Virtools Online Reference

Virtools Dev 3.0 Online Reference

Welcome to Virtools Dev 3.0. You can send comments about any page of this online reference help file by using the comments link at the bottom of each page.

Please note that there is a technical sample for each Building Block illustrating basic use. As long as you have the Virtools Web Player installed, you can view these technical samples by clicking the [image] link that appears just after the BB's description. A new window appears to load the CMO. Note that all tecnhical samples are well commented, and that the only way to read these comments and to play around with parameters or settings is to open the technical sample in Dev.

Virtools Behavior Graphs now have online reference material accessible by double clicking on their icons in Virtools Resources.

  • What's New in Virtools Dev 3.0

  • Learning Virtools

  • Additional Resources

  • Using the Online Reference Viewer

Comments

Copyright © 1999-2003 Virtools SA
All Rights Reserved.
Further Legal Information


What's New in Virtools Dev 3.0

Virtools Dev 3.0 - New Features

Shaders: Programmable Vertex Shaders and Pixel Shaders

Based on DirectX 9.0's Microsoft Effect Framework, Virtools Dev's recent introduction of programmable vertex shaders and pixel shaders greatly enhance the visual quality of your real-time 3D graphics, finally bringing cinematic realism within reach. Virtools Shaders make the most of programmable graphics processors on newer graphics cards, so you can create your own combinations of graphics operations to make customized, optimized special effects in real-time. Shaders now provide Virtools programmers with complete control over the Virtools rendering pipeline.

Action Manager

The new Action Manager is an important means of enhancing productivity for authoring with Virtools Dev. An Action is a specific type of VSL script (Virtools Scripting Language, introduced with Dev 2.5) which performs a predefined task on a selection or parameter. The Action Manager lets you import Actions, organize them, launch them and/or assign them to user-definable keyboard shortcuts in an intuitive user interface.

VSL scripters can now create and share their dedicated tools programmed in VSL and access them in just a few keystrokes, thus greatly boosting productivity. Iterative media modifications, for example, can be easily made to change locations, reset positions, align objects, etc.

NXN alienbrain

Asset management with NXN alienbrain provides a comprehensive teamwork solution for both small or large production teams. Virtools Dev 3.0 now enables you to manage your Virtools projects from A to Z by offering:

  • Integrated rights management, version control and an intuitive “check in/check out” procedure managed directly in the Virtools Dev interface.
  • Easy-to-insert comments and logs for each object to improve archiving, retrieval and overall project management (NXN offers an extension to link alienbrain to Microsoft Project).

Building Blocks

Besides the new Shaders Building Block category outlined above, these new BBs have been added or significantly modified:
  • Web Download: Downloads files from a webserver.
  • Web Get Data: Retrieves web page content associated with a given URL.
  • Cloth System: Creates a draping cloth effect using a spring mass particle system.
  • DX8 Dependency: Retrieves the DirectX8 rasterizer in the Virtools Web Player.

    • Note: DX9, DX7 and OpenGL rasterizers are now included in the Virtools Web Player 3.0.
  • Hardware Level: A new pOut was added that indicates if the composition is currently using
    OpenGL, DirectX5, DirectX7, DirectX8 or DirectX9.
  • Mark System: Added an option to create decal marks and to randomly orientate marks.
  • Ray Intersection, Ray Box Intersection (both in Logics) and 2D Picking (Interface): These three BBs now have the option to output their results in world coordinates or in local coordinates of the intersected object.

Misc Features

  • Obsolete or Invalid Building Block Explorer added to the Schematic Toolbar to facilitate the parsing and replacement of obsolete BBs.
  • Many new variables added to the Variable Manager.
  • Behavior Graph Management added to the Optimization Whitepaper.
  • Double click on .nms files in Virtools Resouces to access its reference material.
  • Runtime Version DLL information for standalone executables.
  • Over 40 new Parameter Operations listed.
  • DX9, DX7 and OpenGL rasterizers are now included in the Virtools Web Player 3.0.

DLL Editor: New Virtools Interface SDK

The Virtools Interface SDK, facilitates the integration of external technology (DLLs), a.k.a. Managers, in Dev's user interface. Complete with an AppWizard to facilitate your coding, this DLL editor now makes it possible to create user interfaces within Dev for your proprietary technology. For example, create a manager to edit animations directly within Dev's GUI interface. (Be sure to check out the CHM files in the SDK folder for more information).

SDK: CK2/VXMATH

  • Template class XArray can have its content aligned into a specific memory boundary (aligned on 16 bytes for example)
  • The VxIndexedCopy function also exists using word indices now.
  • On Windows Platform the VxTimeProfiler class now uses QueryPerfomanceCounter because it returns correct values on Intel processors with SpeedStep technology. Since the QueryPerfomanceCounter adds an important overhead when profiling small chunks of code, a VxRDTSCProfiler class is available which is much more precise, has less overhead but is not "SpeedStep safe" so should only be used for profiling.
  • New manager event : OnRasterizerEvent - from a manager you can be notified of events concerning the current rasterizer, whether it is created, destroyed or resized (CKRST_EVENTS).
    •

    SDK: Render Engine

    • The way objects are rendered has been changed to minimize render states and to avoid sending primitives that are too small (in terms of number of faces) to the video cards. Two new variables control this behavior: CK2_3D\DisableBatching and CK2_3D\BatchingMaxVertexCountToBeBatched.
    • CK3dEntity::AddPreRenderCallback and CK3dEntity::AddPostRenderCallback now have an additional argument to indicate whether the callback will be modifying the rendering pipeline (changing current render states, textures, matrices, etc.) to give a hint to the render engine when sorting the rendering per material.
    • VxDrawPrimitiveData structure was changed to store XPtrSrided members
    • Some enumerations and methods that were not used in the render engine or that could hinder certain optimizations were removed:
      • CK3dEntity::AreRenderChannelsVisible , CK3dEntity::SetRenderChannels
      • VX_MOVEABLE_RENDERCHANNELS,VXMESH_RENDERCHANNELS
      • CKMaterial::SetCallback , CKMaterial::GetCallback
      • CKMesh::AddSubMeshPreRenderCallBack, CKMesh::AddSubMeshPostRenderCallBack
      • CKMesh::SetFaceChannelMask, CKMesh::ChangeFaceChannelMask (Replaced by CKMesh::SetChannelFaceIndices)
    • New classes : CKShader and CKShaderManager were introduced to give access to high level shading languages such as HLSL or CG. The HLSL implementation is given in the sample source code available with this SDK (See Available Source Code).
    Comments


Additional Resources

There are a number of additional resources and ways of getting help for Virtools Dev.

A Sample for Every BB

In the BBSamples folder (Documentation/Cmos). A sample is available for each standard BB.

The Virtools MiniSite

In the Virtools MiniSite (from the Start menu, select Programs > Virtools Dev > Virtools MiniSite) that contains sections on tutorials, elements of the default data resource Virtools Resources, commands you can use with the Virtools Web Player, and large complex demos to show you how to optimize and manage larger compositions..

NOTE: The Virtools MiniSite is installed by default, however if you chose not to install this component you will have to run the Virtools Dev setup.exe again

Help Online

  • at the official Virtools Website (opens a browser window), to register for Virtools Tech Support, to get the latest official Virtools news and to subscribe to the Virtools Newsletter.

  • at The Swap-Meet (opens a browser window), the Virtools Community Web site which contains among other things the Virtools User Forums and where you can subscribe to Virtools Users Discussion list.

    • Comments


Legal Information

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from Virtools.

VIRTOOLS SA (Virtools) PROVIDES THIS MATERIAL "AS IS", WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Virtools may make improvements and changes to the product described in this document (documentation.chm) at any time without notice. Virtools assumes no responsibility for the use of the product or this document except as expressly set forth in the applicable Virtools license agreement or license agreements and subject to the terms and conditions set forth therein and applicable Virtools policies and procedures. This document may contain technical inaccuracies or typographical errors. Periodic changes are made to the information contained herein: these changes will be incorporated in new editions of this online reference.

Windows, Internet Explorer and Visual Studio are registered trademarks of Microsoft Corporation, Navigator and Communicator are registered trademarks of Netscape Communications, 3DS Max is a registered trademark of Discreet, Maya is a registered trademark of Alias|Wavefront, LightWave is a registered trademeark of NewTek. All other brand or product names are the trademarks or registered trademarks of their respective holders.


Installing Virtools Dev, Minimum Requirements

Minimum Requirements

To successfully install and use Virtools Dev, please check that you meet the minimum hardware and minimum software requirements listed below.

Note: Microsoft DirectX 9.0 is provided on the installation CD, should you need them.

Hardware

  • Pentium III or equivalent
  • 128 MB of RAM
  • CD ROM drive
  • Monitor capable of displaying 1024 by 768 in 16 bit color (65536 color/Hi-color)
  • Pointing device (mouse, trackball, etc.)
  • Direct3D or OpenGL compatible 3D graphic accelerator card with 8 MB of RAM
  • Sound card (not a requirement but recommended)

Software

  • Microsoft Windows (95, 98, 98SE, ME, 2000, XP or NT 4.0 (with Service Pack 6))
  • Microsoft DirectX 5.0+ for DirectX compatible 3D graphic accelerator cards (DirectX 8.1+ recommended)
  • Microsoft Internet Explorer 4.0+ (for the Online Reference)

Installing Virtools Dev

You can choose the components of Virtools Dev that you wish to install. If you choose to install all components, you will need approximately 600 MB of disk space.

  1. Insert the Virtools Dev CD.
  2. Follow the on-screen instructions.
  3. If your CD-ROM drive does not automatically run the installation program, manually execute setup.exe in the Dev folder of the Virtools Dev CD-ROM.

Note: If you have previous versions of Virtools software installed on your computer, ensure that you install this version in a new program folder to avoid any potential upgrade problems.

Note: Virtools Dev 2.0 and later use a new file format that is not backwards-compatible with file formats used by previous versions of Virtools products (1.x.x). However, Virtools Dev can open and use files saved by previous versions of Virtools products.


Using the Online Reference Viewer

To open the Online Reference Viewer from within Dev
  • Press F1
  • Select Online Reference from the Help menu

    • Note that you can open the reference page for a behavior building block (BB) directly by

  • Double-cliking the name of a BB in the Building Blocks tab in the top of Virtools Dev
  • Right-clicking a BB in the Schematic and choosing HTML Help

    • The Online Reference viewer contains four tabs for locating and bookmarking information

  • Contents
  • Index
  • Search
  • Favorites

    • Using the Contents Tab

    The Contents tab displays the main sections of the Virtools Dev 2.0 Online Reference as book icons. When you click a book, it displays the first page for that topic and at the same time expands to show a list of all the topics in that section.

    To display a topic from the Contents:

    1. Click the Contents tab to display the Table of Contents.

    2. Click the book icon representing the area in which you need information.
      The page icons below each book represent topics in that area.

    3. Click the page icon for the topic you need.

    Using the Index Tab

    The index is an alphabetical listing of keywords found in each topic. A single keyword may be linked to more than one topic. You may type the first few letters of a subject to jump to an index entry that matches what you are looking for.

    To display a topic from the Index:

    1. Click the Index tab to display the Index.

    2. In the form at the top of the Index, type the subject you need to find or scroll through the alphabetical list to find the term for which you need information.

    3. Click the term, then click Display to see the topic for that term or double-click the term to see its topic. The topic displays in the right pane and may show links to related topics.

    Using the Search Tab

    The Online Reference contains a full-text search engine that creates a database of every word in the Online Reference. You can use the Search tab to find the topics for any word or phrase.

    To display a topic using Search:

    1. Click the Search tab to conduct a full-text search.

    2. Enter the word or phrase for which you want to search, then click List Topics.
      All topics containing your entry are listed.

    3. Scroll through the list to find the topic you want.

    4. Click the topic name, then click Display or double-click the topic name to see the topic.
      You can use the Boolean operators AND, OR, NOT, and NEAR to narrow your search. Enclosing a phrase in quotes ("") searches for that exact phrase.

    Using the Favorites Tab

    The Favorites tab allows you to bookmark pages that you frequently use and come back to them quickly.

    To create a list of favorite help topics

    1. Locate the help topic you want to make a favorite topic.

    2. Click the Favorites tab, and then click Add.

    Further help:

    • To return to a favorite topic, click the Favorites tab, select the topic, and then click Display.

    • If you want to rename a topic, select the topic, and then type a new name in the Current topic box.

    • To remove a favorite topic, select the topic and then click Remove.


Basic Concepts

This section contains the essentials of understanding what Virtools is, and how it works. If you start scripting before reading this section, it is at your own peril!

  • What is Virtools Dev?

  • Elements, Classes, and Object Oriented Design

  • The Elements of a Composition

  • The Virtools Process Loop

  • The Behavioral Engine

    • Behaviors and Scripts

    • Parameters

    • Parameter Operations

    • Attributes

    • Virtools Scripting Language (VSL)

  • The Render Engine

    ***

  • Initial Conditions


What is Virtools Dev?

What is Virtools?

Overview

Virtools is an extensive collection of technologies for 3D visualization and interactivity. The Virtools technologies are broadly grouped as:

  • an Authoring application
  • a Behavioral Engine
  • a Render Engine
  • a Web Player
  • a Software Development Kit (SDK)

An Authoring Application

Virtools Dev is an authoring application that allows you to quickly and easily create rich, interactive, 3D content. Industry standard media such as models, animations, images and sounds are brought to life by Virtools' behavior technologies.

You cannot create models in Virtools Dev; Virtools Dev is not a modeling application. However, simple media such as Cameras, Lights, Curves, interface elements, and 3D Frames (called dummies or helpers in most 3D modeling applications) can be created with the click of an icon.

A Behavioral Engine

Virtools is a behavioral engine - that is, Virtools processes behaviors. A behavior is simply a description of how a certain element acts in an environment. Virtools provides an extensive collection of reusable behaviors in Virtools Dev that allow you to create almost any type of content through the simple, graphical interface of the Schematic editor - without writing a single line of code!

For coders and scripters, the new Virtools Scripting Language (VSL) complements the Virtools Dev Schematic editor by providing script level access to the Virtools SDK.

Virtools also has a number of managers that help the Behavioral Engine perform its duties. Some of these managers (such as the TimeManager) are an internal part of the Behavioral Engine while others (such as the SoundManager) are external to the Behavioral Engine.

A Render Engine

Virtools has a render engine that draws the image you see in the 3D Layout of Virtools Dev. The Virtools render engine can be replaced with a render engine of your own, or customized to fit your specific needs using the Software Development Kit (SDK). Note however that access to the source code of the Virtools render engine is subject to an additional licensing agreement.

A Web Player

Good technology must be easily accessible before it can be considered a great technology. Virtools provides a free Web Player that can be downloaded by anyone - and the download is less than 1 MB!

The Web Player contains a Playback only version of the Behavioral Engine and the complete Rendering Engine. Further information on the Virtools Web Player is available in the Online Reference.

A Software Development Kit

Virtools Dev includes a Software Development Kit (SDK) that provides access to certain parts of the behavior and rendering processes.
With the SDK, you could:

  • create new behaviors (DLLs)
  • modify the operation of existing behaviors
  • write new file importers or export plugins, to support the modeling file format of your choice
  • replace, modify or extend the Virtools Dev rendering engine (subject to a separate licensing agreement)

VSL also provides an interface to the SDK from within Dev, so you can easily and quickly test new ideas and implement custom code without implementing custom DLLs.

These are just examples - your creativity is the only limit to how far you can go!


Elements, Classes, and Object Oriented Design

Overview

Virtools Dev organizes elements into classes. Elements include the media you bring into Virtools Dev (models, Sounds, Textures, etc.), the things you create in Virtools Dev (such as Curves, Places, Scenes etc), and data such as Parameters, Attributes and Scripts.

Essential topics in this section, which concentrates on the Behavioral Object branch of Virtools class hierarchy, include:

  • How Virtools Dev classifies media.
    For example, there is a Light class of objects in Virtools to which all Lights belong. Each light is an instance of the Light class, and has characteristics such as its color and its range.

  • Why certain operations are only possible on certain elements (classes).
    For example, only Characters can use character animations

  • Why other operations can be applied to all elements.
    For example, all elements can be activated or deactivated.

As stated, this section presents the Behavioral Object branch of Virtools class hierarchy, which is sufficient for most users. However, you can find a complete description of the Virtools class hierarchy in the SDK documentation.

Object Oriented

Virtools Dev takes an Object Oriented approach to building a composition (a CMO file). That is, every element is of a unique type where each unique type is described by a class definition. Elements are controlled using methods encapsulated within behaviors (BBs) and parameter operations (paramOps). Each class in Virtools Dev is called a CKClass.

Figure 1-1 The Behavioral Object branch of the Virtools Class Hierarchy

For example, there is a CKClass called CKCharacter. Only CKCharacters can use the behaviors specifically designed for characters (such as the Character Controller BB).

The object oriented nature of Virtools Dev means that everything you import into Virtools Dev (the elements in the form of models, Sounds, etc.) is an instance of a CKClass. Also, anything that you create in Virtools Dev (from a Camera to an Array) belongs to a CKClass as well. Figure 1-1 illustrates the Virtools Dev class hierarchy for behavioral objects.

Inheritance

One advantage of using a class hierarchy is the principle of inheritance. That is, any element has its own unique characteristics and the element inherits the characteristics of all of its ancestor (parent) classes.

For example, the class CKLight descends from:

  1. CK3DEntity, which descends from

  2. CKRenderObject, which descends from

  3. CKBeObject

Therefore, a light has special characteristics that apply only to objects of the CKLight class - characteristics like:

  • the type of light (point, directional, etc.),

  • the color of the light (white, red, etc.), and

  • the range over which the light is visible.

Such characteristics can be changed via the Light's setup (in Author mode), or a behavior building block (at run-time, i.e. Play mode).

Secondly, a light is a 3D Entity, which means it has inherited the characteristics of a 3D Entity - characteristics like position and orientation in the 3D space. Since a light is also a 3D Entity, any behavior that can be applied to a 3D Entity can also be applied to a light.

Thirdly, a light is a Render Object, which means that it can be rendered (seen in playback). Since a light is also a Render Object, any behavior that can be applied to a Render Object can also be applied to a light.

Finally, a light is a Behavioral Object, which means that it can have a behavior attached to it (some Virtools Dev classes, such as classes that store internal data only, can not have behaviors attached to them). Since a light is also a Behavior Object, any behavior that can be applied to a Behavior Object can also be applied to a light.

Specialization

Virtools Dev supports the specialization of behaviors so that the behaviors can be optimized for a specific task (also known as polymorphism). For example, moving a 3D Frame is much simpler than moving a Character so the behavior for moving a 3D Frame can be optimized for the simpler task.

Optimized behaviors reduce the computing time for a given task resulting in a composition that is smaller, more responsive to user input, and that renders at an acceptable frame rate.

Aggregation

Virtools Dev supports aggregation, the logical relationship between elements where a first element is a part of a second element yet both elements are distinct.

For example, if you look at the 3D Object Setup in Figure 1-2, you can see a column labeled Object Meshes. A 3D object may have several meshes, although only one mesh may be active at a time.

Figure 1-2 3D Object Setup with Mesh column circled

If you look at the Mesh Setup in Figure 1-3, you can see a column labeled Materials Used. A mesh may have several materials, several of which may be active at a time.

Figure 1-3 Mesh Setup with Materials column circled

If you look at the Material Setup in Figure 1-4, you can see a field labeled Texture. A material may have only one texture.

Figure 1-4 Material Setup with Texture circled

Therefore, the elements that describe a 3D entity (whether it be an object, a character, etc.) are related yet each element remains independent. In this example, a Texture is part of a Material, a Material is part of a Mesh, and a Mesh is a part of a 3D Object.

Because each element remains independent, the characteristics of each element (in this example, the object's mesh, material, and texture) can be changed quickly and easily. In fact, the entire element can be exchanged with another compatible element!

For example, you could change a 3D Object's Mesh, Material, or Texture - or any combination of these without changing the fact that the 3D Object exists.

NOTE If you change the mesh on a Character, it is very likely that your Animations will no longer work as expected.

Run-time Aggregation, the Scene Hierarchy

A Scene is the set of elements that are currently active at runtime. The elements within a Scene are organized into a scene hierarchy.

Virtools Dev supports a special form of aggregation within the scene hierarchy. At run-time, relationships between elements can be established via Set Parent and Add Child (both in 3D Transformations/Basic). Run-time aggregation allows you to establish relationships between an arbitrary set of 3D Entities, typically for the purpose of simplifying the application of transformations to the set of 3D Entities.

For example, even though it would be easier to do in a modeling application, using Set Parent and Add Child you could construct a car as a hierarchy of 3D Entities: a car has doors, a body, and wheels. Once the hierarchical relationship is established, transformations on the car automatically transform the children of the car: the doors, body, and wheels.

NOTE Set Parent and Add Child establish relationships within the scene hierarchy only and not within the CKClass hierarchy. If Initial Conditions are set on the affected elements before Set Parent or Add Child are activated then, when you click Reset IC, the relationships are deleted.

Sharing Elements

Virtools Dev's support for aggregation allows you to share elements such as Sounds, animations, Meshes, Materials and Textures throughout your composition.

For example, two chairs could share the same Mesh, Material, and Texture - the chairs would appear to be identical and would differ only in name. However, the chairs could have the same Mesh, but have different Materials anbd Textures - the chairs would then have the same form, but look different.

Sharing elements can greatly reduce file size and the workload for CPUs and graphic cards. Reducing the number of elements in a composition also makes managing the development of your composition easier.

Association

Association allows Virtools Dev to create a logical relationship between elements that are not directly related through a parent-child relationship in the CKClass hierarchy. Objects that are associated communicate with each other but are distinct.

For example, a Character is often associated with a Group of 3D Entities for the purpose of collision detection, management and prevention.


Virtools Class Hierarchy - Behavioral Object Branch

Click an element below to go to the page for that Behavioral Object.

See also the following two pages of the Concepts book:

  • Elements, Classes, and Object Oriented Design
  • The Elements of a Composition

    • Comments


The Elements of a Composition

Overview

Below you can see some of the elements typical in a Virtools composition. Indentation indicates that the indented label is a child of the closest previous level of indentation, following the behavioral object branch of the Virtools class hierarchy principal introduced in Elements, Classes, and Object Oriented Design.

For example, a 2D Entity and a 3D Entity are children of RenderObject. A 2D Frame is not a child of RenderObject but a 2D Frame is a descendent of RenderObject.

Elements of a composition, according to type and arranged alphabetically

BeObject - an object to which a behavior can be applied
 | RenderObject - an object that is visible when rendered
 |  | 2D Entity - an object that has width and height but no depth
 |  |  | 2D Frame - a 2D Entity with visible parts
 |  | 3D Entity - an object that has width and height and depth
 |  |  | Character - a type of 3D Entity that acts as an intelligent entity, directed by the user or by software
 | Objects that may be visible but usually are not
 |  | Camera - an object that defines a point of view
 |  | Curve - a set of 3D Entities that define a curve in 3D space
 |  | Grid - a 2D data set whose value depends on 3D coordinates
 |  | Light - an object that provides illumination
 | Objects that are not visible (abstract, data sets, associations)
 |  | Array - a data set expressed as a table
 |  | Group - an arbitrary collection of objects with no restriction as to type
 |  | Level - the parent object of the entire composition
 |  | Material - the surface characteristics of a mesh
 |  | Mesh - the set of vertices that define the shape of an object
 |  | Place - a collection of geographically related objects
 |  | Scene - a collection of temporally related objects
 |  | Sound - a sound stored in digital form
 |  | Texture - an image used to provide fine detail on the surface of an object

The Behavioral Object (BeObject)

While behaviors are the central concept in Virtools Dev, they are of no use if they are not attached to elements. Note that all entries in the simplified view of the Virtools Dev class hierarchy descend from the Behavioral Object (BeObject) class. Objects instantiated from these classes are the objects that can have behaviors attached to them. BeObjects can have behaviors but are not required to have behaviors.

When a BeObject has behaviors attached, it is said to be the owner of these behaviors. All behaviors are attached to one and only one BeObject.

NOTE The owner of a behavior is not always the target of the behavior. The behaviors attached to a BeObject may change the owner or they may change other objects (target).

Level

A Level can be described as:

  • the global container for all objects of the composition

  • the root of all elements in a composition

  • the ancestor or parent of all elements in a composition

There is only one level in a CMO. The Level can contain one more Scenes and zero or more Places to organize your composition into manageable portions.

A Level is a BeObject. Therefore, behaviors and attributes can be attached to the Level. Level scripts are typically used to manage Scenes, Places and other elements needed across several scenes (such as Arrays).

NOTE Scripts attached to the Level are automatically attached to all Scenes.

Scenes

A Scene in Virtools Dev is just like a scene in the movies:

  • only one Scene is active at a time,

  • only the elements in that scene are active

  • only active elements are captured by the camera (processed by the Behavioral Engine in Virtools).

The elements that are not members of the active scene are, by definition, inactive. They are not rendered and their scripts are not processed.

Therefore, scenes are the perfect way to segment compositions into large scale narrative elements or large time-based periods. Scenes are very useful when working in collaboration with other people: each person can work on a specific scene, which can then be saved and merged into one CMO.

The Level Scene (containing all the objects of the Level) is made the active scene of the Level at startup. When a new scene is made active (started), the previously active scene is automatically deactivated.

A Scene is a BeObject. Therefore, behaviors and attributes can be attached to the Scene.

Scenes contain references to elements and not copies of elements or the elements themselves.

Places and Portals

Just as Scenes are a way to organize narrative segmentation within a Level, Places are a way to organize space segmentation in a Level or Scene. There may be zero or more places in a Level. There is no specific link between Scenes and Places.

Places are part of the 3D Entity hierarchy and may contain zero or more 3D Entities. Each Place is deemed the Parent of all 3D Entities within the Place.

Places and Portals are used to optimize the rendering phase. The decision of what to display is done through the active camera. When the Portal system is active (through the "Portal Management" building block for example ), the rule is the following:

  1. Before each rendering process, the list of Places spatially containing the active camera (including the view frustum) is computed using the places bounding boxes.

    2. These Places, and all the Places that have a Portal with these Places (and Portals with these Places, etc.), are considered to be potentially visible and processed by the renderer.

  2. If an element is not a member of one of these places, the element will not be rendered. The element is immediately considered "out-of-view" (even though the element may be active and its behaviors may be executed).

  3. If the Portal system is not active, there is no optimization of the rendering by Places and Portals (every 3D Entity is considered potentially visible and only a hierarchical culling is done), but Places may still be used to hierarchically organize 3D Entities for other purposes.

Places are also very useful when working in collaboration with other people: each person can work on a specific Place, which can then be saved and added to a CMO.

A Place is a BeObject. Therefore, behaviors and attributes can be attached to the Place.

Abstract Elements

Abstract Elements are data structures used by Virtools Dev to store information and to describe relationships between elements.

Groups

Groups are the simplest and most powerful organizational entity of Virtools Dev. Groups are ordered lists of Behavioral Objects that can implement any logical association that may be required and are not restricted to containing elements of the same CKClass or type.

Groups can be created in Author mode or by BBs at run-time. Groups can be reordered, iterated over, etc. - many standard BBs are provided for group management.

A Group is a BeObject. Therefore, behaviors and attributes can be attached to the Group. Groups can be part of other Groups.

Arrays

Arrays are simple tables containing cells organized as rows and columns. Arrays are organized as typed columns (all the elements of a column must have the same type). Arrays support five data types:

  1. Integer
  2. Floating Point

  3. String

  4. CKObject

  5. Parameters

Arrays can be created in Author mode or by BBs at run-time. Arrays can be sorted, filtered, searched, iterated over, etc. - many standard Building Blocks are provided for array management.

Arrays are themselves Behavioral Objects, so they can have behaviors attached to them.


The Virtools Dev Process Loop

The Virtools Process Loop

Overview

The Virtools process loop, often referred to as a Frame or a Rendering Frame, is a repetitive process that occurs when you (or a User) play a composition. Understanding the process loop will help you to create efficient scripts and smooth running compositions with a satisfactory frame rate.

A satisfactory frame rate is usually defined as a frame rate that supports effective real-time visualization. Real-time visualization starts with a minimum of 15 images per second, with total immersion beginning at 60 frames a second. Therefore, as an author, you should always attempt to maintain a frame rate of at least 30 frames per second (approximately the same rate as television) with a goal of 60 frames per second or more.

Virtools is a real-time engine: it allows any behavior to react constantly and consistently to its environment, including the User.

When a composition plays, Virtools repeatedly performs the Process Loop - always performing the same steps in the same order until a composition is stopped or reset.

Figure 1-6 The Virtools Dev Process Loop

The duration of one process loop is commonly called a Frame. The frame rate is the number of times the process loop is performed each second and is measured in Frames Per Second (FPS). The frame rate is constantly displayed in the Virtools Dev interface, adjacent to the Play/Pause button at the bottom right corner of the screen.

Figure 1-7 The bottom right corner of the Virtools Dev interface. The FPS display is just to the right of the Profiler.

The process loop should execute as quickly as possible:
  • A high frame rate provides rapid response to the User's input, increasing the user's perception of the quality of the composition

  • Rendering the image as often as possible increases the perceived quality of animations and visual effects. Note that rendering the image faster than the refresh rate of the display does not enhance the quality of the visuals and may, in some cases, actually degrade the quality of the visuals.

To maximize the frame rate, you must minimize the amount of behavior processing performed in each frame. Never try to do more in a given frame than the minimum necessary to maintain the immersive experience. When constructing scripts, you should try to:
  • divide tasks into sub-tasks and only process the minimum number of sub-tasks per frame.

  • structure your scripts such that the frame rate stays relatively constant.

  • avoid scenarios where, in response to user input, a large script must be processed in its entirety in a given frame. The frame rate is likely to noticeably drop and the user will be reluctant to provide that same input again.

Some BBs, such as Character Curve Follow BB are designed to operate in an incremental manner. Rather than following the designated Curve from the starting point to the ending point in a single frame, Character Curve Follow BB moves the Character along only a small portion of the Curve in a given frame - spreading the work across many frames and increasing the quality of the immersive experience.

As shown in Figure 1-6, there are two parts to the process loop:

  1. Processing Behaviors, and

  2. Rendering the Scene.

Processing Behaviors

Behavioral processing creates the interactivity within your composition. Behaviors can be applied to almost every element in Virtools. During behavioral processing all active behaviors are executed, one after the other, using a sophisticated prioritizing scheme.

Each behavior, when executed, may activate other behaviors through behavior links. Behavior links have a link delay where the link delay is measured in Frames (process loops). The Link Delay can be:

  • 0 - propagate the activation within the current frame

  • 1 - propagate the activation in the next frame

  • n - propagate the activation in the nth frame after the current frame

As mentioned before, various managers help the Behavior Engine in its work. The managers perform their tasks either at the start of behavioral processing or at the end of behavioral processing - just before rendering.

In general, you do not need to know how or when these managers work, with one exception: the MessageManager. Messages are sent at the end of behavioral processing and are received in the following frame. Therefore, interactions driven by messages always experience a one frame delay between the frame in which the message is sent and the frame in which the message is received.

A complete description of all Virtools managers is available in the Virtools SDK.

Rendering

Rendering displays the composition and is performed by a separate rendering engine. The engine can be chosen by the User and depends on the capabilities of their graphics card and operating system; however you can force a certain rendering engine or disable certain features.

You can choose the rendering engine for Author and Play modes while working in Virtools Dev by choosing General Preferences from the Options menu, and selecting the Rendering tab.

Typically, rendering is the most time intensive portion of the process loop and is highly dependent on the capabilities of the underlying hardware.


The Behavioral Engine - CK2

Overview

The Behavioral Engine implements behavioral processing and is the central component of Virtools. Also known as CK2 (hence the CK references you often see in the interface, such as CKID, CKClass and so on), the Behavioral Engine is what makes Virtools so flexible.

What does CK2 do? CK2 executes your compositions, processing Scenes and managing all interactions between the User and the elements of your composition. CK2 also processes the elements of your composition that have behaviors applied to them – that is, the Behavioral Objects.

Once all behaviors have been processed for a given frame, CK2 provides the appropriate information to the render engine (CK2_3D) so that the results of the interactivity can be displayed to the User.

When a composition is played, the following series of tasks is performed.

NOTE To properly interpret the following series of tasks (the algorithm) you must take note of the number level of each statement. Subtasks that must be performed as part of the prior sequence of tasks are part of the same major number. For example, task 3.1.1 states "For each BB attached to Start that has not yet been activated, activate the BB with the highest priority". This means that all subtasks (3.1.1.1, 3.1.1.2 and their subtasks) must be performed to complete task 3.1.1. The "For each" portion of the task description means that this task (and all subtasks) is performed repeatedly until the required condition - that all BBs attached to Start have been activated - is met.

1. For each active element within a Level, sort the elements in priority order to establish the element processing order.

2. For each element, the scripts applied to that element are sorted in priority order to establish the script processing order for that element.

3. For each element, from the highest priority to the lowest priority, process the highest priority element remaining.

3.1. For each script attached to the currently processing element, process the highest priority script remaining.

3.1.1. For each BB attached to Start that has not yet been activated, activate the BB with the highest priority.

3.1.1.1. Process the BB, calculating pOuts, activating any bOuts, and sending any messages.

3.1.1.2 For each bOut that activates a behavior link.

3.1.1.2.1 If the behavior link has a delay of 0 then activate and process the next BB. Continue in this manner until all BBs in this part of the Script are processed or the behavior link has a delay greater than 0.

3.1.1.2.2 If the behavior link has a delay greater than 0 then add the BB to the stack for processing in the required frame. For example, if the link delay is 1, then the BB is processed in the next frame. If the link delay is n, then the script is kept active and the BB is processed in the nth frame after the current frame.

NOTE The Level is always active and is the highest priority element in every frame. All currently inactive elements are ignored in the remaining tasks.

Processing continues in the current frame until all BBs are processed or the link delay is greater than 0.

When all behavioral processing is complete, CK2 provides information to the rendering engine to draw an image on screen, the image is rendered, any link delays that are greater than 0 are reduced by 1, and behavioral processing starts again.

You can watch behavioral processing in action by activating Trace mode in the Schematic. When the composition is played, the sequence of activations and BB processing are highlighted in red in the Schematic.

IMPORTANT: If a BB loops internally (such as the Wait Message or Stop & Go BBs), then the execution order for that BB does NOT follow the algorithm outlined
above. Instead, the execution order is controlled by the Priority assigned to this BB. In the absence of explicit prioritization by the author, the execution order is indeterminate. So for example, if there are two possible activation flows, and there is no Priority on the BBs that the bLinks lead to, it is impossible to predict which flow will activate first. Activation flow continues until complete, when the next flow is processed. Therefore, to ensure sequential execution within a script, it is vital to specify relative priorities with internally looping BBs.

Behavior Loops

A behavior loop is formed when a series of BBs (and/or BGs) are connected by bLinks in a manner that causes the BBs to be activated or triggered in a repetitive fashion.

In other words, a behavior loop is the visual representation of a repetitive operation. A repetitive operation is also known as an iteration and the processing of repeating an operation is also known as iterating.

In any implementation of a repetitive operation, a significant concern is to ensure that there is an acceptable upper limit to the number of times that the operation repeats. In other words, there needs to be a mechanism to ensure that an operation is not repeated indefinitely.

Virtools Dev allows you to define the maximum number of operations that may be performed in a single Frame via the Max Behavioral Iterations setting in the Schematic.

NOTE The default value for Max Behavioral Iterations is 8000. The value of Max Behavioral Iterations is saved with the composition.

Any behavior loop may have a cumulative delay of zero, as long as the loop is not constantly active and as long as the number of iterations in a frame does not exceed the value of Max Behavioral Iterations. If the number of iterations in a frame exceeds the value of Max Behavioral Iterations then the behavioral engine assumes that an infinite loop has occurred and processing is halted.

For example, Array and Group iterators (Logics/Array and Logics/Groups) often have a loop delay of 0 so that all elements within the Array or Group are operated on within a single frame.

However, always keep in mind that (to maintain a consistent frame rate) you want to divide the processing to be performed into the minimum amount necessary per frame. Therefore, unless absolutely necessary, a behavior loop should have a cumulative delay of at least one frame. The actual behavior loop delay can be any positive value in the range of 0 to 32767.

NOTE Looping BBs (such as Timer (Logics/Loops)) that are time-based require a cumulative loop delay of 1 frame or the BB automatically changes to frame-based processing.

Priority

Once CK2 has sorted which elements are active, how does CK2 know which element to process first? The answer lies with that element's priority: the highest priority is processed first.

You can set the priorities for Behavioral Objects, Scripts and BBs. The priority of a Behavioral Object and the priority of a Script are set in the Level Manager. The priority of a BB is set in the Schematic.

If one or more elements have the same priority, then the processing order is random.

Figure 1-9 Priority

With respect to Figure 1-9 , note that both Counters (Logics/Loop) and Priority (Logics/Streaming) are all connected to Start with a 0 frame delay. Therefore, the Behavioral Engine must determine which BB to activate first based on the priority of each BB.

BB Name | Processing Priority
All But One | 50
Counter (at top of Figure 1-9) | 20
Counter (at bottom of Figure 1-9) | 0

The processing order for the first frame is as follows.

1. All But One (Logics/Streaming) at priority 50: the top bIn (In 0) is activated by Start then the lower two bOuts (Out 1 and Out 2) are activated

2. The top Counter (at priority 20): counts 2000 times then activates All But One (following a path with a 0 frame delay bLink)

3. All But One (at priority 50): the middle bIn (In 1) is activated by Start then the outer two bOuts (Out 0 and Out 2) are activated

4. The bottom Counter (at priority 0): counts 2000 times then activates All But One (following a path with a 0 frame delay bLink)

5. All But One (at priority 50): the lowest bIn (In 2) is activated by Start then the upper two bOuts (Out 0 and Out 1) are activated

At the end of the first frame All But One has been activated three times – probably not the expected result.

NOTE As a general rule, when multiple BBs can activate the same BB (as in this example), the receiving BB should have a lower priority than the BBs that can activate it to ensure that all prior BBs are processed first. See also the note above about internally looping BBs and the process loop.


Behaviors and Scripts

Overview

A Behavior is expressed as a script - the visual representation of a behavior, applied to an element, as represented in the Schematic.

A script is composed of two parts - a header and a body. The script header displays the name of the script and the owner of the script. The script body is composed of the Start and one or more BBs, BGs, paramOps, Parameters, bLinks, pLinks, comments, etc.

Figure 1-10 A Sample Script

Figure 1-10 illustrates a sample script containing a BG (Rotate 1s) and a BB (Timer). Note the differences in the font color and font weight between the BG and the BB.

Behavior Building Block (BB)

The fundamental mechanism used to implement behaviors is the BB. BBs are a visual representation of a software element known as a function, a ready-to-use solution to a known task.

Interpreting a BB Symbol

BBs come in various rectangular sizes. You can see some different types of BBs below.

Figure 1-11 Different types of Building Blocks

Behavior Input, bIn

A BB typically has at least one Behavior Input (bIn) – although there are a few exceptions (BBs that operate in Author mode, e.g. Create Blended Animation (Characters/Animation)). bIns are always located on the left side of the BB. A BB starts processing when the BB receives an activation at a bIn.

Figure 1-12 Behavior Inputs

Behavior Output, bOut

BB often has at least one Behavior Output (bOut) – although there are numerous exceptions. bOuts are always located on the right side of the BB. bOuts are activated at the end of processing within the current frame. Activation flow follows any attached Behavior Links.

Figure 1-13 Behavior Outputs

Behavior Link, bLink

BBs are connected by Behavior Links (bLink) that define the order in which BBs are processed. The sequence of BB processing is called the activation flow where activations propagate across bLinks.

Every bLink has a Link Delay that specifies when CK2 should process the BB at the end of the bLink. The Link Delay can be 0 (meaning that the BB is processed in the current frame) or n (meaning that the BB is processed in the nth frame after the current frame).

Figure 1-14 Two bLinks - the left link has a link delay of 0, the one to the right 10

Parameter Input and Parameter Output

BBs typically have Parameters, either in the form of Parameter Inputs (pIns) above the BB that receive data or Parameter Outputs (pOuts) below the BB that transmit data, as you can see in Figure 1-15. Parameters are discussed in more detail in a later section.

Figure 1-15 pIns and pOuts

Target Parameter

A Target Parameter is a special type of pIn used to explicitly identify the element affected by the BB.

When a BB is attached to an element, that element becomes the owner of the Behavior. Typically, a BB attached to an element is implicitly targeted at the owner of the Script.

For example, Translate (3D Transformations/Basic) normally modifies the position of its owner. However, you may want a BB to affect a different element than the owner. In this case, you must explicitly target the BB at a different element.

Alternatively, you may attach a Behavior to an element of a different type than the type supported by the Behavior (for example, you can attach a Rotate (3D Transformations/Basic) behavior to a texture). A Target Parameter is automatically generated by Virtools Dev in the case of an incompatible class.

A BB is only targetable if there is a “T” in the targetable column (between the “Apply to” and “Description” columns) within the Building Blocks window.

Figure 1-16 The Targetable column of the Building Blocks window

If a Target Parameter does not already exist on a targetable behavior, a Target Parameter can be added by selecting “Add Target Parameter” from the context menu. A new pIn is created as the left-most pIn. A Target Parameter input is identified by a pair of small squares (rather than the usual single small triangle for a regular pIn).

Figure 1-17 A BB without then with a Target Parameter

C, S, and V

Some BBs are marked with one or more of the letters C, S or V in the lower left corner.

A "C" in the lower left corner means the BB has a Custom Dialog Box used to configure complex parameters (e.g. Animation Synchronizer (Characters/Animation))

Figure 1-18 Animation Synchronizer Custom Dialog Box

A "S" in the lower left corner means the BB has Settings. Settings typically control which parameters are processed by the BB or how the parameters are processed by the BB.

Figure 1-19 After editing Settings, only 3 bIns are now calculated

For example, Mouse Waiter (Controllers/Mouse) normally calculates 8 bOuts. You may only require 4 of these bOuts so you can edit the Settings to calculate only the 4 bOuts you require, thus saving valuable processing time.

Or, you may require a BB such as Linear Progression (Logics/Loops) to be frame based rather than time based. You can choose frame based processing via the BB’s Settings.

Figure 1-20 Linear Progression Settings dialog box

A "V" in the lower left corner of the BB means that the BB has a variable configuration. That is, you can do one or more of the following:

  1. add bIns,

  2. add bOuts,

  3. add pIns,

  4. add pOuts,

  5. change some or all of the types of the pIns and/or pOuts.

Check the individual documentation for a BB in the Online Reference to determine exactly what can be changed.

Figure 1-21 Parameter Selector, a Variable BB

Messages

A BB may have message icons, meaning that the BB sends or receives messages. Typically, messages are used to signal a change in state, to request that some task be performed, and to signal that some task has completed.

NOTE There is a one frame delay between sending and receiving a message. See “The Virtools Dev Process Loop” for more information.

Figure 1-22 A BB that sends messages

Figure 1-23 A BB that receives messages

BB Processing

You should always check the individual Help page from the Online Reference to see precisely how a BB works. There are three kinds of BB that are processed at run-time; that is, in Play mode.

  1. Single Action: the BB completes processing within the current frame. A Single Action BB can stand alone or be part of a behavior loop. Example: Set Fog (World Environments/Global).

  2. Internally Looped: the BB is turned On and the BB is activated every frame until the BB is turned Off. Example: Keyboard Controller (Controllers/Keyboard).
    3. Note that for internally looped BBs you must pay attention to priorities for activation flow.

  3. Externally Looped: the BB completes one step in the BB’s process loop within the current frame. If the Author wants the BB to operate in the typical manner, an external activation feedback loop is required. Example: Bezier Progression (Logics/Loops).

NOTE An externally looped BB does not require that an external activation feedback loop be present. It is possible to construct a Script in a manner such that the external activation feedback loop is not required.

There are also a few BBs that are not activated at run-time, but when they are attached to an element. An example of such a BB is Create Nodal Path (3D Transformations/Nodal Path).

Figure 1-24 Create Nodal Path BB

Behavior Graph (BG)

A Behavior Graph is an author-defined behavior composed of one or more of BBs, Parameter Operations, etc. At first glance, a BG can look almost exactly like a script. However, a BG is distinct from a script because the author of the BG deliberately encapsulated the behavior. BGs encapsulate a behavior in such a manner that the BG can be saved and reused.

One of the most powerful features of Virtools Dev is this ability to capture interactivity in a reusable form. Behavior reuse can lead to amazing productivity gains!

Virtools Dev treats a BG exactly the same as a BB. A BG can be attached to an element in the same manner as a BB. A BG can even be considered an Author-defined BB that, to an Author, works in exactly the same way as a BB – a BG can have pIns, pOuts, bIns and bOuts. A BG can be considered an advanced BB constructed to perform a specific task beyond the scope of the BBs provided in Virtools Dev (for example, a third person camera for a car racing game).

NOTE Any time the Virtools Dev documentation refers to using a (Behavior) Building Block or a BB within a composition, the reader can substitute Behavior Graph or BG.

Figure 1-25 A Collapsed and then expanded Behavior Graph (BG)

If you compare the image of the closed BG with BB images already presented above, you will notice the differences in the font and weight used that helps to distinguish between a BG and BB.


Parameters

Overview

A parameter consists of a name (pName), a type (pType), and a value (pValue). Parameters are the Virtools Dev equivalent of variables in traditional programming.

Parameters are used to transfer data across Parameter Links (pLinks):

  • between behaviors - from Parameter Outputs (pOuts) to Parameter Inputs (pIns)

  • between Parameter Operations (paramOps)

  • between paramOps and pIns

  • between paramOps and Local Parameters

Parameters can also be used to assign values to an element's Attributes.

Parameter Types

The type of a parameter defines the kind of data that a parameter can properly hold. Parameters can be broadly grouped as:

  1. References or Pointers

    2. The parameter identifies an object instantiated from the CKClass hierarchy (for example, a 3D Entity, an Animation, a Script, etc.)

  2. Values

    3. The parameter contains a data value (for example, a Color, a Keyboard Key, an Integer, etc.)

  3. Enumerations

    4. The parameter's value is constrained to a range of predefined values (for example, the Operators supported by Mini Calculator are constrained to +, -. /, * )

  4. Special
    The parameter does not fit in the prior categories. There are only three such parameter types, Reflected Object, Obstacle and Floor.
For a more detailed description of parameter types, see the SDK documentation.

Parameter Input, pIn

pIns are the arguments for Behaviors and paramOps - the values that control how they work. pIns are represented by the small triangles on top of a BB, a BG, or a paramOp as you can see in Figure 1-26. A pIn has a source for its pValue, typically a Local Parameter. pIns do not store their value between activations.

Figure 1-26 pIns for a BB and for a paramOp

Parameter Output, pOut

When Behaviors or paramOps have finished their processing, they typically produce pOuts. pOuts are represented by the little triangles on the bottom of a BB, BG, or a paramOp. pOuts can have one or more destinations (via pLinks) that are updated as soon as the value of the parameter has changed (the pValue is pushed toward the destination(s)). pOuts store their value between activations.

Figure 1-27 pOuts for a BB and for a paramOp

Parameter Link, pLink

A Parameter Link is a link that propagates a pValue from a pOut or a Local Parameter to a pIn. Unlike Behavior Links, there is no link delay for Parameter Links. Parameter Links are represented in the Schematic by dashed lines.

Local Parameter

A Local Parameter is a parameter represented by a small rectangle - usually located above a pIn. Local Parameters are data buffers that store values until their value is requested across a parameter link. Local Parameters are normally, but not always, linked to pIns by a pLink.

Figure 1-28 Local Parameter attached by Parameter Link to BB

NOTE Two unique Local Parameters are allowed to have the same name. However, this practice is not recommended due to the potential for confusion. For instance, when you copy and paste a Local Parameter, you copy the Parameter’s name, the Parameter’s type and the Parameter’s value to a new local Parameter: these two Parameters are different, even though they have the same name (due to the copy and paste operation). You are encouraged to use unique names for each Parameter that you create.

This

This is a special local parameter that refers to the owner of the script. When you create a This parameter in a script, it automatically sets its value to the identity of the owner of the script.

Parameter Shortcuts

Parameter shortcuts are used to:

  • simplify your scripts by reducing the number of pLinks

  • share parameters across script boundaries

Parameter shortcuts are represented by arrow icons, as you can see in Figure 1-29.

Parameter shortcuts are created by copying a pOut (via the context menu) then performing a Paste as Shortcut (via the context menu).

Copying and pasting a shortcut creates a second shortcut that has the same source as the initial shortcut. Thus, all copied shortcuts point to the same source and have the same name (pName), type (pType), value (pValue) and identifier at all times (CK_ID).

Figure 1-29 A Parameter Shortcut Source and Target symbol


Parameter Operations (paramOps)

Overview

Parameter Operations (paramOps) are simple operations performed on a single parameter or performed between a pair of parameters. A paramOp is represented in the Schematic as a standard sized block with a name, two pIns and one pOut (see Figure 1-30).

Figure 1-30 3 different paramOps

  1. Data retrieval

    2. retrieves information from the Behavioral Engine (e.g. the mouse position)

  2. Mathematical operation

    3. (e.g. multiplication, sine, etc.)

  3. Type conversion

    4. Converts one type of parameter into another type so that the data is in the desired form. For example, a floating point value can be converted to a text string for presentation in 3D Layout.

paramOps can be just as useful as building blocks when creating scripts in the Schematic view. Certain operations, especially some requests, can only be done by performing a paramOp.

NOTE Type conversion can be in the form of a Parameter Operation Link - the default paramOp icon is not displayed, the Parameter Operation Link is drawn in a different color than standard pLinks and the word Convert is displayed along the link.

Parameter Notation

Virtools Dev uses the following notation to describe paramOps in written form.

For binary operations (operations with two pIns), the syntax is

  • Result or Output Operation Type Input1 Input2
For unary operations (operations with one pIn), the syntax is
  • Result or Output Operation Type Input1
In all cases, the syntax is strictly defined as
  • <ptype> paramOp <ptype> <ptype>
For example:
  • <Vector> Multiply <Float> <Vector>
represents a Multiply Operation that produces an output result of pType <Vector>, using inputs of pType <Float> and pType <Vector>.

Values can also be associated with the pIns and pOut.
  • <Float=50.0> Multiply <Float=10.0> <Int=5>
paramOps can be used:
  • to perform binary operations

    C=A*B
    V3 = Angle(V1, V2)
    V2=f*V1
  • to perform unary operations

    C=sin(A)
    C= ABS(A) get the absolute value of A
  • to convert one type of parameter to another

    <Float> Set Value <Integer>
    <3D Entity> Set Value <3D Object>
  • to retrieve information about an object

    <Float> Get Radius <3D Object>
    <Float> Magnitude <Vector>
    <Vector> Get Position <3D Entity> <3D Entity>
    <CharacterBodyPart> Get BodyPart <Character> <String>

paramOps and Behaviors

The processing of paramOps and BBs occurs in different ways.

paramOps are not activated in the same manner as BBs. paramOps do not have a bLink structure that supports activation. Instead, paramOps are only calculated when needed, that is when a BB or another paramOp requests the result of a paramOp. If the value of a paramOp’s pOut is requested:

  1. the paramOp is triggered
  2. the value of the pOut is calculated and updated
  3. the value of the pOut is returned to the requesting pIn and pushed toward any other destinations that may exist for that pOut
paramOps also differ from BBs as follows:
  • paramOps do not have any settings.

  • paramOps may be created in any script attached to any type of object, the restrictions within BBs that they may only be attached to objects of a certain CKClass do not apply.
However, paramOps can be directly synchronized with the activation flow by using Op or Identity (both in Logics/Calculator). See “Calculating a Value at a Specific Moment” below.

Advanced paramOps

Order of pIns

The relevance of the order of inputs follows normal mathematical conventions, that is

<Float=50.0> Multiply <Float=10.0> <Int=5> is equivalent to <Float=50.0> Multiply <Int=5> <Float=10.0>

but

<Float=2.0> Divide <Float=10.0> <Float=5.0> is not equivalent to <Float=0.5> Divide <Float=5.0> <Float=10.0>

Calculating a Value at a Specific Moment

If you wish to calculate a paramOp at a specific moment in a script, you can use

  • Identity to request the pOut and thus trigger the paramOp to perform the operation with the current pIns

  • Op to perform the requested paramOp when activated by another BB (after selecting the Operation Type in the Settings for the BB)
Because Identity supports a variable number of pIns, Identity can be used to calculate several values at the same time.

pTypes <Angle>, <Float>, and <Percentage>

Very often a paramOp will involve a <Percentage> or <Angle> pType. These pTypes are actually considered to be of type <Float> by Virtools Dev but with unique representations:

  • an <Angle> is represented as the number of turns and degrees

  • a <Percentage> is represented as a value in the range 0% to 100%
Therefore, if a pIn of pType <Angle> has a value of 0:180 (0 turns, 180 degrees) then the value used for calculations is actually equal to 3.14159 … (PI) because Virtools Dev must use radians rather than degrees when performing calculations.

NOTE There are 2*PI radians in 360 degrees.

Similarly, a <Percentage> of 50% has a value of 0.5 for calculations.

Therefore, wherever you have a <Float> pIn or pOut, you can change the pType to <Angle> or <Percentage> for your convenience. For example, if you create a paramOp
  • <Float> Multiply <Percentage> <Float>
    • with the values <Float> Multiply <Percentage=50%> <Float=2.0>

the result will be 1.0 not 100%. For such an operation, it might be better to specify the pType of the pOut as <Percentage> for ease of comprehension.


Attributes

Overview

Attributes are a means of adding information to elements. Attributes are very much like local parameters in that they store information, with the difference being that attributes belong to an element instead of belonging to a script.

Virtools Dev includes numerous predefined attributes. You can also define your own attributes.

Only Behavioral Objects can have attributes. A Level is a BeObject and can have attributes. Level attributes are, effectively, global attributes.

Attributes Structure

An attribute has a Name and may also have a Category. An attribute typically consists of one or more parameters that you can edit. However, some attributes, (such as ZBuffer Only) can not be edited.

For example, an element with the Floor attribute is identified to the Behavioral Engine as an element that should be treated as a floor so that characters walk on the element and not through the element.

Attributes are added to elements during Author mode via an the Level Manager context menu, via an element's Setup or via the Attributes manager.

Attributes Manager

The Attributes Manager allows you to inspect and manage which elements have what attributes (Figure 1-31).

Figure 1-31 - The Attributes Manager

At run-time, Attributes can be:

  • added via Set Attribute
  • removed via Remove Attribute
  • retrieved via Has Attribute, if the attribute exists on the element

All attribute BBs are in Logics/Attribute.

Attribute Shortcuts

Attributes are often used to store data values associated with an element. Typical uses for attributes include a player's score, a player's health, the characteristics
of an object, etc.

If the value of an attribute is required by a script, then Has Attribute (Logics/Attributes) can be used to retrieve the value of the attribute. Alternatively, an attribute shortcut can also be used.

Attribute shortcuts are created by copying an attribute from the element's Attribute Setup (via the context menu) then performing a Paste as Shortcut operation (via the context menu) at the desired location in the Schematic.


Introducing VSL

Overview

VSL (Virtools Scripting Language) is a powerful scripting language that complements the Virtools Dev Schematic editor by providing script level access to the Virtools SDK. The VSL Editor supports an intelligent context-sensitive text highlighting (coloring) system, context-sensitive completion and automatic display of function arguments. VSL includes a full debugging mode with breakpoint support, watchable variables with value editing, and step by step debugging (including step into/out support).

For Programmers and Scripters

VSL is an advanced feature that can be used by programmers and scripters alike:

- For programmers, VSL is an interface to the SDK from within Dev. With no need to create a C++ project, you can easily and quickly test new ideas and implement custom code without implementing custom DLLs.
- For scripters, VSL is ideal for replacing complex parameter operations (e.g. math calculations, string operations) and creating advanced behavioral scripts.

VSL is also a very efficient way to automate your workflow (e.g. finalize media, perform batch operations in just a few lines of script, etc.), to achieve innovative visual effects, and more...

Requirements

It is essential that you have previous programming or scripting (e.g. JavaScript) experience before trying to use VSL. In addition, you must be reasonably familiar with or be willing to become familiar with the Virtools SDK.

Schematic v. VSL v. SDK - Which One to Use?

You want to do something in Dev for which no BB or BG currently exists. What is the best way to create this functionality? Should you use the Schematic Editor, use VSL, or should you write a custom behavior with the SDK? The answer to this question depends on your competencies and your goals.

Schematic

In general, if your needs can be easily met by scripting existing BBs or BGs then use the Schematic Editor.

VSL

If you find that you are creating complex scripts with many loops, or that you are creating forests of paramOp trees, then you may want to consider writing a VSL script instead. You may want to use VSL to prototype and test ideas that, if feasible, you would like to implement using the SDK (for maximum performance). Or, you may wish to use VSL to create custom functionality without having to worry about distributing custom DLLs.

Note: Although VSL can create new data types (structures), these are only available in VSL and can only be used by VSL scripts.

SDK

There are some things that can only be done with the SDK (not all functions and methods are available in VSL), or that would work better when implemented in a custom plugin (that, in addition to defining new BBs, also defines new data types and uses a manager to run everything). See the Limitations section of the Understanding VSL page.

Use the solution that best fits your needs, remembering that development complexity (generally) increases from Schematic to VSL to SDK.


The Render Engine

Overview

The Render Engine is the part of the Virtools application that draws the image you see on screen. There are actually two components to the Virtools render engine, either of which can be replaced or customized using the Virtools SDK if you access to the Virtools RenderPack (subject to a separate licencing agreement):

  1. The Render Engine - CK2_3D

  2. The Virtools Rasterizers, providing support for DirectX5, DirectX7, DirectX8, DirectX9 and OpenGL.

The Render Engine - CK2_3D

The Virtools Render Engine is a 3D engine abstraction, as its API is independent of specific 3D hardware and software. This abstraction isolates the rest of the Virtools Dev (with the exception of the Rasterizer), and especially the Behavioral Engine, from the details of 3D implementation.

The Render Engine decides what should be drawn, but does not actually draw the image itself. Based on information supplied by the Behavioral Engine (CK2), the Render Engine develops a list of all items that can be seen.

The list of visible items is then provided to the Rasterizer for drawing on screen.

Virtools Rasterizers

The Rasterizer defines an Application Programming (API) that abstracts the rendering hardware and associated APIs.

The Rasterizer that you or your User can use depends on the capabilities of the graphics card.

The Rasterizer deals with polygons, textures and rendering settings. Given these 3D elements, the Rasterizer draws one 2D image intended to be shown on screen. Thus, the Rasterizer corresponds to the performance critical last phase of the rendering.

Virtools provides a Rasterizer for these different 3D APIs: DirectX5, DirectX7, DirectX8, DirectX 9, and OpenGL.


Initial Conditions

Overview

Virtools allows you save, remove and restore initial conditions (IC) for one, several or all elements of a CMO. Initial conditions is a sort of snapshot for an element - exactly what is saved depends on the type of element. In addition to BeObjects, you can set initial conditions for scripts as well. If an element has IC, this is shown in the Level Manager (an X in the IC column), and in the Setups for BeObjects and in the script header for scripts.

Setting (Saving) IC

In the Dev interface you can set initial conditions for an element by using the context menu that appears when you right-click. A number of editors also have Set IC buttons. You can set IC for several elements at the same time. At run-time, you can use the Save IC BB.

Removing IC

In the Dev interface you can remove initial conditions for an element by using the context menu that appears when you right-click. A number of editors also have Remove IC buttons. You can set IC for several elements at the same time. At run-time, you can use the Remove IC BB

Restore IC

In the Dev interface you can remove initial conditions for one or several elements using the context menu that appears when you right-click. A number of editors also have Remove IC buttons. You can restore IC for all elements of the whole CMO that have IC using the global Restore IC button. There is no specific BB to restore IC, however several BBs in the Narratives category have a pIn that allows you to restore an element's IC. For example, the Activate Object BB has a Reset? pIn that will if selected restore the object to IC when activating it.

Information Stored with Initial Conditions

The following list details what parameters are saved for a specific CKClass. "List" (e.g. Mesh List ) means just the list of items, not all data about about every item, e.g. "Mesh List" for 3D Object below means that a 3D Object that has IC keeps track of the names only of Meshes in the list, it does not store any further information on Meshes. However when you see "IC for all ...", that means IC are kept for all items, e.g. "IC for all body part" for a Character below means that the state (IC) of all individual body parts is stored by the Character (in which case if you set IC for a Character, there is no sense in setting IC for any bodyparts).

Script: All local parameter values.

Behavioral Object: Attributes (if an element has new Attributes since setting ICs, the Attributes are not removed when you restore ICs).

3D Entity (including 3D Frame and Portal): Mesh List, Current Mesh, Animation List, Owner Place, Z order, World Matrix (Position, Orientation, Scale), Parent Entity; Skin Data if available.

3D Object: N/A (no other data in addition to parameters saved for 3D Entity).

Body Part: IK information, Character to which this body part belongs.

Light/Target Light : All Data (as shown in the Light Setup).

Camera/Target Camera: All Data (as shown in the Camera Setup).

Character: All body part data (List + IC for all body part), Active Animation, FloorRef and Root.

3D Sprite: Type, Size, Offset, Mapping, Current Material.

Grid: Size, Content of each layer.

Curve: List of Curve Points (+ IC for all curve points), Fit coefficient, Curve steps, Open/closed curve.

Place: Default Camera for the Place, Portals List.

2D Entity (including 2D Frame): Position, Screen size, Z_order.

2D Sprite: All Bitmap slots, Color Key, Current Slot, Save Options.

Level: Fog, Background Color/Texture, Starting Camera.

Scene: Fog, Background Color/Texture, Starting Camera.

Group: Objects list.

Array: Array data, key column information.

Wave Sound: All Data (as shown in the Sound Setup).

Mesh: Texture Wrap, Lit Mode, Mesh Topology (to complete), Channels (to complete - every column/line?), Materials Used.

Patch Mesh: All Patch and Control Vertex Data (= Patch Mesh Info data?), Tessellation Factor.

Material: All Data (as shown in the Material Setup).

Texture: All Bitmap slots, Color Key, Current Slot, Save Options, Desired Video Format.

See also Initial Conditions in Level Manager


Virtools Dev Whitepapers

Overview

Virtools Dev Whitepapers cover advanced topics beyond Virtools Dev's Basic Concepts and the Virtools User Guide and provide strategies for using Dev more efficiently and resolving technical issues.

To get the most out of these whitepapers, review them after you have become familiar with Dev's working process.

  • 2D User Interfaces and Text Display
  • Character Animation Control
  • Level of Detail (LOD)
  • Lights, Shadows and Reflections
  • Optimization
  • Scene Management

Comments

Copyright © 1999-2003 Virtools SA
All Rights Reserved.
Further Legal Information


2D Interface Whitepaper

User Interface and Text Display

User Interface

BBs Dedicated to Interfaces

Virtools Dev includes numerous BBs dedicated to designing user interfaces. These BBs are located in the "Interface" category.

Entities that can be used as Interface Elements

2D Frames

2D Frames are rectangular 2D entities that support a material. Pros and cons of 2D Frames include:

  • Pros
    - Control material blending properties - Control transparency with or without alpha mask.
    - Use the material's diffuse color information to control the color of the 2D Frame.
    - Share materials, and therefore textures, among 2D Frames.
  • Cons
    - Textures are automatically resized to integer power of two resolution (for example, an image 200 by 300 pixels is automatically resized to 256 by 512 pixels).
    - The resizing process can result in blurred images.

2D Sprites

2D Sprites are also rectangular 2D entities, but they don't use a material. 2D Sprites own their own texture information. Positive and negative aspects of 2D Sprites include:

  • Pros
    - Textures remain at their source resolution and are not automatically resized to integer power of two resolution.
  • Cons
    - Only color key transparency is supported.
    - Textures can not be shared between two sprites.
    - 2D Sprites require more processing than 2D Frames of the same size and are slightly slower to render.

Since 2D sprites don't resize their texture to an integer power of 2, they are usually better to use than 2D Frames for background images.

3D Sprites as Interface Elements

If you want to create a rotating element in your interface (like a rotating speedometer indicator on a dashboard), you must use a 3D Sprite because it is not possible to rotate a 2D Frame or a 2D Sprite. You can simulate a 2D Interface Element by parenting the 3D Sprite to the current camera, creating a "billboard" effect.

BBs dedicated to User Interfaces

Layouts

A few BBs in "Interface/Layouts" ( "2D Curve Layout", "2D Flow Layout" and "2D Grid Layout") support the dynamic positioning of your 2D Frames with values taken from an array, a grid or a curve. This technique is a useful time-saver since you only need to change the array, grid or curve to re-organize all the 2D Frames of the interface without moving them one by one.

Controls and Primitives

Buttons are supported by the "Push Button" BB. Drag and Drop functionality is supported by the "Drag and Drop" BB.

Additional Views and Resize View

The "Additionnal View" and "Resize View" BBs in "Interface/Screen" allow you to resize or even add an extra 3D view in your content (for example, as a rear view mirror in a driving simulation). Use these BBs with care because each additional view requires another rendering pass.

Text Display

Text

BBs for dealing with different kinds of text in Virtools Dev are in "Interface/Texts":

- "2D Text": The most effective method to display 2D text. It uses a dynamically-generated texture with user-specified features such as italic, underline or bold. The rendered text is positioned relative to a 2D Frame. Look at the settings in the "2D Text" BB documentation to customize the final layout.
- "3D Text": Currently, the only method to display 3D text (3D Text is text that has a position in the 3D space of the world; it is not text that is rendered as a 3D element.) 3D text also uses a dynamically-generated texture but you have to use a 3D Frame to hold the text. Therefore, your text can interact fully with your 3D environment and can be oriented in any manner that you choose. The settings available for this method are the same as the ones from the "2D Text" method.
- "Bitmap Text Display": This method is obsolete. Bitmap Text Display uses a bitmap created by the user to generate a font. Note: it is quite difficult to create the bitmap, and rendering quality is often unsatisfactory.
- "Text Display": This method is very slow. A simple display of text on the screen. The Text Display BB does not use a texture so it is quite useful when debugging and testing. This BB is not appropriate for use in a completed application because it takes a lot of time to process and the visual quality is often unsatisfactory.

Fonts

Virtools Dev uses specially formatted textures to display text onscreen. These textures can be dynamically generated by Virtools Dev from the system fonts installed on the machine or from specially designed textures that describe your custom font. BBs related to this topic are in "Interface/Font".

With "Create System Font" you can dynamically create textures from the system fonts installed on your local machine and (optionally) store them in your composition. It is safer to store these textures in your composition if you think that target machines might not have the system font already installed. If the system font required by the application is not present on the target machine, the texture with the closest name will be used. To be sure to save the Texture in the composition, you have to uncheck the "Dynamic" setting in "Create System Font", run the composition once to create and store the created texture.

You can also choose special features like "italic" and "underline" for the generated textures used for the fonts.

Font Properties

With "Set Font Properties", it is possible to set different visual properties for many fonts even if they come from the same texture. Each font should be specified by its name. Virtools Dev recognizes that a font is created from the same texture as another font as long as they have the same texture type (weight, italic, underline) and texture size (512x512, 1024x1024), and so another texture will not be created.

For example when using "Set Font Properties" with "Create System Font", you can create several fonts with specific properties such as color, a shadow, etc. All these different-looking fonts can be generated from the same texture as long as you do not specify a different texture type or texture size with the available parameters and settings of "Create System Font".

The Caret

The Caret is a text insertion point that prompts a user response (ie: cursor). Caret display is managed by the setting "Show Caret" available in the "2D Text" and the "3D Text" BBs. If this setting is checked, it is possible to set the material used by the Caret via the BB's parameter inputs. To create the Caret, use either the "Input String" BB or the "Set Caret Pos" to position the insertion point in a given string.

Homogeneous coordinates

To display text scaled according to the screen resolution, you have to use the "2D Text" or "3D Text" BBs and check the setting "Screen Proportional".

Pasting text into a Parameter Input

The easiest way to retrieve formatted text from a text file is:
- use the "2D Text" or "3D Text" building-blocks
- edit parameters, then click on the checkbox on the left of the parameter "Text" to open the text window
- paste the text in the text window
- check the "WordWrap" setting available on these building-blocks
- set the width of the "2D Frame" or the "3D Frame" to a value large enough to contain the text.


Character Animation Control Whitepaper

Character

What is a character?

A Character is special type of 3D Entity defined by a hierarchical set of Body Parts that are all children to a unique root object. This Root defines the Character's position and orientation.

Skin Character

A Skin Character is a character with 3 possible types of body parts: skin, bones and dummies. Skin body parts are body parts owning a mesh that is deformed during an animation according to the positions of a set of bone body parts. A skin character can have just one skin body part. Dummies are passive body parts whose matrix can be used for object positioning (ie: in the hand, at the belt, on the floor...).

A Skin Character's main advantage is that there is no skin join problem (a gap between body parts when in motion). Its main constraint is its ability to deal with material or texture behavioral modification.

There can only be only one mesh for each skin body part, but in some cases, that can actually be more convenient (ie: for "Visuals/Shadows/Shadow Stencil BB" you only have to put the Shadow Stencil Caster attribute on the skin body part(s).)

Skin Characters' animations are lightweight and versatile.

Body Part Character

A Body Part Character is comprised of body parts with their own mesh and possibly dummies. You will most likely need to use "Mesh Modifications/Deformation/Skin Join BB" to resolve gap issues when in motion.

Mesh Morpher Character

Even if your animation uses unknown animation controllers, it can still be exported by sampling the object animation into a mesh morphing animation. This method stores all the character's meshes with each animation frame. Note, using a lower sampling rate makes a lighter animation file, and this animation technique generates huge files in comparison to other techniques.

Tips on Media Creation

A character MUST have all its body parts hierarchically linked to a SINGLE body part. This body part (the root) gives the Character's position and orientation. In Virtools, the root body part should have the Z axis in the "front direction" and the Y axis in the "up direction". Using this orientation will simplify the use of many Virtools behaviors.

If you want to use Character Keep On Floor, don't forget to have an object containing "FloorRef","Foot",or "Pas" in its name if you want a precise floor reference. See "Characters/Constraint/Character Keep On Floor" and "Characters/Constraint/EnhancedCharacter Keep On Floor".

Read the documentation about the software you use for creating you character in "Virtools Online Reference/Importing/"

Different Tools Relative to Characters in Virtools Dev

Any Building Block that applies to 3D Entities can apply to Characters and to Character's body parts (Characters and their body parts are 3D Entities). As you manage complex hierarchical sets, don't forget to check the hierarchy parameter to TRUE, especially when you use 3D Transformation BBs. Remember, a Character doesn't have a mesh, its hierarchy does, and this mix-up is a frequent cause of why a Building Block may seems to malfunction. Read the BB's html help and eventually reapply the behavior to the proper body part. For example, Simple Shadow BB is applied to the the body part, not on the character.

Building Blocks specific to Characters are all in the "Characters" directory, and most of them are related to animation.

Using Animations

Character Controller BB

Character Controller BB + "Controllers/Keyboard/Keyboard Controller BB" : these two Building Blocks are simplest way to put 4 animations on a character and control it with Numpad keys.

Unlimited Controller BB

Unlimited Controller BB : this Building Block is key to any complex animation control.

Warp

In comparison with "Set Animation Step/Frame BBs", this BB's most interesting feature is its Warp capability. Warp creates a transition animation that is temporarily created between the last and the next animation. The length of this animation is equal to the Warp Length parameter value.

"Start" creates a transition to the start of the next animation, useful if you want to be sure that the next animation will be played from start (a "jump" animation for instance.)

"Best" finds the best frame to begin the next animation. The "best frame" is determined according to body part's orientation, position and scale similarity with the current animation frame, useful for cycling animation transitions (transition from a Walk animation to a Run animation, for instance.)

"Same" creates a transition toward the next animation step (ie, the progression percentage) equal to the current step of the current animation, similar in use as "best" with more control as long as animations are synchronized. (ie, this warp mode choice must be planned while producing animations.)

"None" creates no transition animation.

stoppable / non-stoppable

Animations fall into two great categories: "non-stoppable" animations (ie: Jump, Fall, Open_door, etc.) and "stoppable" animations that are often looping animations (ie: Wait, Walk, Swim, etc.)

These categories are taken into account by the boolean parameter of the Unlimited Controller BB. Once a "non-stoppable" animation has started, it will be played until its last frame is reached. As a consequence, once it has started, no more messages are required to play the animation. On the contrary, the Unlimited Controller BB needs to receive the proper message at every frame in order to play a stoppable animation.

Input Parameters

For generic scripting, you can create as many input parameters as you expect to have variables. To create a parameter input corresponding to a parameter of the "Unlimited Controller" dialog, right click on its cell (here on the cell with the Wait Animation) and select the "Create Input Parameter" menu item. A parameter input is created and (PO) that stands for "parameter 0" appears in the corresponding cell of the dialog. This way, anything problematic can be put in standard scripts, resorting to arrays where more animation-linked parameters can be put.

The following example is a set of arrays for animation selection purposes. The first array chooses the second array according to a keyboard key. "Priority" arbitrates when more than one key is pushed.

The second array chooses the animation according to the context (in this case, the current floor type of the character).

The last array chooses the relevant parameters needed for the animation. Certain parameters are not necessarily linked to the Unlimited Controller BB. For instance, "SliderRadius" is used for a dynamic change of an Object Slider radius used by the character ("size" on floor is greater when you crawl than when you stand.)

"Non-stoppable" animation parameter changes won't be considered after the animation has started, whereas stoppable animation parameter changes are. For instance , you can change the Fps of a running stoppable animation, or make it non-stoppable. On the contrary, if you change the "Animation" parameter of a running non-stoppable animation, the new value will start if the corresponding message is received after the current animation's last frame has been played.)

In the following example, the Unlimited Controller BB (with only one line modified by input parameters) is used to set new values for the next animation at any time and send the message at every frame until the Animation input parameter is equal to the Current Anim output parameter.

Secondary Animations

Secondary animations provide added realism to a character's movements.

An animation is considered secondary as long as it is specified that way by the Unlimited Controller BB. In theory, any "secondary" animation can also be used as a primary animation; however, secondary animations should be conceived in regards to their final purpose.

In your animation software, secondary animations follow the same creative process as primary ones; however, do not set any modifiers on unused body parts or the character's root body part. Export the animation like any other and declare it as a secondary animation in the Unlimited Controller parameters box.

At this stage, secondary animation control is very much like that of a primary animation; however, some differences exist. The "order" parameter doesn't exist, since any number of secondary animations can be played simultaneously as long as no overlap exists for the implicated body parts. In that case, the "last called" animation will always have priority over the preceding one. The "turn" and "orient" parameters are useless for secondary animations.

According to the Action parameter value - "Play Once" or "Loop+ Stay" - others parameter may be taken in consideration. Stay is relevant for "Play Once" and "Play Loop N", and Loop count for "Play Loop N" only. "Stop" use only Warp parameters.

Secondary animation parameters can be set as input parameters (like primary animation parameters).

Behavioral animations

Characters sometimes need to process behavioral animations to simulate complex and unpredictable interactions with the environment. Behavioral animations can also be used in complement to other primary and secondary animations.

3D Transformations

Behavioral animation by 3D Transformation is low cost in media production (since there is no animation production), but good results can be time consuming to script. The trick is to keep referencing to the direct parent's matrix of the modified body part in your script.

When behaviors apply to a set of separate body parts, the first question is whether or not to use the Exclude from Animation BB.

If you don't use Exclude from Animation BB, the body part's matrix is set by the current animation at the beginning of the frame. Therefore, you can process the 3D transformation in the same frame with the body part as its own referential and keep coherent with the current animation. The main constraint with this method is that attenuation parameters are more difficult to use.

If you use Exclude from Animation BB, the 3D transformation applies like for any classical 3D Object. As a consequence, keeping coherent with the whole character can be tricky.

IK

Inverse kinematics (IK) involves inferring the matrix of a body parts chain from the one of the last chain member (ie the last child). This is a powerful tool, useful for precise interaction with the environment (object grasping, for instance.)

Currently, the only available IK building block is IK Position BB. While it is very simple to use, IK Position BB won't check for intersection of body parts.

To avoid such incoherence, the only way is to script your own tests (whether not to trigger the IK behavior, to dynamically move a referential 3D frame at reach, trigger a rotation behavior on the character, etc.)

You can combine more than one IK position BB on the same character. For example, Spine-to-Neck with high latency and Clavicle-to-Hand with low latency, makes a swift movement of the arm to grasp an object while the body bends slightly. Be sure that you process the BB related to the upper hierarchical chain before (but in the same frame as) the other one, because children of the ending body part will be affected by the IK Position BB.

You can combine IK with 3D Transformations. If the 3D Transformation applies to a body part in the IK chain or child of the ending body part, take note of the processing position in the frame.

As with 3D Transformations, you have to consider whether you want to exclude the IK chain from animations or not. If not, the coherence with the other body part will be more easily kept, but you will loose the benefit of the latency parameter. (In this case dynamically change the latency parameter from 100 to 1 with a Bezier Progression BB, for example.)

Blended animations

An other technique of dynamic animations is the use of blended animation. The key features for this technique are "Create Blended animation BB" and "Set Blended Animation Factor BB". First generate the blended animation with "Create Blended animation BB". This new animation can be used like any other animation.

By changing the animation factor (continually and in runtime), you can blend from one animation to the other with complete control

Examples of use of blended animation :

Let's say you have a Walk animation synchronized with a Run animation. With the blended animation factor, you can control the speed of the character that plays the Walk+Run animation with a perfectly linear transition from the slow to the fast mode.

Or let's say you have a Kick_Front and a Kick_Right animation. You can choose a precise angle between Front and Right for the kick to occur by setting the proper animation factor before playing the Kick_Front +Kick_Right blended animation.

Note: It is possible to blend blended animations.


Level of Detail (LOD) Whitepaper

Level Of Detail (LOD)

Overview

Level Of Details (LOD) is a collections of algorithms used to speed up rendering time, by removing irrelevant details from drawn objects (like very small faces on distant objects).

Virtools includes several LOD techniques using LOD BBs (under Optimization/Level Of Detail), giving you a number of ways to speed up rendering time. The following LOD algorithms are implemented in Virtools Dev:

- LOD Multi Mesh
- LOD Patch Mesh
- LOD Progressive Mesh
- LOD Alpha Transparency
- LOD Character Animation

The LOD Manager Options BB activates/ deactivates LOD algorithm(s) and is used in conjunction with LOD object attributes (described below in greater detail). According to your needs (or constraints), any or all the LOD algorithms can be combined.

The basic concept of using LOD BBs is very simple - if an object fills only a small area of the screen, then this object should be rendered quickly.

Even without using LOD, this is already true to an extent. A 3D graphics card's fill rate is better as an object gets smaller (or farther away), but the fill rate is just a small part of rendering time. Most of this rendering time is taken up by calculating vertices (vertex 3D transformation, lighting, projection ...etc), and calculating animations (especially for characters).

LOD saves rendering time not only by speeding up the fill rate, but also by speeding up all those 3D calculations. In most cases, this is performed by adjusting the object face count according to the object's size on screen.

When the teapot is bigger than 50% of the screen size it is rendered at full face resolution.
When the teapot is smaller than 10% of the screen size it is rendered with a minimal face resolution.
Between those two screen size, face count is interpolated.

LOD Attribute

All the LOD techniques implemented in Virtools are accessed through the same interface steps.

1. Apply the LOD Object attribute to the object

The LOD Object attribute is located in the attribute category named LOD (Level Of Detail).
Add it to the object.

Once the attribute is added to the object, it should be visible as follows in the object's attribute list.

Double-clicking on the value cell brings up the LOD Object parameter dialog.

Note: LOD attributes can also be assigned with Set LOD Attribute BB.

2. Choose appropriate parameters according to your needs (or constraints)

The left check buttons determine the LOD method used for the object.
Except for progressive mesh method, you have to check one of these method for the corresponding LOD technique to take effect. For example, if the Patch Mesh is not checked, the LOD manager will not change the patch mesh's iteration count (tessellation level) and assumes that the user wants to use another LOD technique that doesn't use patch mesh tessellation capabilities.

The resulting face reduction (applied at run-time by the LOD manager) is controlled by the percentage parameters on the right.

- Screen Mag: The magnification size of the object. This percentage stands for the maximum object size beyond which the object's face count stops being increased. In other words, if the object's screen size is bigger than Screen Mag the face count is cast to the maximum defined face count, and if the object's screen size is smaller than Screen Mag the face count is reduced until the object's screen size reaches Screen Min.

- Screen Min: This percentage stand for the minimum object size beneath which the object's face count stops being decreased. In other words, if the object's screen size is smaller than Screen Min, the face count will be cast to the minimum defined face count, and if the object's screen size is bigger than Screen Min, the face count is increased until the object's screen size reaches Screen Mag.

- Faces Mag: When the object's screen size is bigger than Screen Mag, Faces Mag percent of the initial object's face count are rendered. In most cases, this value is 100% (meaning that all faces of the object are rendered). However, for patch meshes, Faces Mag can be greater than 100% because it is a tessellation algorithm, not a real faces reduction algorithm. For a patch mesh, Faces Mag=100% means an iteration of 5 (tessellation level). You have to reach 200% or higher to reach the next tessellation level (if you want a smoother object).

- Faces Min: When the object's screen size is smaller than Screen Min, Faces Min percent of the initial object's face count are rendered. In most cases values of 2%, 1% or 0% are used (note: you can use of course intermediate values like 2.6%).

The following scheme shows the object face count progression as the object gets smaller (or farther away):

Figure 1.1

The face proportion is calculated according to the object screen size proportion. This face proportion guides the chosen LOD technique(s).

LOD Multi Mesh

If the object with the LOD attribute owns more than one mesh, the Multiple Meshes button will automatically be checked when the attribute gets attached to the object. However, you can choose to use LOD Multi Mesh technique or not, by checking or unchecking the Multiple Meshes button.

From a given face proportion the LOD Multi Mesh algorithm will choose the appropriate mesh among the object's mesh list. This list doesn't need to be in any order; the LOD Multi Mesh algorithm will look at all object meshes and find the one whose face count closely match the desired face count. In most cases, 4 or 5 different resolution meshes are enough to perform a correct LOD Multi Mesh.

The LOD Multi Mesh algorithm is not the fastest one, but it provides very good control on the end result.

Notes:
- All the LOD algorithms applying to an object are evaluated just before the object rendering, meaning that different objects can share the same mesh(es) without any interference to the LOD process.
- You can't apply the LOD Multi Mesh technique to skinned objects or morph animated object.

LOD Patch Mesh

If the object with LOD attribute uses a patch mesh (as current mesh), the Patch Mesh button will automatically be checked when the attribute gets attached to the object. However, you can choose to use LOD Patch Mesh technique or not, by just checking or unchecking the Patch Mesh button.

From a given face proportion, the LOD Patch Mesh algorithm will choose the appropriate patch mesh iteration value to modify the tessellation level. This tessellation will result in a new face count proportional to the desired face proportion.
Unlike other LOD algorithms, the LOD Patch Mesh Faces Mag value can be greater than 100% in order to get a more accurate mesh representation.
Mesh iteration=5 when Faces Mag=100%.

Note:
- Like all other algorithms, the LOD Patch Mesh algorithm is evaluated just before the object rendering. But as changing a patch mesh tessellation is a very costly process, you should avoid using the LOD Patch Mesh algorithm on objects sharing the same patch mesh; otherwise, it will dramatically slow down your frame rate! The only case where you would share patch mesh on two LOD objects is when you are sure that those two objects won't be seen simultaneously onscreen.

LOD Character Animation

If the 3D entity on which the LOD attribute applies is a Character, the Character Animation button will automatically be checked when the attribute gets attached to a character. When the Character Animation button is checked, the Multiple Meshes and the Patch Mesh options disappear, since they can't be used directly on a character (they only apply to 3D Objects). To use a LOD Progressive Mesh, or a LOD Patch Mesh on the skin of a character, the LOD Object attribute must be attached to the character's body part that owns the skin (in most case this body part is the root entity). Note: the label "Faces" has been renamed "Anims" since it now deals with character animations, and no longer with face count.

The purpose of the LOD Character Animation technique is to reduce (or remove) animation calculation when the character gets small.
Anims Mag=100% means all body parts are animated if the character screen size is bigger than Screen Mag.
Anims Min=0% means the only animated body parts are the root and the floor ref (if there's a floor ref).
If the character screen size is included in the range [Screen Mag, Screen Min] then, only some of the body part will be animated (the most significant ones).
The number of animated body parts is an interpolation between Anims Mag and Anims Min.

Note:
- In most case, the used values are: Anims Mag=100%, Anims Min=0%, and Screen Mag=Screen Min.
It often gives a better result to use Screen Mag=Screen Min, that way, the all the body parts animation are stopped at the same time (Removing animation from body parts gradually while character is moving can result in ugly artifacts).
- When a character gets outside the viewing frustum, all its animations are stopped except those applying to the root. This is done automatically even if there's no LOD attribute on the character. Thus, to benefit from this, you shouldn't associate a skinned or morphed mesh to the root of the character, because if you do, the skinning and morphing animation will not be stopped when the character gets outside the viewing frustum.

LOD Alpha

When Alpha button is checked, two new percentage values appear in the LOD attribute dialog box: Screen Alpha Mag and Screen Alpha Min.
The reason why the LOD Alpha technique owns its proper values, is because the threshold values used for LOD Alpha usually aren't the same as the threshold values used by other LOD techniques. So in order to still be able to cumulate the LOD Alpha technique with other LOD techniques, it has its own threshold values. To understand what happens see Figure 1.1 and replace Screen Mag and Screen Min values by Screen Alpha Mag and Screen Alpha Min, and consider the Faces % axis as describing the object opacity.

The purpose of the LOD Alpha technique is to fade out (and finally hide) small objects.
If the object screen size is bigger than Screen Alpha Mag, the object is totally opaque.
If the object screen size is smaller than Screen Alpha Min, the object is hidden.
If the object screen size is included in the range [Screen Alpha Mag, Screen Alpha Min], the object is transparent.

Note:
- This LOD technique works on lit objects as well as on prelit object.

LOD Progressive Mesh

The LOD Progressive Mesh algorithm is probably the most frequently used. Object's faces are automatically remove as the object get smaller.
But as you may have noticed, there's no LOD Progressive Mesh button in the LOD attribute dialog box. This is because converting a mesh to progressive mesh is a very costly process that shouldn't be done at run-time (on the fly). That's why this check button is located in the Mesh Setup itself.

When you check the Progressive Mesh button in Mesh Setup, a structure is built in the other one to speed up the run-time face reduction. Building this structure can take several seconds.

Once the structure is built, and if the object owns the LOD Object attribute, the LOD Progressive Mesh technique will apply to the rendered object, according to Figure 1.1.

Note:
- This technique works for all objects using progressive meshes.
- To make it work for a skinned or morphed character, remember that the LOD attribute needs to be given to the body part that owns the skin (most likely, the root).


Lighting, Shadows and Reflection

Lighting, Shadows and Reflection Whitepaper

Overview

Lighting, shadows and reflections dramatically increase the atmospheric and visual quality of your scene; however, to make proper use of these features, you need to understand their limitations and how they work.

Lighting

Lighting is the process with which vertices in your scene are lit.
The Mesh Lit Mode (see Mesh Setup) determines if the mesh has to be lit, or if the mesh's lighting must be calculated using user-specified vertex colors.

Lit Meshes

If the Mesh Lit Mode of the Mesh Setup is set to "lit", lighting calculation is performed.
This calculation uses:

  • the vertex normal
  • material properties of the face to which the vertex belongs
  • properties of each light in the scene

We will now describe how each of these components are used to perform the final vertex lighting.

The vertex normal is a normalized vector that describes the orientation of the vertex. The oriented vertex concept can be understood as "what amount of the light (emitted by a particular light) is taken into account for this particular vertex". The dot product between the vertex/light direction and the vertex normal is calculated for each vertex (after back face culling) and for each light.

The following screenshot shows the vertex normals of a simple teapot with one light.

Tip: If an object's lighting seems incorrect, check that vertex normals are oriented correctly using the "Show Object Information" building block. Incorrect vertex normal orientation may result from a mirror modeling operation in your modeler.

Material Properties

The Material Properties used to compute the vertex color are Ambient color, Diffuse color, Specular color and power, and Emissive color.

Ambient color of the material is combined with the ambient color of the scene (set the ambient color of the scene using the Virtools Level/Scene setup or the Set Ambient Light BB).

Diffuse color can be considered a material's main color. If your object is not lit, make sure that the diffuse color is not set to black.

Emissive color can be considered the color of the object itself (for self illumination).

Specular color is the highlight color on the object's surface. The calculation of a vertex's specular color depends on: this color, the material's specular power, and the light's specular property. Note that specular power value is NOT linear regarding the resulting specular effect.

Warning: Specular color calculation can be very intensive. Therefore, in your scene, reduce the number of lights that have the Specular property set to On.

The specular color calculation estimation.

Light Properties are also used in the Light calculation.

The following table shows which parameter is calculated with the different the light types.

 | Position | Orientation | Range | Attenuation | Spotlight attenuation | Color
Point Light | Yes | NA | Yes | Yes | NA | Yes
Directional Light | NA | Yes | NA | NA | NA | Yes
Spot | Yes | Yes | Yes | Yes | Yes | Yes

As you see from this table, a Spot light requires the most calculations.

The Range parameter defines the maximum distance that a light can illuminate objects in the scene.
Note: OpenGL does not support light range.

A light's Attenuation parameters defines how the light decreases over distance.

Warning: Light attenuation calculations may vary depending on the rasterizer. In Virtools Dev, the CK2_3D/DX5LightingModel variable allows you to get the same lighting model for the DirectX 8,DirectX 7 and OpenGL rasterizers when this variable value is set to FALSE. Note that the DirectX5 rasterizer will not use the same lighting model in this case.

Spotlight attenuation is the attenuation that occurs inside the cone of the light: within spot range, a vertex will not be lit the same way when moving in the X/Y plane of the spotlight. The spotlight attenuation occurs in the volume defined by the hotspot and falloff angle.

A color can be set for the light itself.
This color is generally used to define the atmosphere of your scene. For example, a blue light can be used to create a cold, frightening atmosphere. Light colors will obviously be different for an indoor scene and for an outdoor scene.

Note: Using VSL or the SDK, you can set negative color component values so that a color component is "absorbed" when the light illuminates the scene.

In the Scene/Level Setup, you may use the ambient light to define the hour of day of your scene.

Lighting calculation is done for each vertex of the scene and for each light.

Warning: The maximum number of active lights is limited when using a video card that support Transform and Lighting (T&L). In general the maximum number of active lights is 8.

Prelit Meshes

Using prelit meshes, you save lighting calculation time during object rendering by precalculating the lighting of every vertices. The resulting colors (diffuse and specular) are stored for each vertex.

To assign these colors, you can use your modeling software, the Precompute Lighting building block, or the Set Prelit Color building block.

You can switch between the lit and prelit mode using the Mesh Setup Lit Mode combo box.

With vertex color you can set the alpha of every single vertex. This feature can be used with other special effects to achieve smooth texture transitions.

The following screenshot shows that the red plane is partially hidden by the water according to the water vertex alpha. It is sometimes easier to use alpha vertex than alpha texture to achieve accurate transparency effect, especially with a tiled texture.

Vertex color can also be used to achieve more complex effects such as making an object disappear according to the mesh topology.

Shadows

Several methods exists to add object shadows to your scene, and the tradeoff between the desired visual effect and its calculation time generally determines which method you should use.

Simple Shadow

The Simple Shadow is the simplest method to add a shadow to your scene. It consists of adding a channel on the floor (or on any object where a shadow must be cast along the world Y axis). This very efficient method requires few resources and little calculation time.
A white texture with a black spot is often enough to be a texture for the Simple Shadow building block. When creating the Simple Shadow of a character, the building block must be be applied to a bodypart of the character. (Choose a bodypart that moves very slightly).

The Simple shadow technique uses very little computation time.

Pros

  • Simple method
  • Low computation time, except on large scale floors and/or with multiple "Simple Shadows".

Cons

  • Not realistic
  • The shadow is always cast the same way (along the Y world axis)
  • Does not take the light position into consideration

Planar Shadow

Unlike the Simple shadow, the planar shadow creates the full shadow of the object. The planar shadow also uses the light position to cast the shadow and uses the stencil buffer or clipping planes to "cut" the shadow. Cutting the shadow consists in rendering it only where it is meant to be.

The following screenshot shows what happens when the shadow is not cut - if neither the stencil buffer nor clipping planes are available. If you are not sure that on the target machine a stencil buffer or clipping planes is available, place objects so that inappropriate parts of the shadow are not visible. In the above screenshot, the wall is used to hide this unwanted part, even if shadow casting is not realistic (ie: no shadow on the wall).

If only clipping planes are available, the shadow will be cut according to the local bounding box of the floor. As you can see below, the shadow is "cut" by the bounding box of the plane, since the clipping planes are set according to bounding box of the object receiving the shadow.

But, if the stencil buffer is available, the shadow is cut accurately.

The planar shadow uses little resource.

Pros

  • Simple method
  • Low calculation time
  • Reasonably realistic shadow
  • A low polygon model can be used for the shadow.

Cons

  • Off plane shadow removal depends on Stencil buffer or Clipping planes
  • Shadows are cast only on plane objects

Shadow Caster

The Shadow Caster building block may be used when you need accurate shadow rendering. To create the shadow, a rendering of the object casting the shadow is created in a texture. A dedicated camera is placed at the light position, pointing at the object that will cast the shadow, then this camera renders the object and all its hierarchy to a texture. This texture is used by a channel applied to the object receiving the shadow; therefore, this building block requires more calculation time than previous methods.

As you can see, the shadow is much more realistic since it not only casts on a plane but also, in this case, on walls. You may also choose to cast a soft shadow that will use a gradient to render the shadow.

The shadow caster building block is supported by all rasterizers, except by the OpenGL software rasterizer which is not able to clamp the shadow. If you want to make sure that rendering to the texture is supported, you can check the CKRST_SPECIFICCAPS_COPYTEXTURE render driver capability. Depending on the driver implementation, when a texture is set as the target for rendering, it either occurs directly in the texture video memory surface or is copied at the end of the frame from the back buffer to the texture video surface (which is a little bit slower). The default shadow texture resolution is 128*128. This resolution is generally good enough to achieve a good quality shadow.

You may experience performance drop when using several shadow caster building blocks at the same time in a composition. This performance drop is due to the an additional rendering that occurs for each Shadow caster.

The Shadow Caster building block uses more resources.

Pros

  • Shadow resolution can be set
  • Creates a soft shadow
  • Creates a realistic shadow

Cons

  • Using several Shadow Caster BBs can affect performance (1 rendering of the object hierarchy per Shadow Caster)

Shadow Stencil

Shadow Stencil BB is another shadow rendering method that uses the stencil buffer. This method consists of determining the intersection between the shadow volume and the objects that receive the shadow. To simplify the explanation, the object's shadow volume is rendered twice (inversing the culling the second time) but only to the stencil buffer. The shadow is then blended onscreen only where the stencil buffers allow it, using the specified material. The screenshot below shows the Shadow Stencil in use.

The main advantage of this method is that the shadow of the object will cast on the object itself. If we have a closer look at the character foot and we change the color of the shadow to red, you will see the self shadowing of the right foot.

This feature can be used if you need your shadows to be very realistic.

Counterpoints to the stencil shadow method include:
- The stencil buffer must be available on the target system. Even if most recent video card supports stencil buffers, you must be aware of this issue. Stencil buffer is generally available in 32 bits display color depth.
- Since this building block is based on a "intersection" calculation between a shadow volume and objects in the scene, the shadow will not stop on the first object. The following screenshot shows this issue.

As you can see, the shadow (in red) is displayed not only on the floor but also on the wall. The stencil shadow method used is based on rendering and not based on object parsing. You will have to limit your camera movements so that this unwanted shadow is not seen.

The method's third part (drawing the shadow where stencil buffer allows it) uses blending. Therefore you may experience a framerate drop if the shadow occupies a large onscreen surface (this will particularly show on low fill rate video cards).

The Stencil Shadow building block may use high resources in certain conditions.

Pros

  • High quality shadow
  • Self shadowing
  • Very realistic shadows
  • Easy to use

Cons

  • Depends on the availability of stencil buffer
  • Shadow is cast on all objects
  • Framerate drop if the shadow occupies a large onscreen surface (fill rate/blending)

Planar Reflection

Planar object reflection is achieved using a very simple idea: render the reflected object behind a mirror. The mirror (the object on which the reflection is visible) has to be transparent so that the reflection is seen.

The screenshot above shows simple reflections. Note that the reflection is limited to the horizontal plane area.

The following screenshot shows what would be rendered if the reflection was not "cut".

To solve this problem, planar reflection uses 2 methods, and if the first one fails, the second one is used:

  • Stencil buffer: this technique consists in rendering the reflected object only where the mirror renders. This method will work only if stencil buffer is supported by the video card. Stencil buffer is generally available in 32 bits display color depth.
  • Clipping Planes: if stencil buffer is not supported, the building block uses clipping planes to reject part of the reflected object's rendering. Note, our tests have shown that T&L render drivers do not support clipping planes.

Stencil Buffer

User-defined Clipping Planes
(placed according to the bounding box of the mirror.)

As you can see from the images above, the stencil buffer cuts the reflection better than the clipping planes. With the clipping planes, the reflected object is not cut in the appropriate places because the bounding box does not fit the mirror object's topology. (Clipping planes work well with rectangular mirror objects.) The recommended method is to use the stencil buffer because this method is best suited for objects that are not necessarily rectangular.

Pros

  • Low calculation time
  • Easy to use
  • The clipping planes alternative method is efficient on rectangular planes

Cons

  • Depends on the availability of stencil buffer for the most realistic reflections
  • Clipping plane is not available on TL render drivers.


Optimization Whitepaper

Optimization

To help you optimize your Virtools Dev compositions, the following recommendations will help you get the best frame rate (FPS) possible and covers four primary areas of optimization:

  • Rendering Optimization
  • Memory Optimization
  • Script Optimization and Behavior Graph Management
  • Other Optimization Processes

Rendering Optimization

Before covering rendering optimization methods, please review the topic Virtools Rendering Process.

Viewing Frustrum

The frame rate (FPS) closely depends on the number of visible objects that need to be rendered. Virtools always renders all visible objects, even occluded ones, and two primary strategies exist to help reduce the number of visible objects to be drawn.

  • On an outdoor scene, you usually work on the clipping planes of your camera (see: Camera Setup) since distant objects are often meaningless to the scene. First, set the Near Clip value as far as possible, and reduce the Far Clip as much as possible. When you have found an acceptable compromise for the two, you may see that objects in your scene are sharply cut, and the overall effect is not very pleasing. You should add some fog to your scene to have a smoother transition around the Far Clip distance of the camera. The following images show a scene with a short far clip with and without fog.
No Fog | With Fog
  • On an indoor scene, you usually use the Virtools Portal management. The Portal mechanism automatically shows and hides places that are not visible from the camera. Portal.cmo ("Documentation/Cmos/BBSamples/Optimization/") gives an example of the portal mechanism. On this scene (see the screenshot below), we define four places, one for each room. Between the places (where the doors are), we create three portals. Then, on the Place Setup, we define the portal relation between the places. Finally, once the portal mechanism is activated using the "Portal Management BB", when a portal is not visible, the place behind it won't be visible either.
No Portal | With Portal

Culling

Now that you've optimized the number of objects to render, Virtools needs to find these visible objects. This stage in the rendering process, called culling, can take a lot of processing time when you have too many objects. To speed up the culling, you need to build a good hierarchy in your scene as described in the Rendering Process. A good hierarchy means that objects in the same area should also be in the same hierarchical branch. To build your hierarchy, you can use places which are always a parent to all the objects they contain. To modify the hierarchy of a scene in Virtools, use the Hierarchy Manager.

Lighting

When all visible objects have been found, Virtools computes the lighting effects. This computation is done for every vertex of visible objects in the scene. The following steps optimize this process.

  • Make sure to reduce the number of active lights to a minimum. Prefer directional lights, followed by point lights and finally spotlights. Avoid specular lights as much as you can. Also keep the light range as low as possible.
  • Optimize your 3D models to use the fewest faces possible.
  • Break up highly detailed objects (with a large number of faces) that are never fully visible into several smaller objects. For instance, in the following scene, the floor was cut into 4 pieces. Since the camera sees only 1 or 2 pieces of the floor at anytime, we reduce the light computation. On the flip side, increasing the number of objects reduces the clipping speed, so you have to find a good balance between object number and object size.

  • Another way to optimize highly detailed objects is to use Prelighting. You can light an object within your modeling software and then export it with its lighting information. Once in Virtools, set the Lit Mode of the object's Mesh Setup as Prelit, and all light computation will be ignored for this object. To increase efficiency, we recommend setting main static objects as prelit and lighting only animated objects. You can also use the "Precompute Lighting" BB to generate lightmaps within Virtools.

Also read the Lighting whitepaper for more information on this subject.

Drawing

The last step of the rendering process is drawing the scene. Rendering time depends on the following:

  • Number of face to draw. For this reason, always build real-time 3D models with the least possible faces to meet your visual quality. Although there is no theoretical limit to the total number of faces that can be drawn, it really depends on the power of your video card. However, you cannot have more than 65535 vertices per object - due to the DirectX/OpenGL rendering engine.
  • Texture and Video size. When you are using textures or videos in your application, you should always size them by a power of two (..., 64x64, 64x128, 128x128....); otherwise, Virtools will need to resize your textures each time it loads them in video memory, which can be particularly time consuming with videos. A texture's maximum size is directly linked to the capabilities of your 3D graphics card. (Some old video cards even prefer them to be square.)
  • Transparency. When the system draws transparent objects, for each pixel drawn, it first needs to read the current buffer value, then blend it with the object information and finally set the new value to the buffer. Therefore, the more transparency layers you have in your composition, the more system time it will take to draw the scene. So avoid having fully transparent objects - hide them instead.
  • Multitexturing. When you are using multitexturing (Channel in the Mesh Setup in Virtools), you can choose the blending mode used to blend the different material layers (Src Blend, Dest Blend). Virtools also gives you information on the number of passes needed by your video card. If your card needs 2 passes, the object will be drawn twice. Recent graphic cards can draw several layers in one pass, but it depends on the blending mode you've selected. So, always choose the blending mode that uses the fewest passes possible.

Memory Optimization

Before looking at memory optimization methods, please review the topic How Hardware is Used by Virtools Dev .

Memory Optimization

  • Video Memory Size. Make sure your video memory occupation never exceeds VRAM memory size since swapping rendering information is very slow. To gain VRAM memory:
    • Share textures as often as possible (several materials can use the same texture).
    • Use the most economical "Desired Video Format" in Texture Setup. Select a 8, 16, 24 or 32 bits format depending on your needs. You can also use compressed formats.
    • If necessary, free some VRAM by specifying that textures and sprites be stored in system memory rather than in VRAM, or by not saving them (ie: read them off a CD). This option is available in the Variable Manager.
    • Use compound textures (A power of 2 texture can be a compound of several smaller textures that are used by several objects displayed together, like the following texture used by a character).

  • Sharing Media. To reduce file size, and consequently the RAM required, you should:
    • share textures between materials (Texture parameter in the Material Setup or directly in the modeler),
    • share material between meshes (drag and drop a material between the Level Manager and the object's Material List of the Mesh Setup or share them directly in the modeler),
    • share meshes between 3D entities (drag and drop a mesh between the Level Manager and the Object Meshes List of the 3D Object Setup or share them directly in the modeler),
    • share animations between characters (select the Share Animations option when you copy a character or use the Share Character Animation Keys BB). See the Character Animation Control Whitepaper for more information.

File Size Optimization

  • Texture Compression. At the end of your project, compress your textures to reduce your file size. You'll get the best visual results if you use specific file saving options for each texture (in the Texture Setup) rather than a global compression method (Miscellaneous Controls of Preferences or in the Variable Manager). Each compression algorithm can be better adapted to a particular type of image.
  • External Files. During your project cycle and when you distribute your custom application, you may want to save textures and sounds as external files (Miscellaneous Controls of the Preferences). They will therefore not be included in the file, which is highly recommended when you are saving several versions of the same composition. Afterwards, use the Path Manager to define the directory where your textures and sounds are saved.
  • File Compression. When you are doing a web application that must be downloaded or when you want to reduce the size of your file on your hard drive (for instance, when you are keeping several versions of the same composition), you can compress the final Virtools file (.nmo, .cmo) with a lossless compression algorithm. It has no effect on the frame rate of your composition, but, of course, the more you compress your file, the more time it takes to decompress it when loading. To set the compression level, go to the File Options of the Variable Manager.
  • Using Patch Mesh. You can use a patch mesh instead of normal mesh in your composition to make a smaller file. Patch meshes are very light to save.

Script Optimization and Behavior Graph Management

Scripting is usually not the most time consuming computing process; however, if your scripts are not optimized, they can reduce the frame rate. These basic recommendations help optimize your scripts:

  • Use Generic Scripting. This means, for instance, that when you want to rotate 20 objects, you don't create 20 different rotation scripts - only 1 with a group of objects to rotate or an array describing objects to rotate, their speed and so on...
  • Use hierarchical Behavior Graphs (BGs) to organize your scripts - separating BBs that are active once from looping BBs that are always active. (c.f. Behavior Graph Management below)
  • When you really need to do a heavy script (parsing a very long array for instance), try to distribute it on several frames instead of doing everything in the same frame.
  • To reduce file size, try to use as many shortcuts as possible for BBs using the same input values.
  • Also, you can use the Virtools Scripting Language (VSL) to replace complex calculations in place of using many Parameter Operations or even many BBs.

Behavior Graph Management

Behavior Graph Management is the time taken by the engine to parse each link and launch the execution of all BBs; it consists of finding active BBs and executing them until no active BB is left - for every "Active" script for the current frame.

The Behavior Graph management time (along with other very useful performance indicators) is provided in the Profiler. To open the Profiler, click on the Profiler button [image] in the status bar (on the left of the FPS when in play mode).

Behavior Graph Management Strategies:
Hierarchy

For optimizing rendering speed, the key is to organize your BG in a hierarchical manner. Hierarchies help to optimize culling, displaying, hiding, executing BBs, etc.

Active Scripts and Active Behavior Graphs

While the actual number of scripts is not of primary importance, the number of "Active scripts" and number of active BGs are. A common mistake is to put all the BBs at the same level without any distinction between "one shot" BBs/BGS (initialization) and "Always activated" BBs/BGS (loops).

In its current implementation, Dev's engine has to process every link when it comes to an active script and/or BG,
but it can skip processing every inactive BG/script.
VSL for Looping Processes

Loops with Zero Delay can add an important overhead. Now that VSL exists, many looping processes can be replaced by VSL code for significant boost in performance.

This becomes especially true when working with groups or arrays that are processed with every frame.

Behavior Graph Management Examples

Script 1: To Avoid

This imperfect script stays active due to the presence of a loop - even though many BBs are only executed once. Initialization BBs should be organized in a separate script (or at least be in a single BG).

Script 1: Optimized

Following the same idea, only one output of the Switch On Parameter BB will get executed at a time so we can put
those (line) BBs in a separate BG to gain precious time, simply because the hierarchical organization helps us skip the inactive parts.

Script 2: To Avoid

The example above takes more processing time than the one below.
Script 2: Optimized

In this optimized script, BBs that are occasionally activated are grouped together in a single Once In While BG that will not be processed until necessary.

BG Management Addendum

Viewing Active/Inactive Scripts

Activate Trace Mode in the Schematic toolbar to see which Scripts/BGs stay active.

If active scripts are surrounded by numerous links and inactive BBs, your script should probably be optimized.

Other Script Optimization strategies:
  • Hiding/Showing a hierarchy: Do not show/hide every objects using a Hierarchical parser but use the Hide Hierarchy/Show BB.
  • Having an object placed at the same position as another: Do not use a looping Set Position BB but instead set your object as child of the other in Hierarchy Manager.
Addendum

When we execute an active script or a graph, we first start by checking all the Behavioral Links that are at the current Level. This is because BBs have the opportunity to activate their outputs at any time (inside or outside the process loop). The Wait Message BB is an example of that kind of behavior; its output is activated as soon as the message is sent by another script. We execute Wait Message BB's subsequent behaviors only when it is executed. I.E. When we execute the script containing a Wait Message BB, we:

  1. Check all links
  2. Check if the input they are linked to were activated since last frame
  3. Potentially activate the subsequent BBs.

Other Optimization Processes

Virtools also provides the following tools to optimize the frame rate.

  • Level Of Detail. Virtools provides BBs in the "Optimization\Level Of Detail" category to automatically manage objects with a variable number of faces. These objects can either use a patch mesh or a usual mesh with the Progressive Mesh option set. With these BBs, Virtools will automatically adapt the number of faces of the object to the distance to the camera. The further away the object is, the fewer faces it has. You can also set an animation level of details to simplify a character animation when the character is far from the camera.
  • Collision Detection. When you are using obstacles with a high-detailed mesh, the collision detection process can take some time. However, it is not always necessary to have the same degree of details for rendering and collision detection. Therefore, it is very efficient to use an hidden object with a simpler geometry instead of the high detailed object. Place the hidden object at the same place than the visible object and use it for the collision detection only.
  • Variable Manager. With the variable manager, you can set the rendering option of the application and composition. Make sure to adapt them to the power of your video card.
  • Portal Management. When your world is an indoor world with several independent rooms, use Virtools portal management. Virtools provides several BBs in the "Optimization\Portals" for that. Defines portals (invisible objects) between places, the system will then automatically hide the places which portals are not visible.
  • Occluder. When you are not using the Virtools portal management, you can use the Occluder attribute of the Optimization Attribute category. When an object is an occluder, all objects behind this one (compared to the camera) are hidden, making the rendering faster. Of course, the more occluders you have, the more time you need to detect objects behind them. You'll need to find a good trade-off between time lost to detect objects behind the occluders and time gained by reducing the number of rendered objects.


Hardware Use

Hardware Use by Virtools

It is important to understand how Virtools Dev uses a computer's hardware resources in order to understand the technical limitations of your Virtools composition.

RAM

When you load a .cmo or a .vmo, all information is loaded in the computer's RAM. If you load a 50 Mo composition, you need to make sure that you have at least 50 Mo of free RAM if you want a reasonable frame rate, although more is advised since Virtools needs some free RAM for its internal processing.

You can free some RAM by specifying that textures and sprites be stored in system memory rather than in VRAM, or by not saving them in system memory at all. In that case, the texture will be loaded directly from its external source (such as the CD ROM) when needed. This option, available in the Variable Manager, is of course slower but useful for particularly large files like video.

Video RAM

As described in the Video memory occupation description of the Modeling for Virtools topics of the Online Reference, the video RAM is used to store the:

  • Z-Buffer. View Width * View Height * Z Precision. The Z Precision is usually 15 or 16 bits in 16 bits Color Depth and 24 or 32 bits in 32 bits color depth depending on the use of the Stencil Buffer.
  • Back-Buffer. View Width * View Height * View Color Depth
  • Front-Buffer. View Width * View Height * View Color Depth
  • Stencil-Buffer. View Width * View Height * Stencil Precision. Stencil Precision is usually 1 or 8 bits.
  • Textures. Texture Width * Texture Height * Texture Color Depth of the Video Memory Information in the Texture Setup.
  • 2D Sprites. Same rules than textures.
  • Videos. Only the current slot is stored in the RAM, Same rules than textures.

Even with an AGP bus, it is critical for the system to swap between the RAM and the VRAM; therefore, you should never have more textures displayed in a view than what can be stored in the VRAM. You can of course have more textures in the entire composition as long as they are not all used in the same view.

CPU

The processor is in charge of the following process:

  • Object management
  • Behavior management
  • Video, texture and sound decompression

GPU

The graphic processor unit mainly takes care of transformation & lighting computation (if supported by the board), textures mapping, and drawing the scene. The card's technical limits determine the graphic limits of Virtools compositions for polygon number, transparency, additional material channel...

Sound Card

A sound card plays the sound and potentially accelerates the decompression of sounds.


Virtools Rendering Process

Rendering is the action of transforming a 3D world scene into a 2D picture displayed onscreen. Virtools goes through several steps to perform a rendering. These steps, described below, are organized to facilitate comprehension rather than to depict the exact order in which these operations are performed. The final order depends on the type of rasterizer you are using (OpenGL or DirectX based), and part of the process is repeated for each object of the scene.

Viewing Frustrum

The system first need to know what part of the world is visible for the final picture, this volume is called the Viewing Frustrum. In Virtools, the view frustrum is defined through the current camera's field of view, aspect ratio, near and far clip as shown in the following picture (see the Camera Setup documentation). On this example, both the sphere and the cube are visible to the camera and will finally appear in the 2D picture.

Culling

With the view frustrum defined, the system must verify what objects are actually in this volume - i.e. is visible - and will need to be rendered in the final picture. This action is called culling. Every object in the scene must be checked to know if it is intersecting the view frustrum or not. Since this process can be very time consuming when a scene contains many objects, Virtools uses the hierarchy of the scene (available through the Hierarchy Manager) to speed up the culling operation. The system does the following process starting with the root objects (object without parent) of the scene.

  1. Take an object, clip it to the view frustrum.
  2. If is is visible and entirely included in the view frustrum, children are marked as visible as well, then find the next object at the same level and go back to 1,
  3. If it is partly visible, take its first child and go back to 1 with the first child.
  4. If is is not visible, find the next object at the same level and go back to 1.

For instance, on the following example, we have a camera focusing on a single tree, and it sees only a small part of the field that is made of 4 squares. In the first design, there is no hierarchy - every object is a root object. In the second design, each tree is a child of the field portion it is lying on.

Let's calculate how many checks the system must do:
- In the first design, there is not hierarchy, so the system must check 12 available objects one after the other.
- In the second design, the system first checks the 4 root objects. Only two objects are intersecting the view frustrum. For these two, the system will then check the children (2 for each). The system checks 4 root + 4 children = only 8 objects, instead of 12.

Backface Culling

Except for "both sided" materials (see the Material Setup documentation), only faces where the normal is looking at the camera are visible (and therefore drawn). Backface culling is the action of removing all faces that turn their back to the camera.

Texturing

Texturing is a vertex transformation and is the action of mapping one or more textures on a visible object. If you are not using a software rasterizer, texturing is directly mapped by the graphics card. A graphics card uses its video memory to store textures applied to visible objects. Important: Never have more visible textures than what can be stored in your graphics card's video memory; otherwise, the frame rate may become very low.

Lighting

The system now knows what object is entirely or partly visible in the scene. The next step is the lighting calculation. Lighting influences every face of visible objects not removed by the backface culling. Each visible face must be parsed and their color updated with the light information. No automatic mechanism exists to determine which face of a visible object is actually visible within the screen and which one is not. Therefore, as soon as the object is intersecting the view frustrum, the computation is done for all faces looking at the camera of the object, even if only one of them is actually onscreen.

If you are using a Transform and Lighting (T&L) hardware acceleration, this computation is accelerated by you graphics card.

Projection & Rasterizing

At this point, objects are ready to be drawn. For the final drawing, or rasterizing, Virtools Dev uses a Z-Buffer algorithm. The Z-Buffer or Depth-Buffer has the same resolution and size as the final 2D picture. Every pixel of this buffer is associated with a depth, or distance, from the view plane. Initially, the values are set to the largest possible distance. See the User Guide's Depth of Field, Z Buffering topic for additional information on the Z-Buffer in Virtools.

Finally, the final 3D to 2D transformation is achieved using a projection transformation (either perspective or orthographic) on the viewing plane. The result is drawn on the 2D picture for each pixel where a Z-Buffer value is bigger than the new Z-Buffer value (i.e., no object is in front of the current one for now).

Transparent objects are rendered only when all opaque objects have been drawn. For a transparent objects, if the Z-buffer value of a pixel is lower than the new Z-Buffer value, nothing is done to the pixel; otherwise, the current pixel color is blended with the color coming from the object (according to the object's materials settings). The Z-Buffer value of the pixel is not changed since transparent objects are only reading the Z-Buffer and not writing on it. When the Z-buffering test is enabled (option of the Material Setup in Custom mode), this operation is done even if the ojbect's transparency value is 0 which means completely invisible. Transparent objects are not harmless to your frame rate and use resources even if they are not visible. Hide objects than rather than make them completely transparent! IE if you have hundreds of transparent objects one in front of the other, the same pixels will be updated and blended hundreds of times and can often lower the frame rate. Feel free to use transparency, but carefully!

This final drawing is never done directly onscreen (also called Front-Buffer), but on a 2D picture in the video memory of the graphic card, called Back-Buffer. Once all drawing has been achieved, the back-buffer is copied to the front-buffer. The time needed to draw the final image mainly depends on the graphic card's Fill Rate and on the size of the Back-Buffer.


Scene Management Whitepaper

Scene Management

What is a scene?

A scene is a sequential narrative section of an application. An application can be divided into several scenes. In a typical video game, you find at least 3 different sections: the game, the inventory and the highscore table. These sections are always sequential (ie: you can't be in the highscore table and the inventory at the same time); therefore, they can be considered 3 different scenes.

Why use scenes & what are the advantages?

There are several advantages to using scenes:
- A "big" performance improvement since only elements in the current scene are "activated" and processed by the behavior engine.
- Facilitation of teamwork so each member can work on a specific scene.
- Easier debugging and understanding of the application's narrative line.

Tip

You have the possibility of importing NMO files as a scene directly in the Level Manager via the Resources menu.

Remember, a scene only contains a reference to an element. So if you delete a scene, elements present in that scene remain in the Level Manager until you delete them from there.

How do scenes work?

Only one scene can be active at a time.

All Level scripts are referenced in all scenes to allow the level activation during scene activation. Currently, scenes are best used with a Level script that serves as the "Scene Manager". The Level is the best entity to hold the "Scene Manager" script because it is always activated, so it can serve as the link between each scenes (ie for life points, bonuses, etc.). The main function of the "Scene Manager" will be to launch a scene then to wait for potential messages from the current scene before activating the next one. (ie: the goal has been reached and a new scene is launched)

While it may be possible to launch one scene from another without a "Scene Manager" script, the narrative line becomes more difficult to understand, making debugging and managing teamwork more complex.

Activating and deactivating scene scripts and using initial conditions for these elements

When launching a scene, the elements contained in it can behave in a number of ways depending on their state.
States are flagged in the Level Manager using the icons A, a dash, and R, corresponding to the states of scripts and Initial Conditions respectively.

A script or object will have one of the following states:
- [image] Activate: the script is activated from the beginning
- [image] Deactivate: the script is deactivated.
- [image] Do Nothing: no action is taken

Initial Condition (IC) states only apply if an element had initial conditions applied to it.
- [image] Reset: the object is returned to its initial conditions
- [image] Do nothing: no action is taken

These states can also be forced by setting the parameters in "Launch Scene".
The following choices are available:

Activity Options
- Scene Defaults: flags for the scene in Level Manager are used
- Force Activate: all scripts in the scene are reactivated
- Force Deactivate: all scripts in the scene are deactivated
- Do nothing: no action is taken

Reset Options
- Scene Defaults: flags for the scene in Level Manager are used
- Force Reset: all objects in the scene are returned to their initial conditions
- Do Nothing: no action is taken


Importing Media into Virtools

3D Models and Animations

  • Supported Formats: Virtools Object File (.nmo), DirectX (.x), 3D Studio (.3ds)

  • Exporting from 3DS MAX to Virtools - Readme and Tutorials

  • Exporting from MAYA to Virtools - Readme and Tutorials

  • Exporting From LightWave - Readme and Tutorials

  • Tips for 3D Modeling

Images and Sounds

  • Images

  • Sounds


Importing Images

Images

Supported Formats

Still Image Files

  • jpg

  • bmp
    Both the normal and RLE modes of this format is supported (note that RLE cannot be saved).

  • pcx
    This format can only be read, it cannot be saved.

  • tga
    This format is now fully supported, including images in 32 bits with an alpha channel. Both RLE and standard modes are supported.

  • png

  • tif
    Not all varieties of this format can be read. If you wish to save in this format, you are limited to RLE and RAW modes.

    The format .gif is not supported for licensing reasons. "Animated Gifs" can easily be simulated in Virtools by using multiple texture slots for a 2D Sprite.

Video Files:

  • avi
    Moving image files (video or movie files) are currently limited to the .avi format. For a target machine to be able to read an .avi file, the codec used to encode it must be present. A number of codecs are normally installed by default with Windows or widely available media players, however to be sure that the .avi can be read you may wish to provide the codec along with your composition or ensure it is available to download.

    Video files (.avi) can be added to a CMO as either a 2D Sprite or as a Texture. Each frame of the file is considered a separate slot, with only the current frame actually resident in video memory. The rest of the animation sequence is loaded into the memory as and when needed (i.e. the video file is streamed from the hard drive).

    You are strongly recommended to import AVI files as Textures and not 2D Sprites. To play a Texture AVI file, use a 2D Frame to hold the Texture and the Movie Player BB to play. For 2D Sprites, use the Sprite Movie Player BB.

Importing an image in Virtools

To import an image in a composition, put the file in your Data Resource and drag the image from the Data Resource to the 3D Layout or the Level Manager.

  • Dragging an image will create a Texture
  • Shift+drag creates a 3D Sprite (with associated material and texture)
  • Ctrl+drag creates a 2D Sprite
  • Ctrl+Shift+drag creates 2D Frame (with associated material and texture)

You can also replace an image by loading a new image in the Texture Setup or in the 2D Sprite Setup (note that the file must be in the data resource if you decide to save images as external files).

Using Images in Virtools

Textures should be to the power of two and preferably square (for increased optimization), except where images are used as 2D Sprites, images can be any size. However, 2D sprites will take up the equivalent memory space of the next squared power, i.e. a 2D sprite of 65 pixels will take up the memory space of an 128 pixel image.

See also Texture Setup, 2D Sprite Setup, Material Setup, Material-Textures Building Blocks Category.

Saving Images in Virtools

Save mode options for Images are found in the Miscellaneous Controls section of the General Preferences. However, you can decide to use a specific mode just for that image via the Save Option in the Texture Setup or 2D Sprite Setup.

File Location:
Image files (including AVI files) can be saved inside a composition or can be saved external to a composition.
Warning: You must save image files inside compositions that are to be viewed using the Virtools Web Player.

File Format:
Still images can be saved in the following modes:

  • External: a reference to the file name and file path is saved inside the composition.
  • Original Format: The original file is saved inside composition (no compression or modification)
  • Specific Format: The file is saved inside the composition in the chosen format.
  • Raw Data: The file is included in composition as it appears in Virtools.

Note that compression for video files (AVI) is not available.

Tips:

  • Use images stored in your data resource - this will make management a lot easier.
  • If you want to export an image, use save slot in the image setup shortcut menu.
  • You can drag images from a data resource to an image slot (in texture setup).
  • If possible, do not rely on Virtools Dev to compress your images - use software (such as Adobe Photoshop, Jasc Paint Shop Pro etc.) designed to do this.


Importing Sounds

Sounds

Supported Formats

.wav

.mid

.mp3 (now completely supported)

.wma, .wm, .asf
Only the sound component of Windows Media Audio (.wma, .wm, .asf) files is currently supported by Virtools.

Importing a sound in Virtools

To import a sound in a composition, put the file in your Data Resource and drag the sound from the Data Resource to the 3D Layout or the Level Manager. You can also replace a sound by loading a new sound in the Sound Setup (note that the file must be in the data resource if you decide to save sounds as external files).

Using sounds in Virtools

Please see Sound Setup and the Sounds Building Block Category.

Saving sounds in Virtools

Sound files may now be saved inside a Virtools composition (by choosing "Included inside cmo file/Original File") - see the Miscellaneous Controls section of the General Preferences for more information.

If you choose not to include sound files in a .cmo, sound files must be
  • in the .mp3, .wma, .wm, or asf format (reminder: for Windows Media Audio formats, only sound is supported)
  • in the same folder as the Virtools composition


Supported 3D Model and Animation Formats

Overview

Please check the Virtools website regularly or join the Virtools Users' Group mailing list for the latest news of any new formats supported, the latest recommendations for modeling, and information on new plugins for Virtools.

  • Virtools Object File (.nmo):
    The native file format for characters and objects in Virtools is .nmo. NMO files contain one or more elements, with or without their applied Scripts. NMO files are produced by export plugins or exported directly from some applications.

    Note: You can also save NMO files from Virtools Dev itself.

    See Also:

    • Exporting from 3DS MAX to Virtools
    • Exporting from Maya to Virtools

  • DirectX (.x)
    The format .x is a format developed by Microsoft as part of DirectX.

    Virtools fully supports the standard .x format that only contains information on simple models and animations. The standard version of .x contains no information on cameras, lighting etc. However, .x can be expanded to include further features - Virtools will not read this extra information.

    • To be sure of exactly what information is stored in .x files you create, consult the documentation that comes with your modeling application.

  • 3D Studio (.3ds)
    The format .3ds is a format developed by Autodesk.

    As with .x, Virtools fully supports the standard version of .3ds- but .3ds files can be expanded to include extra information will not be read when importing to Virtools.

    To be sure of exactly what information is stored in .3ds files you create, consult the documentation that comes with your modeling application.

    Should you decide to save a file from 3D Studio Max in the format .3ds, you will have no control over the choice of scale. This will only be problematic if you are not using meters as your scale, as Virtools uses meters for scale.

  • Notes on Creating .3ds and .x Characters and Animations
    If you wish to import a character into Virtools via the .3ds or .x format:

    1. only one character per file (.3ds or .x)
    2. the character must be hierarchical with one root
    3. the character must be animated in key frames only
    4. there must only be one animation per character file
    5. normally you can export just character animation files on their own without any meshes - refer to the documentation for your modeling application

  • Importing Objects and Object Animations
    Several objects may each have a unique animation, i.e. you are not restricted to one animation per file as with characters.

3D Models - Objects

To bring objects into Virtools,

  • place your file in a Virtools Data Resource.
    When you drag the file from a data resource into the 3D Layout or Level Manager, any animation(s) attached to an element contained in that file will appear in the Level Manager, under the element(s).

  • use the Import File command from the Resources menu in Virtools.
    Any animation(s) attached to that element and contained in the imported file appear in Level Manager, under the element(s).

    If you have just one object and/or animation, use a building block such as "Play Animation 3D Entity" (3D Transformations/Animation) to trigger the animation.

    If you have several objects, use a building block such as "Play Animation 3D Entity" on each object to control each object's animation individually, or use a building block such as "Play Global Animation" (3D Transformations/Animation)to trigger all animations at the same time.

    Note: To use "Play Global Animation" you MUST place your file in a data resource - using the Import File command from the Resources menu will NOT work.

3D Models - Characters

  • either place your file in the characters folder of a Data Resource.
    When you drag the file into the 3D Layout or Level Manager, the character's animation will appear under the character in the Level Manager.

  • or use the Import File as Character command from the Resources menu in Virtools.

In both cases, to configure the animation you will need to use building blocks such as Keyboard Controller (Controllers/Keyboard) and Character Controller (Characters/Movement).

Additional Character Animations

To make additional animations available to a character, place the files containing the animations into the animations subfolder of characters in the Virtools Data Resource. To attribute these animations, drag them from the animations subfolder within Virtools onto your character in the 3D Layout. Again, to configure the animations you will need to use building blocks such as Keyboard Controller and Character Controller.


Modeling for Virtools

Before Starting to Model

The key to modeling for real-time 3D content in Virtools is knowing

  • the target hardware
  • how the models will be used
  • limitations when converting to the NMO format

The choice of hardware (the processor, system ram, graphics card and video ram) is potentially very important - especially how the target machine's graphics card handles textures. Can you use texture maps of 512 pixels? How many MB of textures does the graphics card hold at a time? What filtering techniques does the card support?

You must think of what will happen in the scene before starting: will objects be fixed or animated, will you need transparency, will you need invisible objects to help collision detection, do models have to be be seen from both sides... Only when you know how your scene or models will be used, should you start to model, trying to optimize things whenever possible.

You also need to be aware of any limitations when converting to the NMO format. You could design a wonderful model or character using techniques that are not exported, resulting in frustration and many hours of lost work. When using an exporter, make sure you read the documentation that comes with it - or the scene you see in Virtools may not be what you planned. Be aware that not all exporters support the same features.

Below you will find some points and tips to take into consideration...

3D Design/Organization

Eliminate unneeded facets
Eliminate non-visible faces, depending on the camera's view.

Grouping objects
Combine and group at the same location objects using the same material to simplify the scene hierarchy.

Separate large objects
Separate huge objects into parts, it will free the memory and decrease the render time, all the parts will not be treated as they will not be in the camera zone at the same moment.

Subdivision Level
Particularly for round objects, you have to choose the good subdivision level and adjust the visual quality with the normal angle to keep a maximum smoothing.

Billboards (3D sprites)
The faces reduction process can be in an extreme case a transformation of your object into an auto-orientable 3Dsprite.

Repeated objects
Repeated objects can be duplicated and positioned directly in Virtools, the object entity is really doubled but not the mesh. The new object always refers to the original mesh so it's quite faster and save file size.

Normals: transparent objects, inverted normals
List transparent objects using an alpha mask or those which must be seen from inside.
When using "Both Sided" materials, face normals are not duplicated : the normal orientation remains the same but no backface culling is done.
Objects seen from inside needs inverted normals and a material with "Both Sided" to OFF.
Face Normal orientation is used by some building blocks such as Object slider : make sure to orientate face normals correctly to allow collision processing according to your needs. If a camera must fly inside a tube, with collision detection make the normal point inside the tube.

Nomenclature
Always name correctly your objects and materials before exporting. (Avoid names like poly011221). You should ensure all elements have a unique name - for example object, object_mesh, object_mat and so on.

Triangulation
Check yourself the triangulation to avoid non-desired results due to the automatic triangulation.

3D objects or maps?
You have to make choices in your scenario, an object can be in real 3D or transformed in a pre-lit map coming from a hi-res render. Sometimes a mapping is more visual than a 3D object and produce a great optimization.

Fix objects
Each objects or characters must be scaled rotated and positioned correctly before exporting.

Create specific models
The scenario gives you the idea to create behaviors and for this, to create specific models, invisible, for collision detection or other special needs.

Organize objects in Virtools
Once in Virtools, organize 3D objects in the 3D Layout into Places to manage them easier. Places will allow you to use portal management.

Scaling
When you have finished modeling, set the scale size of all objects to (1,1,1). This is because some BBs (notably for collision avoidance/detection) are optimized for objects with a uniform scale size.

Small Objects
Several low resolution (< 100) objects display may create overhead. If you have to display several low resolution objects (i.e. stones in a river) you may merge them in one single mesh, if your interactivity allows it (the stones will move together as they are a single object).

Moving and Non-moving Objects
Separate moving objects from fixed objects.

Hierarchy
Avoid too many root objects or group them in a hierarchy so that the render engine can perform culling, so removing unseen branches from the rendering process and improving the FPS.

Lights & Textures

Render techniques
Several techniques are possible to render a mesh: a colored material (without any texture), vertex lighting, simple texture mapping, mapping with pre-lit textured. Then it is possible to combine these methods to achieve a more sophisticated work.

Default render
Objects are simply colored with their materials without using texture maps, essentially a rush level technique to quickly ensure that objects run correctly in the real time engine.

Vertex lighting
You can write a color value (RGB) and even a transparency (Alpha - RGBA) value into each polygon vertex. The object doesn't need real time lights anymore to be lit, it is self-lit.

Texture mapping (UV)
First you create projections of pictures over the objects, then mapping coordinates of these projections _ UV_ are written in the object topology and you can tweak then. Realistic textures increase the quality aspect of your scene.

Pre-lighting
Pre-lighting is still a mapping technique but here, image maps are pre-lighted maps : representations of the objects including lights and shadows, obtained by a 3D hires render.

Mixed methods to reach a superior level in term of quality
Vertex lighting with mapping (in fact its principal reason of being).
Vertex lighting with pre-lighted maps for a really high quality visual level, and scene optimization.

Textures: types and sizes
Isolate textures that will be repeated (tileable) and grouped in compilations (using texture cropping), from the others that will not (pre-light maps non-tileable). Maps must respect some size constraints and have a size calculated with a power of 2. Although, they are not obliged to be square (like 128x128), they can be in 128x256, 512x32…
Limit the texture size to allow low VRAM graphic card to display your content correctly

Video memory use
Virtools Dev uses three buffers for rendering:
Front buffer - what you see on-screen,
Back buffer - where the scene is rendered before swapping the Front and Back buffers,
Z-Buffer - used to perform object occlusion calculations (i.e. what if element A is in front of or behind element B).

The memory used by these 3 buffers is calculated in Bytes: W * H * (CD * 2 + ZD) / 8, where
W and H are the Width and Height of the scene to render window (windowed or full-screen),
CD is the color depth of the display in bits (either 16 or 32 for Virtools), and
ZD is the Z-Buffer depth in bits (again 16 or 32).

In addition to the memory required for buffers, you have to calculate the memory required for textures that rendered elements and 2D Sprites use. Regardless of whether a texture is used partially or entirely, the calculation is the same - the memory required for each Texture in Bytes is: W * H * CD / 8, where
W and H are the Width and Height of the Texture, and
CD is the color depth of the display in bits (usually 16 or 32, check the Texture Setup for a particular Texture).

An example: to render a scene in fullscreen at a resolution of 800*600*16 with a 16-bit Z-Buffer, the buffers will require 2 880 000 bytes - i.e. 800 * 600 * (16*2+16) / 8 = 2 880 000 bytes. If the composition contains ten 256 * 256 * 16-bit textures that display simultaneously, these textures occupy 10 * 256 * 256 * 16 / 8 = 1 310 720 bytes. The total memory required for the scene is therefore 1 310 720 + 2 880 000 = 4190720 ~= 4 MB. This is already pushing the capabilities of a 4 MB graphics card.

If the video card does not have enough memory for the textures, Virtools swaps textures between the video and system memory. That can result in a sluggish and unsatisfactory display, since transfer between video and system memory is slow. Therefore calculate the maximum video memory your composition requires, to make sure that your target video cards can handle the load.

N.B. Don't forget to include Textures used by the Sky Around BB if you use this BB.

UV tweaking
Don't stop your work at the automatic mapping job level. Take time for tuning UV, reuse some compilation (cropping) zones over other object parts or even other objects.

Organize your maps
When you make compilations, you must try to group the pictures by zone or by object.
Note that a texture can not be cropped AND tiled.


Exporting from 3DS Max to Virtools

  • Readme.txt for Virtools 3DSMax Exporter Plugin

  • Tutorial: Simple Animated Scene
  • Tutorial: Modeling in Character Studio
  • Tutorial: Exporting Characters and Animations


Exporting Characters and Animations from 3ds max

Overview

This document is to show you how to export a character created in 3D studio max to the Virtools file format (*.nmo) using the Virtools 3DS Max Export Plugin.

Before attempting to export a character, please make sure you have read the readme.txt accompanying the Export Plugin, and that you follow its guidelines and restrictions.

Some of the steps below, in italics, will only apply if you have used Character Studio Biped and Physique.

You will find the files used in this example in the Virtools Dev program folder: Documentation/ExporterFiles/Max_tutorial_character. If you do not find these files, you will have to launch the Setup.exe of the Virtools Dev CD once more and install the sample files.

Note: When creating animations, you should be very careful what you do with the FloorRef. When walking or running, the character should stay at a constant height from the FloorRef object. When jumping, the Character should increase it's distance from the FloorRef object to give the appearance of translation away from the floor. Characters should ALSO have a "stationary root" that only moves relative to the floor reference (e.g. for walking, jumping etc.) but that does not move constantly (i.e. in an idle animation the root should not move). This is very important if you wish to use your Characters with the Virtools Mulituser Pack, or the dead reckoning algorithm used for predicting distributed objects will not work correctly. In short:

  • Make sure the (stationary) root element does not move at all when the character is in its default ('wait' or 'idle') animation.
  • For other animations make sure the root moves a minimum; in a walk animation along the Z axis for example, make sure that the root moves along the Z axis only - there should be no movement on the X or Y axes.

Note: Ensure the animations you create are 'real' in the sense that the Character actually performs them and does not 'pretend' to perform them - e.g. for a walk animation you should ensure that your character actually moves (translates) in your modeling application, and does not perform the animation in situ ("on the spot" or "in place").

Note: If you export a character animation and the character changes direction in this animation and you which to put another animation in sequence after this one, make sure to check the "Align Character animation" check box when exporting both animations..

Character and one Animation

A character is normally exported with an animation, commonly the stand or wait animation. You can however export any animation when you export your charaacter - this example uses a run animation.

To do this, follow these steps:

  1. Ensure you have both your character and animation file open in 3DS Max (Jack01.max and Jack_run.bip).
    For real-time 3D content you need to use models with a as low a number of faces as possible, and that with animations you must choose the right compromise between fluid actions and light file sizes.

    WARNING: A character must only have one root, otherwise character animations will not play correctly!

  2. Open the timeline, so that you can

  • adjust you animation, by adding or deleting keys, changing the animation length or position of keys etc.
  • check that the controllers for your animation are of type Bezier, Linear or TCB only.
You are advised to use Bezier, Linear or TCB animation controllers (Position, Rotation and Scale controllers). The exporter can convert any unknown animation controllers (such as an IKController, PathController or procedural controller, etc..) to a standard animation by sampling the object animation. However, the file size for a sampled animation is typically much larger that the file size for a keyframed animation.
  3. If the Bip01 Footsteps object is frozen, unfreeze it in the tab Display in Character Studio.
  4. Check that In Place mode is not selected, unless you wish your character to perform its animation on the spot.

  5. To export the character with this first animation, select Export from the File
    menu, then Virtools Export (*.Nmo). The Virtools Export dialog box will appear as below.

  6. Select the Export as a Character check box, and give both the character and the animation a name.
  7. If you are using Physique, ensure Convert to Skin (default is selected).

    Note: Morph Animation has been kept for backwards compatibility but you are strongly advised to use Skin due to equivalent performance at much smaller file sizes.

    Note: If your character is using an unsupported controller for a particular object, such as clothing (a coat or cloak for example), you can still use Skin:
    • ensure the particular object has a mesh that is separate to the Character's mesh (skin)
    • choose Convert to Skin as Physique conversion
    • set a rate for Frames per Sample in Controllers Output (see below for more information), as the unsupported controller only will be translated to mesh morphing.
  8. You only have to use the Controllers Output section if you have used non standard, that is non-PRS (Position/Rotation/Scale) controllers using Bezier, Linear or TCB keys.

    The exporter can convert any unknown animation controllers (such as an IKController, PathController or procedural controller, etc..) to a standard animation by sampling the object animation.

    The frame per sample parameter indicates the period between two keys that will be generated. (For example a 100 frame long animation sampled at 3 Frames per sample will generate an animation with 33 keys).

    3ds max also enables you to animate meshes with morph animations or modifiers such as bend, taper, etc... Virtools does not support such modifiers but the exporter can again convert them to a morph animation using the "Animated Object" sampling rate in the same manner as above.

    Note: Modifiers that add or remove faces to an object during an animation will NOT be converted.

Animation only

If you wish to export an animation only, follow the above steps, but select the Export Animation Only radio button. Note that you can only export one animation at a time.


Modeling with Character Studio

Introduction

This document explains one way of creating a character in 3D Studio Max and Character Studio, using Biped and Physique. This character can then be exported to Virtools Dev as a skin character using the Virtools export plugin.

You can find sample 3ds max source files (.MAX and .BIP) and the resulting Virtools Object files (.NMO) of the character Jack, used to illustrate the method outlined here in the Virtools Dev program folder: Documentation/ExporterFiles/Max_tutorial_character. If you do not find these files, you will have to launch the Setup.exe of the Virtools Dev CD once more.

WARNING: A character must only have one root, otherwise character animations will not play correctly!

Modeling a Character

  1. In 3ds max, open the file jack00.max. This character has been created with a relative low number of faces (around 600) so as to be compatible for real time 3D content.

Using Character Studio

  2. In Character Studio, create a Biped.

    Make it the same size as the character.

  3. Select the Biped's center of gravity, and switch to Figure Mode.

    Move the Biped so that it's spinal column is centered, and so that it's center of gravity is level with Physique's crotch. Place the Biped on top of the character.

  4. To mold Biped to the shape of the character, select any part of Biped select the Motion toolbar select Figure mode to modify the Biped so that you can adapt it to the dimensions of your Character In the Structure toolbar, define the number and lengths of Biped limbs and other body parts.

    N.B. You can often optimize real-time biped characters by defining one finger per hand and one toe per foot

  5. Using and Rotate, define the orientation of the legs, and then the arms. Once the limbs have been orientated correctly, use Scale and Non-Uniform Scale to adapt them to the form of the character's skin.

  6. Once you have placed the Biped correctly inside the character's skin, select Skin and apply the Physique modifier.

  7. In the Physique panel, select the function Attach to Node. Next select the root.

  8. A Physique Initialization dialog box will appear. Select No Blending - now the vertices can be manipulated.

    The character now has Physique, and you can adjust or deform the vertices. Certain parts of the body should remain rigid (e.g. for a human, the head and feet should remain rigid).

  9. In Physique, click Sub-Object, and select Vertex in the pull down menu. If you select all the vertices, you will see that are all in red meaning you can deform them.

  10. In Vertex Link Assignment, click Select to identify the vertices of the character which must remain rigid, such as those attached to the head.

  11. Ensure all 3 buttons are selected. Select the vertices which make up the head.

  12. Click Assign to Link, and ensure only the green button is selected. Select the vertices which make up the head - you will see that they change color from red to green. Repeat steps 10 to 12 on other body parts which should remain rigid, such as each foot.

Animating the Character

There are several ways of animating a Biped character in Character Studio. The easiest method no doubt is to create a standard walk animation using Create Multiple Footsteps, and then to alter it manually afterwards. Another method is simply to animate the character manually in free form.

Whenever you create your own animations, you should make sure that the animation is a complete cycle so that the animation does not 'jump' when played in Virtools.

Note: When creating animations, you should be very careful what you do with the FloorRef. When walking or running, the character should stay at a constant height from the FloorRef object. When jumping, the Character should increase it's distance from the FloorRef object to give the appearance of translation away from the floor. Characters should ALSO have a "stationary root" that only moves relative to the floor reference (e.g. for walking, jumping etc.) but that does not move constantly (as with an idle animation). This is very important if you wish to use your Characters with the Virtools Mulituser Pack, or the dead reckoning algorithm used for predicting distributed objects will not work correctly. In short:

  • Make sure the (stationary) root element does not move at all when the character is in its default animation.
  • For other animations make sure the root moves a minimum; in a walk animation along the Z axis for example, make sure that the root moves along the Z axis only - there should be no movement on the X or Y axes.
  1. If you wanted to create a stand animation for this character, you would record the character in a stationary position, typically 30 or 40 frames.
  • Select the Biped

  • In the Motion panel, click Footstep Mode

  • Click Create Multiple Footsteps
  2. To create moving steps:
  • Clear the FootStep Mode check box

  • Click Animate

  • Animate your character just as you would animate any other object in 3ds max

  3. As an example, you can load one of two animations (a run - Jack_Run.bip and a stand - Jack_Stand.bip) already created. For now carry on with Jack_Stand.bip:
  • From the Motion panel, select General, Load File
  • Load the file Jack_Stand.bip

  4. Click Time Configuration,

  5. In the Time Configuration dialog box, enter 40 for End Time so that the animation can play one complete cycle.


Exporting a Simple Scene from 3DS Max

Exporting a Simple Scene from 3DS Max to Virtools

Introduction

This tutorial explains how to export a 3D Studio Max scene from 3DS Max version 3. Before you start this tutorial, ensure you have installed the Virtools Exporter plugin for 3DS Max.

The Scene in 3DS Max

Load the sun_room scene located in the scenes folder for this tutorial into 3DS Max.
When the file is opened it may indicate that certain textures are missing. If so, simply find the path to the textures in Map_RT.
Here is what you should see:

Activate Display, Polygon Counts - you will see that the scene contains 474 faces.

Note a certain number of specific characteristics before exporting this set:

Vertex Lighting

Select the wall_Small object, for example, and you will see the attributes of the Vertex color (the color attributed either by calculation of the lighting in the scene, or manually with the Vertex paint modifier).

The Vertex paint or Vertex color modifiers can be used to simulate shadows or shades of light in the scene. These values will be exported to Virtools.
The advantage of using Vertex paint or Vertex color is that you can add the light you want without adding real-time lighting: you thus save CPU time. However all real-time lighting will have no effect on these objects. (It all depends on the effect you want to get.)

Textures and Materials

The kitchen_part02 object, for example, has a transparent material called glass_table. For this object, the material is exported in 2-sided mode. Both the transparency and the 2-sided feature are exported to Virtools. (Diffuse parameters are also exported to Virtools.) The only difference is that, unlike 3DS Max , Virtools will mix the diffuse color and the texture. If you want an unmixed texture, set the diffuse color to white.

The ambient, diffuse, specular, self-illumination and opacity parameters can in fact all be exported.

Texture Cropping

The Wall_Right_mat, Wall_Left_mat, Wall_Face_mat, Wall_Front_mat objects use the same texture: wall_total.jpg, but not the same material.

These objects use the cropping technique, which consists in using different zones of a single texture. The advantage of this technique is that you can save memory access time, by using a single large texture instead of 4 small ones, so improving your composition in Virtools.

Collision Objects

Certain objects are modeled for use as collision objects, so that you can use specific Virtools behaviors. For example, you could create collision_objects that can be used to test collisions with the low wall. Note the direction of the normals on this object; they are used by collision detecting Building Blocks so the normals need to be oriented correctly.

Lighting

In this scene all objects are self-illuminated by placing their own shadows on all the objects. This is another technique that can be used to light objects in the scene; lights can of course be exported and can be used, for example, to illuminate objects.

Exporting Data

To export your 3DS Max scene, select File/Export. If you want to export only part of the scene, select File/Export Selected
and name your file (sun-room.nmo for example). The following dialogue box will appear:

Since it is an object, select the Export as Objects radio button. The Animation name box is unimportant because the scene does not include any animation. And there you go!

You now have an nmo file that can be imported in Virtools.

Loading the Scene in Virtools

The result of this export should be exactly the same as the sun_room.nmo file in the Documentation folder: ExporterFiles/Max_tutorial_scene. To open your file either

  • place sun_room.nmo into the 3D Entities folder of a data resource and drag sun_room.nmo into the 3D Layout or Level Manager, or

  • from the Resources menu, select Import File and navigate to where you saved sun_room.nmo.


Exporting from LightWave to Virtools

Exporting from LightWave to Virtools Dev

Description

This document shows you how to export your objects, scenes, textures and animations from LightWave to Virtools Dev. (It does not cover the general use of LightWave; understanding the LightWave Modeler or LightWave Layout is a prerequisite.)

Please read the Readme.txt file first.

Then read this introduction for a general overview before starting the six tutorials that cover:

1. Exporting a simple object from Lightwave Modeler
2. Exporting a layered object from Lightwave Modeler
3. Exporting a simple object from Lightwave Layout
4. Exporting a Body Part Character from Lightwave Layout
5. Exporting a Skin Character from Lightwave Layout
6. Exporting Atlas UV Maps from Lightwave Baker

Introduction

LightWave and Virtools

LightWave is built with two separate software that work together. Those two different parts work differently and serve different purposes, and that is why Virtools decided to create two different exporters: one for the Modeler and another one for the Layout.

From the Modeler

This exporter only exports the objects and their defined materials.

Note : in some cases, the appearance of the materials inside Virtools may not work. It is then recommended to re-install the plugin.

From the Layout

This exporter will export all parts of your scene, including (depending upon the options chosen): objects, characters, animations, lights and cameras.

Virtools Exporter Plugin

To export from Lightwave to Virtools’ native file format (.Nmo), you need specific LightWave plugins to translate the file format of your scene or your object into a Virtools format file (.Nmo)

Since there are two different exporter plugins for the Modeler and the Layout, you need to install both plugins: one inside the modeler, and another one into the layout.

Inside the Modeler

Lightwave’s modeler gives you the ability to create different objects, and assign their materials and textures.

Pivot Point

Inside the Modeler the pivot point is referred to as the center of the Modeler’s World.

Note : the pivot point is not modifiable inside Virtools.

Modeling

Faces and triangulation.

You can set the Modelers options to quads as to lower the vertices number, but you should know that in some cases triangles are far more useful than quadrangles, especially for organic forms and moves.

Besides, you should know that most of the graphic cards finally work in triangles, therefore, it is sometimes advisable to work in triangles from the start.

Normals

If you create a composed object, by making a « lace » from a curve (ie. bottle object), be careful of the normals direction, and try to never use the « both sided » option since it forces the real time render to render twice the mesh.

Layers

Inside Lightwave’s modeler, a very useful part is the layers. If you happen to be using these for creating your object, know that the Modeler’s exporter will export only one object from the layers you would have selected. This may not be a very handy method if you need to get back onto your different objects inside Virtools.

On the other side, each layer may define a particular material, making it very interesting to create multilayered objects. In deed, one can chose to keep a layer for each material, so that once inside Virtools you can access different materials directly from the setups. All of these are explained inside example 1.

Surfaces

Surfaces defined inside Lightwave’s Modeler will be exported as Materials.

Surface Editor

If you don’t assign a specific UV onto your surface, the exporter will export a mesh with a 0,0 UV vector making it impossible to show correctly a texture. Therefore don’t forget to assign maps on your surfaces or to « make UV’s » .

Textures

From the Surface Editor, the only texture you will be able to export will be the « color » texture that will keep the UV’s set to it, the map type, and the bitmap assigned to it.

Note. No behavioral textures can be exported from Lightwave. Only the bitmaps can

Textures dimensions

You need to be careful to export textures which’s dimensions correspond to squares of to 32,64,128,256… up to a maximum of 2048, knowing that only a few graphic cards accept such big maps.

Textures blending

No option of transparency or bump will be exported (set inside Virtools), but Color, Specular, and Diffuse are exported as defined, without any bitmap texture.

Texture Layers

All the layers added to the texture will be exported into a new « channel » in order to mix the different bitmaps. But know that each added layer adds a computing « path » slowing down the real-time process.

Inside the Layout

Layers from the Layout

Objects which have been built with different layers are exported separately (as different objects).

Pivot point

The pivot moves will NOT be exported, so be careful to set your pivot point’s position once for all, as a basis of your object.

Surface Editor

The surface editor is exactly the same as in the modeler, therefore all the modifications for texture, blending and mapping are exactly the same and will be exported in the same way.

Baker plugin

The baker plugin is supported inside virtools. It recognizes the « atlas » UV’s of you surfaces and keeps the assigned Map for the « materials » inside virtools to work with.

Characters

A Character is a very specific class of object once inside Virtools. It is advised not to define a character unless it contains proper animations such as an arm or a leg moving and a hierarchy.

Body parts vs skin

Inside Virtools we make a distinction between Body parts and skinned objects. Skin objects will refer to a bone structure that is responsible for the parts moves. Body parts are just objects parented one to the other.

Exporting with body parts.

Body parts are the different parts of a composed object called « character ». Each body part is actually a simple object, but parented to a hierarchy.

The Hierarchy is exported exactly as defined into the « scene editor ».

The fact of exporting an object with a parented structure doesn’t mean you are exporting a character. It will export all the objects, and the parenting but the animation will be set as a « global animation » and therefore won’t be assigned specifically to this structure.

Exporting with bones

Inside Lightwave, bones are specific objects that will affect the shape of the objects that are near enough of it.

Inside Virtools, the bones are only the pivot points of those objects. The amount of effect is kept as a resulting movement, and not as parameters that will change the object.

Animation

Simple animations

Some animations are not needed inside Virtools because most of the simple movements will be made by behaviors. In other words, there is no need of creating an animation for sliding an object on a line, or performing a rotation, these will be scripted easily inside Virtools Schematic.

Structure animations

You need to define inside your animation all the movements that change a structure. For example, an object that unfolds itself is a perfect case of structure animation. By doing this, you simplify the work inside Virtools where an animation will create the moves that would have taken a big script to create.

Character animation

Characters correspond exactly to the amount of complexity that calls for a designed animation where you need to define a hierarchy, sometimes even a skeleton, and make it move. Each part of the hierarchy, or skeleton that is inclined to move must be defined, or by an object (body part) or by a bone (skinned object).

Animation distances

For efficiency, one should always add the distance to the animation which is made. For example, a character walking should not only moves is legs, but actually displays himself of the distance implied by his walk.

Different animations

Inside a same file, one can have several different animations. The best technique is to put all the different animations one after the other and register them one by one, giving them an explicit name (stand, walk, walkback…).

To export them separately, be sure to check off the « export character » and to set the correct numbers for « start frame » and « end frame ».

Restrictions

For rotation more than 180°, be sure to add a frame, if not the animation may be truncated, or act weirdly.

Tutorials

The following exercises are presented in order of complexity . You may start with any one, but it is advised to practice them in the following order.

In the following section you will find 6 examples :

1. Exporting a simple object from Lightwave Modeler

2. Exporting a layered object from Lightwave Modeler

3. Exporting a simple object from Lightwave Layout

4. Exporting a Body part Character from Lightwave Layout

5. Exporting a skin Character from Lightwave Layout

6. Exporting Atlas UV Maps from Lightwave baker


Exporting from LightWave - Exercise 1

Tutorial 1 – Exporting a simple object from Lightwave Modeler

Build an object

After opening your Lightwave modeler and activating the plugin (check the ReadMe.txt file), go to « Create » section box « box » and create a box with 9 faces on its Y faces and only 3 on its sides, check for its size to be 1 meter on each axis, and its center (pivot point) at 0,0,0.

Set surfaces

Using the polygon selection level, select the whole cube and, using the « Change Surface » tool, set them to « red » and change the color.

Then choose a side of your cube and another surface so that you have of two different materials on the same object.

Give the surfaces a map

Using the surface editor, select the « red » surface and click on the « T» button of the « color » line to add a map (« load image »). Be careful of the mapping type you use (cube or planar) and check the scale - you may need to set the scale to « automatic ».

Do the same for both surfaces and then simply export.

Export

The export is straightforward, just give your file a path and a name.

Import into Virtools

Open Virtools and go to the « resources/import file » and chose your saved file.

You should see a cube with the same dimensions. If maps appear in black, just add a light to the scene for the textures to show.

Notice its pivot point is exactly in its center, at 0,0,0 coordinates.

If you go inside the « Level Manager », you will find a 3D object named like your file, and 2 materials, named like the surfaces you made inside the Modeler.

If you get to the « material setup » you will find out that their « ambient » color corresponds to the color you set to the surface defined in the Modeler.

Next exercise: Exporting a layered object from Lightwave Modeler


Exporting from LightWave - Exercise 2

Tutorial 2 – Exporting a layered object from Lightwave Modeler

Build an object

After opening your Lightwave modeler and activating the plugin (check the ReadMe.txt file), go to « Create » section box « box » and create a box that is wide and small to create a table.

Adding new boxes to the same layer, build the legs of the table.

Build a second layer

On the second layer, build a bottle by « lacing » a « curve ».

Set the surfaces

On the first layer, select the whole table as « polygons » and define a « surface » for the full table.

On the second layer, first select the upper part of the bottle, and set it to a gold « surface ». Set the lower part as a glass « surface », and then chose a few polygons on the front of the bottle to set as a label « surface ».

Give the surfaces maps

Using the surface editor, give each surface a map.

Export

Before exporting your object, be sure to select both layers. Only the selected layers will be exported.

Import into Virtools

Inside virtools, you will find back both your objects, but as one mesh

Check for the different materials

Each defined surfaces is inside Virtools Dev defined as a « material ».

Next exercise: Exporting a simple object from Lightwave Layout


Exporting from LightWave - Exercise 3

Tutorial 3 – Exporting a simple object from LightWave Layout

Import an object

From a previous model, import a LWO file into your LightWave Layout program. If you are using the file from the previous exerciseon the previous file, you may find it with set materials and textures already.

If this is not the case, you may set them inside the Layout as well.

Set a surface

This section only applies if you haven’t already got a surfaced object with maps.

Give the surface a map

This part only applies if you haven’t got already a surfaced object with maps.

Export from the Layout

Inside the export interface, uncheck all the buttons except for the export, objects, lights and maps.

Import into Virtools

Inside Virtools, chose the Resources/Import file menu and check that all the objects appear inside the Virtools Layout, with all the textures, materials. Note that in opposition to exporting from the Modeler, all objects are seperated, even if they were made as different layers inside a same object.

Next exercise: Exporting a Body Part Character from Lightwave Layout


Exporting from LightWave - Exercise 4

Tutorial 4 – Exporting an animated Body Part Character from Lightwave Layout

This tutorial will show you how to build a mechanical spider, create a « walk » animation and export them to Virtools to get an interactive walking spider.

Build your characters objects

The 3 different body parts you need to animate your spider :

  • the body
  • the upper leg part
  • the lower leg part

    • As with any body part animation, you need to build all body parts separately. With LightWave, you can chose between separating them into layers or building different objects.

    Pivot Points

    Whichever technique you chose, you need to think ahead on the pivot points’ position. In fact, the Modeler will place the pivot point in the center of the world. Therefore, you need to place your object corresponding to its supposed pivot point.

    It is therefore far more practical to set your objects’ pivot from the start. Of course it is possible to change the pivot points position and orientation inside the layout, but this operation is sometimes very tricky.

    Set surfaces

    Since your objects are separated, don’t forget to assign surfaces. For our example, we simply assigned a « metal » surface to the whole spider.

    This operation can be done also inside the layout.

    Give surfaces maps

    This operation can also be done inside the layout.

    Once your finished with the model, simply save your object for the layout, or jest send it to it.

    Organize the hierarchy

    Inside the Layout, import your three object. If ,as advised, you have set the pivot point in a correct position, you should find back your three objects all together in one place.

    First of all you need to clone the leg parts to finally use 4 separated legs.

    Open the « scene editor » to parent your objects. Drag and drop the lower part onto the upper part, and the upper parts onto the body. To check that the parent structure is correct, simply move the body and check all the legs follow.

    Animate

    To animate the spider, you need to first fold the legs. Fold the lower leg part downward, and the upper leg part slightly upwards.

    Once you’ve done this to each leg, you need to place the legs in a start position.

    By setting the view to « top » you can place the legs in a symmetrical position and register this key frame for « all the items ».

    Set your animation’s length to 30 frames.

    Place yourself at the last key frame (30), and set this last key frame for « all the items » so that you are sure the animation will cycle with the start key frame.

    For the in between moves, it is just a matter of setting keyframe 15 with the opposite position (front leg to back etc…).

    In between, you need to lift up the legs after they’ve been to the far front, until the have reached the back.

    Once you have animated the four legs, you need to displace the body.

    In deed, virtools won’t generate the displacement of the object, it will just perform the animation. Therefore, you need to induce the distance into your spider animation for it to actually move, when it walks.

    Once you animation is correctly set, you may check it with the player.

    Don’t forget to save.

    Export

    For exporting your animation, chose the « virtools exporter ».

    Inside the window, check :

  • Export object
  • Export as Character
  • Character Root Object
  • Character’s name
  • Export Animation
  • Animation in Linear

    • And uncheck all the other options.

    Import into Virtools

    Once you have opened Virtools Dev, just go to the « resources » menu and check for « import file » or « import file as / character », both choices will include a character.

    You should see your spider appearing in black in the middle of the 3D layout.

    Check inside the Level Manager that a « character » class object as in deed been added. Inside this class you should find the « spider » object and its « animation ».

    To check for the animation to be correctly implemented, you have two techniques : the « animation synchronizer », and the « Character Controller ».

    The animation synchronizer

    The animation synchronizer is a specific building bloc that gives you the ability to check an animation frame by frame, under different view angles.

    Get into the « characters/animation » building block category and chose the « animation synchronizer » that you simply drag and drop directly onto the spider.

    It should respond by lighting its bounding box in yellow, meaning the building block has set itself onto a the « character » object class you have chosen.

    A window will then open with a screen, a list and a time line.

    By choosing the « walk » animation inside the list, you set the animation synchronizer to animate your character with this specific animation. By choosing a view, you can look at the animation from different sides. By using the vertical slider, you can zoom in our out. And by sliding the time line, you finally check the animation.

    The Character Controller

    This building block is a high level behavior that will create a correspondence between a « message » and an animation for the chosen character.

    Inside the « characters/movement » chose the « character Controller » and drag and drop it onto the spider.

    A window will open for you to set the correct animation onto the parameters. Since we have only one animation, set « walk animation » to « spiderwalk », and don’t set the other parameters.

    We then need to set an interactivity to trigger the message. We will do this with the keyboard.

    Inside the « controllers/keyboard » chose the « keyboard Controller » and drag and drop it directly onto the spider.

    This time, no window appears, since this behavior is already set to respond to the numpad arrows.

    If you press the play button, you just need to press the « 8 » key to see your spider walking.

    Next exercise: Exporting a Skin Character from Lightwave Layout


Exporting from LightWave - Exercise 5

Tutorial 5 – Exporting an Animated Skin Character from Lightwave Layout

In this tutorial we will see how to export a character built with skin and bones. We are going to build the simplest kind, but of course, you can create more complex skeletons.

The example is called « JumpingBox.cmo » located in the Virtools Minisite. This example actually contains two animations, one for jumping and one for waiting.

Build your character’s shape

Inside Lightwave Modeler, build a simple box with some tessellation for it to react correctly to the deformations of the skeleton.

Set surfaces

Set a surface on your box. Our example presents a Virtools box and only has one map.

Give the surface a map

Assign map to the surface. This operation like preceeding one can also be done inside Lightwave’s Layout, but, if so, it won’t be understood as a transformed object.

Once the surface is set with a map, you can export your object to the layout.

Build the bones

The first step is building the bones for your character to move. Our example only requires 3 bones.

Inside Lightwave, bones are set in a basic position and orientation by default. You therefore need to define what position and orientation you need it to be at the start, this is called the « rest position » and « rest orientation ». To set those correctly, simply rotate and position your bone and then by opening its property box, change the « rest » values.

Copy the values indicated by the layout.

Our example only needs two « parent » bones that follow the first bone’s orientation.

Once your bones are all places and oriented correctly, don't forget to go back into the property box to set your bones to « active » by pressing the « active » tag button. If your bones have been correctly set, your object shouldn’t change shape or position.

Animate

The animation is create like any other. The « jumping box » example is based upon a compression movement where we change the height of the root bone and slightly bend the « head » bone, like if the box was gathering its force to jump. Compression to expansion (during the jump itself) to then compress again but less so than before.

Depending upon the tessellation level of the box (or your character), the deformation will appear more or less smooth. A low tessellation level can create very harsh deformation of rigid blocks (each block being a face).

Of course, don’t forget to copy the first key frame to the last key frame selecting « all elements » to be sure your animation will be cycling correctly.

The jump movement will of course include a displacement, but not only on the forward position, also on the height. Therefore, don’t forget to include a high position key frame.

NOTE : An important point of bone animation is not to change and animate the box object. This is because the position of the bones are computed in reference to the box, and you may find yourself with a floating or drifting box if you are not careful.

Export

Exportation must be done carefully, selecting the correct options since we need to export a character with its animation based on bones. We therefore need to select the following options :

  • export bones
  • export character
  • character names
  • export animation
  • linear key frames

  • and set the start and end frame numbers of your animation. Our example goes from 0 to frame 30.

    • Import into Virtools

    Inside Virtools you need to import your animation as a character by choosing « Resource » and choosing « import file » or « import file as/character » (which have the same result).

    Once imported, check that your animation is inside the « Level Manager » as « character » with its « animation ».

    To check the animation, you may use both methods, « Animation Synchronizer » or « Character Controller ». But for our « jumping box » example we will use the « Character Controller », to be able to use other animations afterwards.

    Inside « characters/movement », chose the BB « Character Controller » and drag and drop it onto the box.

    A window will open for you to set the correct animation on the parameters. Since we have only one animation, set the « walk animation » to « jumpAnim », and don’t set other parameters.

    We then need to set an interactivity to trigger the message. We will do this with the keyboard.

    Inside the « controllers/keyboard » chose the BB « keyboard Controller » and drag and drop it directly onto the box.

    This time, no window appears, since this behavior is already set to respond to the numpad arrows.

    If you press the play button, you just need to press the « 8 » key to see your box jumping.

    Adding an animation

    We will now see how to add an animation from Lightwave, without touching the actual animation or character.

    To perform this, we need to create a new animation. Of course it needs to be done from the same skeleton since the animation has to refer to the same bone structure. Therefore, the simplest way is to start from the end of the previous animation.

    Inside the layout load back the « jump » animation. We will add this time a « wait » animation, where the character moves slightly, instead of being completely frozen.

    Copy the last key frame at frame 60 (to add 30 frames), thus defining the limits of our new animation.

    But notice that putting our animation just next to the first one makes the character to keep moving even while we haven’t set any new key frame.

    This because Lightwave automatically interpolates the smoothing movements between each key frame. Therefore we need to set the move « curve» to change this effect and have our two animation completely disassociated.

    To manage this, go to the « spline controls » menu, and set the Y size of our root bone’s « continuity » to -1 so that tension computed between both key frames is set to nill.

    Once the tension is corrected, we just need to place a middle key frame with a slight move for the waiting to take life.

    Then we can export the animation as « animation only ».

    This time we need to export this single animation to a Virtools Resource folder for it to be included inside the former character’s animations.

    Set the right parameters for the animation. This time, add the « wait animation » in the « stand animation » parameter.

    If you press the play button, you just need to press the « 8 » key to see your box jumping and waiting around.

    Next exercise: Exporting Atlas UV Maps from Lightwave Baker


Exporting from LightWave - Exercise 6

Tutorial 6 : Exporting Atlas UV Maps from Lightwave Baker

Build an object inside Modeler

Inside the modeler, build an object on which you want to create particular pre-rendered textures. (Our example is a church.) Note that the full object will be considered by the process and therefore only one surface is set, for the UV coordinates.

Make Atlas UV’s

By choosing« make UV’s » inside the « map » section, you open a window in which you can name a new texture and set it to « Atlas ». These « atlas » UV coordinates are set in reference to the complete object side by side, depending upon its general shape, usually Front, Back, Left, Right and Up and Down.

Inside Layout set the surface

After having exported your object to the layout, you can set the surface. For the Atlas Coordinates to be taken, you need to use the « baker » plugin which you will find into the « shaders » section of your surface.

Double click on the shader, into the list or press « edit » to open it configuration window. The processed map will be given a default name that you can change if needed, but be sure to set your UV’s to the atlas UV texture name you set inside the modeler.

Render

Once your texture is set, you can render the frame (press F9) to render the object surface. This process is done just before the frame is rendered, and may take more or less time, depending upon the options you have chosen for your texture.

Change the surface

To get the result back onto your object, you need to change the parameters of your surface. Set to OFF, all the options, and remove the « baker » from the shaders list.

Once your surface is free, go into your color settings (T). inside this window change the render mode to « uv » and set the « uv type » to the name of your atlas UV maps. Change the « map » name of the baked map you have just rendered.

Now, your object will appear with a pre-rendered texture.

Export

You can now export your object, and all the elements you need with it.

Note : since your object as been pre-rendered, it is often the case that lights and shades are set upon the texture. We therefore advise you to export the light as well as to keep a coherent light inside Virtools.

Import into Virtools Dev

Once our object is imported inside virtools (resource Menu / Import file), it will appear inside the 3D layout window, black.

This is because its « material » settings are set to black. Get into the « material setup » by right clicking onto your object, or by double clicking inside the Level view /materials/the_name_of_you_material.

The material setup offers four color parameters to set your texture’s appearance. Change "Diffuse" to full white by clicking on it and picking the top left white color. The texture now appears.

Note : a pre-rendered textures needs a full light definition to appear correctly, since it has been pre-rendered, it doesn’t need any more light; however, it won’t react to any dynamic light either.


Readme.txt - Exporting from LightWave to Virtools

Comments


Exporting from Maya to Virtools

  • Virtools Exporter for Maya (readme)

  • Tutorial: Simple Animated Scene
  • Tutorial: Character Animation


Character Animation Tutorial

1.Overview
2.Modelling
3.Texturing
5.Skeleton and IKs
4.Keys
5.Export the character and its animations
6.Load the character in Virtools
7.Material & texture tuning
8.Merge animations & add behaviors
9.Conclusion

Note: When creating animations, you should be very careful what you do with the FloorRef. When walking or running, the character should stay at a constant height from the FloorRef object. When jumping, the Character should increase it's distance from the FloorRef object to give the appearance of translation away from the floor. Characters should ALSO have a "stationary root" that only moves relative to the floor reference (e.g. for walking, jumping etc.) but that does not move constantly (i.e. in an idle animation the root should not move). This is very important if you wish to use your Characters with the Virtools Mulituser Pack, or the dead reckoning algorithm used for predicting distributed objects will not work correctly. In short:

  • Make sure the (stationary) root element does not move at all when the character is in its default ('wait' or 'idle') animation.
  • For other animations make sure the root moves a minimum; in a walk animation along the Z axis for example, make sure that the root moves along the Z axis only - there should be no movement on the X or Y axes.

Note: Ensure the animations you create are 'real' in the sense that the Character actually performs them and does not 'pretend' to perform them - e.g. for a walk animation you should ensure that your character actually moves (translates) in your modeling application, and does not perform the animation in situ ("on the spot" or "in place").

Overview

This tutorial is designed to show you the exporting data process from Maya to Virtools for a character animation scene. It uses the Maya to Virtools plug in. Even though this is a basic multi animation scene, you are bound to have a working knowledge of Maya’s joint, IK and texturing tools, as it is not a ‘how to use Maya’ tutorial. Before exporting, it helps you in the understanding of this sample scene. You will see what kind of entities are animated and exported, then how different animations will be combined in Virtools on a single character.

Modelling

In the beginning, you must use a polygonal definition of your character.

This Character is generally one block designed as it is skinned to a skeleton. Although, you are able to skin other parts in the same time or parent others directly to a joint too.

"Man" is the principal mesh but "cloth" will also be skinned to the root joint. You see "hat" and "tool", two polygon models which will be simply parented to the joints.

Texturing

To dress the character, a planar mapping is just created in the front view, on the mesh "Man". Same thing for the others meshes. Notes that hands (parts of the "Man" model are mapped with a Y planar projection like the "hat", though the main body with "cloth" and "tool" uses a Z planar projection. But every objects in this scene uses a single texture image. Then Cut Texture operations and UV transformations achieve the UV management in the Texture view.

This texture compilation is a 256x256 image map where all UVs are precisely positioned.

In your Hypershade, you must notice that the image map is attached to the material by a Place2DTexture node. It’s the normal way to make a projection in order to write the mapping coordinates in the UV. If you experiment mapping projection for data real time exporting, don’t use Place3DTexture and Projection nodes as they don’t affect UV. Moreover be very careful not to change any values inside the Place2DTexture node. For the UV tweaking, only the UV manipulations achieved in the Texture View are really saved during the exporting process.

In this Hypershade view, you can see 2 materials, using the same texture file. The fisrt one "body_mat" is for the objects "Man", "hat" and "tool". The second one "double_mat" is only for the open object "cloth", and you will assign a Double Sided flag, later in Virtools, to this material. Indeed, this mesh must be viewed from inside and outside, so faces need to be set to double side.

Skeleton and IKs

To set up a character animation for real time animation, you must know that more the skeleton will be complex, and keys set, more the animation file will be eavy. Several methods can be used, depends of the character, but generally, make it as simple as possible.

The Virtools exporter allows you to conserve keys on Joints, Ikhandles, IkSplineHandles, locators. Examine this Maya scene to discover how the character is structured.

- First, the skeleton is build in this modelling and texturing pause.

- IKhandles are created ,"Man" and "cloth" are both skinned on the skeleton with the Smooth Skin method.

- Objects like "hat" and "tool" are parented to their specific joints.

- Locators and Constraints and created, so these handles could be constrained to the locators. Then you will set keys directly on locators.

- To control the spine’s joints an IKSpline Handle is used and keyframed.

Then, the Paint Skin Weights Tool menu is used to fine tune the skin assignments. In order to do this it can be interesting to put your character in a normal stand position, then try some natural moves to see the result of your assignments.

We put the Locators, the Ikspline curve, and the ‘tool’ under a group named "keyframed" parts

In the Hypergraph they are organized over the character image, these entities will be keyframed to animate the character. It’s easier now to select in this group the entity to animate.

Keys

The animator can have plenty of methods to animate. The plug in can export in two ways : in keys or in sampling.

In "keys", you can’t use any deformer or expression. Only key values on the plug in supported entities are considered and written in the exported animation file. Then Virtools will interpolate between these keys.
( Only keys on Joints, IKs, and Ikspline curves )

In "Sampling", everything is scanned ( joints, deformers, expressions…) and transformed to obtain the final mesh. So you can use any Maya functionality for your animation set up process. Controlled by the "step" sampling value, each key where a scan occurs, an entire mesh is generated. With no doubt, this method is a bit heavy but fully conservative. To minimise the weight file, try different sampling step values.

For the moment, the plug in only export keys in Linear format. That means if you set keys in Spline Tangeant mode, only key points will be kept without considering in between values given by tangeants ( in key export mode ). So It’s better to configure your Maya in the Linear tangeant mode or remember to convert with the Graph Editor all Splines Tangeants in Linears to see in maya the real effect of the future exported moves.

Linear Tangeant ( exactly exported ) Spline Tangeant ( exported like Linear )

In this Maya scene, you find 4 animation sequences:

  • "Stand" animation, frame 1 to 50
  • "Walk" animation, frame 80 to 109
  • "Action1" animation, frame 120 to 175
  • "Action2" animation, frame 200 to 250.

Entities under the "keyframed_parts" group have keys.

Through, in the sequences "action 1" and "action 2" other entities have keys like this one, "joint65" which control the wrist rotation.

In the "action 1" sequence the object "tool" is also animated.

As you are about to export, just have a look at the "Walk" animation.

This sequence from frame 80 to 109 is a complete cycle, that is to say frame 109 has exactly the same pause than the one in frame 80. For this reason you will only export from frame 80 to 108. Now a trick to ensure frame 109 exactly match frame 80. Keys on frame 80 have been copied then pasted on frame 109.

A snapshot of frame 80 in the side view has been taken and will be used to adjustment.

snapshot of the frame 80.

The snapshot is mapped on a plane which has the same dimensions of the picture. The plane is first scaled and positioned in the background side view to match exactly frame 80. Then the plane is translated on Z in frame 109 to allows you the exact tuning of this frame 109.

Export the character and its animations

- First you will export the character itself with its primary animation attached.

Select File/Export All/[] to open the option box.

Put parameters like in this window. Export as Character, frame [start 1 end 50 step 2].

As it is a stand animation a step of 2 is enough, in this case no more precision is really needed.

You export as Frame Sampling. click Export All and name the file "man_stand_sampl". The export plug in will scan the scene and create the .nmo file.

-Then you must export the secondary animations.

Select File/Export All/[] to open the option box.

This time select Export Animation only and frame [start 80 end 109 step 1], as you want only exporting the animation without the character mesh. click Export All and name the file "man_walk_sampl". The export plug in will scan the scene and create the .nmo file. Put this file in your Virtools database in Characters/animations.

- Do the same for the two other secondary animations, name them "action1" [start 120, end 175, step 1] and "action2" [start 200, end 250, step 1]. Put these two files in your Virtools database in Characters/animations.

It’s time to go in Virtools, load the files and merge then.

Load the character in Virtools

Each animation files are given in this tutorial in the "Virtools_scenes&files" directory. You should have at this time the following files in your Virtools database :

in Characters : "man_stand_sampl.nmo"

in Characters/animations : "man_walk_sampl.nmo", "man_action1_sampl.nmo", "man_action2_sampl.nmo".

Otherwise put the files given by the tutorial at the correct places and follow the next steps.

- Run Virtools, and click Ressources/Import File As / Character.

- Load "man_stand_sampl.nmo", the character appears in the Level View under the directory Default Level / Global / Characters.
- In the 3DLayout top bar, open the camera menu and select the "persp" camera to view your character correctly.

You have loaded the character itself with its primary animation attached.

Before to merge other animations you will adjust and verify materials et textures.

Material & texture tuning

- Materials:

In Default Level / Global / Materials you should find "body_mat" and "double_mat".

In their Material setup sections, set their Ambient and;Diffuse to <255,255,255>.

Set the Double Sided flag to [off] for "body_mat", this flag keeps [on] for "double_mat".

- Textures.

Remember to select a correct value from the Video Memory Format, from <1555> to <888>.

You should see this in the 3D Layout;now :

Merge animations & add Behavior Building Blocks

You are about to merge the secondary animations.

Open your Virtools database where you have saved the Maya animations.

Under character / animations you must find your 3 .nmo files.

Drag & drop these files in the 3DLayout over the character. They will be auto attached to it and you would also see them appear in the Level View under Default Level / Global / Characters / Animations with the first one "man_stand_sampl.nmo".

To see the character playing its different animations you must add some Building Blocks.

From Controllers / Keyboard drag & drop the Keyboard Controller BB over the Character.

From Characters / Movement drag & drop the Enhanced Character Controller BB over the Character.

A parameters window opens where you can link the animations to the character actions like this :

Before you see the result, just click ( right mouse button ) on the Play icon to open the Times Settings and set the Frame Rate to Limit at 60 Fps

Your character can walk, reacts when [suppr] and [Page UP] keys are pressed, and has a stand animation when nothing appends.

Save your Virtools composition and name it "Cowboy.cmo".

This final file is also given with the tutorial under "Virtools_scenes&files".

Conclusion

You can now merge this scene with "mountains.nmo" from the scene tutorial.

Before to do this, delete the spotlight and the camera of your cowboy scene as "mountains.nmo" still have ones.

Then open the man_stand_sampl setup in the Level View under Default Level / Global / Characters and change its position to <0, 1.3, -20>so the character will be directly in the right place. Try BBs to set up collision detection, have fun !


Simple Scene Tutorial

Exporting a Simple Animated Scene from Maya to Virtools

1.Introduction
2.The Scene in Maya
3.Exporting Datas
4.Loading the Scene in Virtools
5.Adjustements and Behaviors
6.Conclusion

Introduction

This tutorial explains how to export a Maya scene including animated objects with simple keyframes. It uses the Virtools plug-in directly loaded in Maya.

The Scene in Maya

Load the "mountains.ma" scene in the tutorial's "scenes" file into Maya. To do so, place "mountains.ma" directly in your Maya "/scenes" directory. Then place the 4 textures in "/sourceimages". Here is what you should see:

Activate Display/Polygon Counts to see the number of faces in the scene, i.e., 474 (quads or triangles).

Note a certain number of specific characteristics before exporting this scene.

- the vertex lighting & the triangulation.

In the Custom Polygon Display Options, set Color to Color in Shaded Display and the Color Material Channel to Ambient+Diffuse. Then click Apply. You will see in smooth shaded or smooth shaded & textured mode that the main scene is in vertex lighting. These values will be exported in Virtools.

You will also see that this mesh has been manually triangulated in some places (using the Split Polygon) in a specific direction, so that the topology of certain edges will be properly respected when the scene is transferred.

- Objects and their materials.

The "water" object is made of a transparent material.
The "ground_bridge" and "box_static" objects use the same "Boards.jpg" texture, but they do not use the same material. In this case 2 different materials are used because one will be placed in Both Sided in Virtools, and the other will not. We will want to see the top and bottom of the faces of the "ground_bridge" object; thus Both Sided will be activated in the setup of this material. The "box_static" object, however, will be single sided. In this Maya scene materials are not systematically separated into types because there are few faces, but this separation is given as an example of how to optimize more complex scenes.

- Collision objects.

2 objects are modeled so that they can be used as collision objects if you wish to add specific Virtools behaviors. For example, "collision_object" can be used to test collisions on the bridge, without testing all the faces that make up the bridge. Note the orientation of the normals on this object: pointed towards the inside of the bridge, Note the direction of the normals on this object; they are used by collision detecting Building Blocks so the normals need to be oriented correctly. "Collision_object2" can be used to limit the movement of a character and prevent him from falling in the water. These objects will be placed in the invisible category in Virtools; they are also made of a very specific material (shown here in transparent red in Maya).

- Lighting.

2 spotlights are used to light small objects in the scene, since the "Landscape" object is self-illuminated with vertex lighting.

- Animated objects.

"box_static3&4" are the animated objects. Although the animation uses spline curves, it will be saved only in break mode. Four keyframes are set between images 1 and 100. The overall length of the animation can be changed later in Virtools to adjust the speed of movement. The most important thing in this example is to have 4 independently set keyframes.

Exporting Data

To export your Maya scene with its animation and textures, select File/Export/All/.
Select the parameters shown in the window below, in particular Enable Animation starting at frame 1 and ending at frame 100 and the Keys keyframe method to export animation of the 2 boxes at the same time.

Then click Export All and call the file "mountains". The exporter will create a ".nmo" file. You are now ready to go into Virtools and load your converted scene.

Loading the Scene in Virtools

The result of this export should be exactly the same as the "mountains.nmo" file provided with this tutorial in the "Virtools_scenes&files" file.
Start up Virtools, select Resources/Import File and find your "mountains.nmo" file. You are now ready to adjust certain parameters and add a few behaviors to reconstitute the ambiance of the scene.

Adjustments and Behaviors

In the camera selection menu of the 3DLayout top bar, select the "persp" camera to obtain an overall view of the scene.

- Materials.
Two-sided materials: Remove the Both Sided flag for all materials except "wood" and "Board_DB_mat", which should remain dual sided.

- Textures
One more adjustment should be made on these textures. Set the Video Memory Format to <0555> for all textures except for the texture on water ("file3"), for which the Video Memory Format should be set to <8888> in order to obtain a good level of transparency.
You should now obtain the following in the 3D Layout :

- Collision objects.
Now go into Level View/Globals/3D Objects and remove the "Visible" flag from "Collision_object" and "Collision_object2".

These collision objects can be used to test collision behaviors not described in this tutorial. They should not be visible in the final scene.

- Animated objects.
The "box_static3" and "box_static4" objects were animated in Maya. To play their animation, simply go into the Building Blocks/ 3D Transformations/ Animation window, and drag&drop Play Global Animation onto the "box_static3" object in the 3D Layout or the Level View.
The Edit Play Global Animation's Parameters window will open. Select the "mountains" animation and then enter the following Duration parameters: Min 0, S 20, Ms 0.
Placing a Play Global Animation building block on "box_static3" will also trigger an animation Play on "box_static4" because the animation was integrated when the ".nmo" file was exported. Before clicking on Play to see the animation, use the right button on the mouse to click the Play icon and open the Times Settings. Set the Frame Rate Limit to 60 Fps.

- Behaviors on inanimate objects.
To bring this scene to life, a Texture Sine building block is added to the mesh of the "water" object, with X amplitude=0.1, Y amplitude=0.1, Velocity=0.1 and Channel=-1.
In the Default Level the Set Background Color is also set to <255,255,255,255>.

- Camera.
Try the following adjustments for the "persp" camera:

A Widescreen camera with a 35 mm perspective for a cinematic effect, and the Position, Orientation and Target Position parameters given above to see the boxes moving with the water when Play is activated.

- Sound.
Finally, a sound file is provided with this tutorial: "wind18bit.wav". It must first be placed in the Sounds file of your "Database Virtools" so than you can use a drag&drop to load it in the Level View. Once the file is in Level View, place the Wave Player building block on top, with the following parameters: Fade In=0, Fade Out=0, Loop ON. Then open Wave Sound Setup and set the Loop flags to ON and the Type to Background.

Conclusion

You have just finished exporting and integrating a complete Maya scene, including simple animation and Virtools behaviors. Now you can test other behaviors on this set for collisions (with the collision objects hidden in the scene), by importing characters... This entire scene is modeled under Maya with the unit used in the Virtools world (1 unit = 1 meter). The Textures respect the Virtools format (size in powers of 2) required by graphics adapters. The final file of this Virtools composition, "mountains.cmo" is provided with this tutorial in the "Virtools_scenes&files" file.


Maya to Virtools Exporter

Virtools Exporter for Maya

  1. Installing and using the exporter
  2. Geometry
  3. Lights
  4. Cameras
  5. Materials and Textures
  6. Character and Object Animations

Introduction

This document describes how to use the Virtools Exporter for Maya. It is split up into the following sections:

  • Section 1. deals with installing and starting exportation.
  • Sections 2. to 6. tell you exactly what aspects are exported from Maya to the Virtools format, and also of any export limitations or things you should do to ensure your export goes correctly.

You should be aware of how an exporter actually works: it takes information from a source format, in this case the Maya format and converts it to a destination format, in this case the Virtools nmo format. When converting this information, one of three things will happen:

  • There is a direct equivalent in Virtools, so the result will be the same as what you have in Maya
  • There is no direct equivalent, so the element is translated into the nearest Virtools equivalent
  • The feature is not recognized by the exporter, so it will not be translated at all.

Installing and Using the Exporter

Install the plugin as instructed in the readme.txt which came with this document. If you are not sure how to do install a plugin, refer to the Maya Documentation for more information.

Starting the Exporter

  1. To export a scene or character from Maya to the Virtools format, choose File, Export All.
    If you want to export only certain elements, select them in your scene before choosing use Export All and make sure you choose the Selected radio button for Export in the Export Options dialog box.
  2. If you wish to select the export options, click Options.
    Export options are explained below.
  3. Select a location to save your file and name it.
  4. Click Export

Choosing Export Options

Export options are split into two parts:
  • General
  • Animation

General
  • Type Normal or Character
  • If you are exporting a character or character animation, choose character, otherwise choose normal.
  • Export Animation Only
  • Select this check box if you want to export animations only, without any models.
  • Hierarchy Full or Flat
  • If you choose Full (Default), then any parent-child hierarchies in your scene will be exported. Flat means that no hierarchy information is exported.
  • Export All or Selected All means export all elements in the scene; Selected means only the elements which are currently selected in the scene. The default is All.
  • Exported Objects Types of entity to be exported: meshes, lights, normals, textures, cameras, groups.
  • Textures
  • If the check box is selected (default), then the textures will be saved inside the nmo file.

Animation

  • Enable Animation
  • If this check box is selected (default), then any animation will be exported as well.
  • Start / End
  • Start and End key frames of the animation.
  • Sampling Step
  • How frequently the animation should be sampled. 1 means every frame, 2 means that every other frame will be used, 3 means one in 3 frames and so on. The higher the sampling, the lower the file size but at a decrease in animation quality.
  • Keyframe using Keys or Frame Sampling
  • The mode used for producing the animation.
  • Animate
  • The entities whose animation you want to export: meshes, lights, vertices, cameras.

Geometry

- Polygons:
Polygons become 3D Objects in Virtools. Animation is restricted to:
  • Keyframe animation.
  • Object/Vertex animation using deformers or expressions.
  • For this type of animation, you must select the Frame Sampling check box in Animation Options (see section 1).
- Splines:
  • Splines used for paths (Curves in Virtools) are not exported.
  • However, you can easily create paths in Virtools using Create Curve in the 3D Layout.

- Nurbs and Subdivision Surface:
Nurbs and Subdivision Surface are not supported by the exporter.

  • 1. You must convert your model to polygon using the conversion tools in Maya.
  • 2. You must then ensure that your meshes are properly triangulated.

- Structure:
The following structural information is exported:
  • Sets and Partitions
  • These are groups of faces when an object uses several materials (see also section 5 Materials).
  • Normals
  • Smooth and Break (0 to 180°)
  • Object UV co-ordinates
  • (see also Materials section)
  • Vertex color and Alpha
  • Scene Hierarchy (groups supported)
  • Root or parent-child relationships are exported.

Lights

Type of Maya Light | Exported? | Translated to
Spot | Yes |
Directional | Yes |
Point | Yes |
Ambient |  | Point
Area | No |
Parallel | No |

Exported parameters depend on the light type:

 | Spot | Directional | Point
On/off flag | Yes | Yes | Yes
Color | Yes | Yes | Yes
Constant attenuation | Yes |  | Yes
Specular | Yes | Yes | Yes
Range | Yes |  | Yes
Hot spot | Yes |  |
Fall off | Yes |  |
Fall off shape | Yes |  |

Cameras

One, two and three node cameras are all converted to Targeting Cameras (equivalent to a 2 node camera in Maya) in Virtools.
You should not use 3 node (Twist) cameras in Maya as the Twist information is not translated.
  • Orthographic Cameras are not exported.
  • Camera animations can also be exported.
  • A camera's position, target (if applicable) and 'attributes' are exported (see screenshot):

      FOV

      Near and Far clip plane.

Materials and Textures

- Ways of applying a material:
Materials can be applied to geometry as set out in section 1.
  • An object can have Material sets or partitions (multi-mat). This is exported.
  • In Maya objects may have multi UV co-ordinates. This is not exported.

- Shading Modes:
Virtools has two shading modes Flat and Gouraud (also known as Lambert).
  • Lambert becomes Gouraud in Virtools.
  • Phong, Lambert, Blinn, Anisotropic, PhongE are translated to Gouraud in Virtools.

To be sure of getting the closest result in Virtools to what you see in Maya, you are advised to use Lambert. After Lambert, Blinn, Phong and PhongE are recommended in no particular order.

- Other Material and Mapping Parameters:
The exporter can only export parameters linked to UV co-ordinates.

You should be aware that in Maya a number of parameters are stored in mapping nodes, the results of which can only be seen in Maya. The following two illustrations should help you.

An example of Mapping using PLACE2DTEXTURE NODE: This is the correct way to map, ensuring that you export UV co-ordinates correctly.

As soon as you want to map in Maya, a mapping node «Place2dTexture» is automatically associated to the exp_image and material in a hierarchy.

This node allows you to define tiling (mirror, stagger, wrap U and V) as well as the offset, scale, and rotate.

It is not possible to get the parameters of this node as it is used for rendering only.

The UV position parameters got by the exporter will be those that can be changed in the window Texture View, which can be used in place of the those in Place2dTexture node window. Therefore, you should adjust your mapping in Texture View.

An example of mapping using PLACE3DTEXTURE NODE + PROJECTION NODE:

As well as a Place2dTexture node, you can see here a Place3dTexture node and a Projection node which are used to place the map interactively and to choose between several projection types such as triplanar, cubic etc…

This means unfortunately that the effect of these nodes is not stored in the object's UV co-ordinates meaning such information will not be exported. Therefore, you should not use this method.

- Shading Parameters:
These are found in Common Material Attributes.

  • Color is exported if no exp_image has been mapped to this channel; if this is the case then color will be black in Maya but white in Virtools.
  • (Alpha) Transparency is exported.
  • Ambient Color is exported as Ambient Color in Virtools.
  • Incandescence becomes Emissive in Virtools.
  • Bump Mapping is not exported.
  • Diffuse is taken with the parameter for Color in Maya and is translated to become Diffuse in Virtools.
  • In Maya, Color x Diffuse = Diffuse in Virtools.
  • e.g. if Diffuse in Maya is 0.8, the Diffuse in Virtools will be 80% of the RGB Color values in Maya.
  • Translucence is not exported.
- Double-Sided:
The flag Double-Sided, found in Render Stats for an object, is also exported. That means if you keep this flag to ON in Maya, the material will be set to ON in Virtools, so the objects faces will be doubled.

- UV Mapping Type:
  • Planar, Cylindrical, Spherical, and Automatic mapping are supported. However, you must ensure you use the technique Place2Texture Node explained above.
  • Scale, rotation and translation parameters for UV are exported.
  • NB These are only exported is they are done using the Texture View.
  • Cut and Sew is supported.
  • Texture cropping refer to Place2Texture Node explained above.

Character and Object Animation

Note: When creating animations, you should be very careful what you do with the FloorRef. When walking or running, the character should stay at a constant height from the FloorRef object. When jumping, the Character should increase it's distance from the FloorRef object to give the appearance of translation away from the floor. Characters should ALSO have a "stationary root" that only moves relative to the floor reference (e.g. for walking, jumping etc.) but that does not move constantly (i.e. in an idle animation the root should not move). This is very important if you wish to use your Characters with the Virtools Mulituser Pack, or the dead reckoning algorithm used for predicting distributed objects will not work correctly. In short:
  • Make sure the (stationary) root element does not move at all when the character is in its default ('wait' or 'idle') animation.
  • For other animations make sure the root moves a minimum; in a walk animation along the Z axis for example, make sure that the root moves along the Z axis only - there should be no movement on the X or Y axes.

Note: Ensure the animations you create are 'real' in the sense that the Character actually performs them and does not 'pretend' to perform them - e.g. for a walk animation you should ensure that your character actually moves (translates) in your modeling application, and does not perform the animation in situ ("on the spot" or "in place").

For all animation, object or character, you have a choice between two possible modes:

  • Keyframe
  • Sampling

- Keyframe:
  • You should only use Break keys
  • Spline and Linear keys are not currently recognized by the exporter.
  • You can place keys on meshes, vertices and joints.
  • You must not use expressions or deformers with this type of animation.
  • You can use the Paint Skin Weight Tool as these values are recognized by the exporter.

- Sampling:
This mode will record the position of the character every n frames, where n is the value you choose in the Animation Options section of the Export Options dialog box.
In addition to what is already noted for Keyframe above, the following applies to animations exported using Sampling:
  • Cluster Deformers are supported.
  • IK (including IKSplines using CV or EP curves) are supported.
  • Locators are supported. If you need locators you must use th Sampling Export Mode.

- Note on Characters and Character Animations:
Normally you will first export a character with its mesh and one animation, then you will export subsequent animations (primary or secondary) one by one on their own, without the character. In Virtools, you will then assign all or some of a character's animations to the character (refer to the Online Reference for more details).

- Tips for character collisions:
Add a little object parented to the root's skeleton hierarchy and when you animate your character, always keep this object's Y position to 0. This object's visibilty flag must be set to Off in Virtools, because this object is only used for floors collision detection.


Interface

Overview

This section introduces and explains to you all elements of the Virtools Interface.

This section is divided in several parts corresponding to the Menu Bar, 3D Layout, Building Blocks Resources, Data Resources, Level Manager, Schematic and Entity Setups, Status Bar.

Menu Bar 3D Layout Building Blocks Resource Data Resources Entity Setups Level Manager Schematic Status Bar
Displays the content of your project in real-time 3D
Provides access to Virtools behavior building blocks (BBs)
Contains the media (models, textures, counds ...)you will use in your project
Displays the scripts of your composition. Scripts visually describe behaviors.
Provides a list of all the elements that are part of your current composition.
Allows you to view and edit the parameters and attributes of the elements in your composition.


Building Blocks Resource

Overview

The Building Blocks Resource is a library containing Behavior Building Blocks (BBs). You can browse BBs by category using the tree in the left pane of the window. To find learn more on a certain BB, double-click the BB to open its online documentation. The BB window contains the following columns:

Category
Lists BB categories and sub-categories. You should always see the default BB categories; other categories should be present if you have purchased additional packs or coded custom BBs.

Behavior Name
Name of the BB.

Apply to
States the type of entity (the CKClass) to which you can apply the BB.

T
Displays a T if the BB is Targetable.

Description
Gives a short description of the function the BB performs.

Adding Behaviors to Elements

You attach BBs to elements by dragging a BB onto an element in the 3D Layout or in the Level Manager. You can select several BBs at a time using SHIFT or CTRL +click. Dragging a BB onto an entity in the 3D Layout or in Level Manager adds the BB to the first script attached to this element, or creates a script if the element currently does not have any scripts, and opens the Edit Parameter dialog box for that BB if the BB has pIns you can edit. You can also drag BBs directly into existing scripts in the Schematic.


Data Resources

Overview

A data resource is a storage area for all the media you may need for a composition. A data resource is simply a root folder identified to Dev as containing sub-folders of containing specific types of data.

To add elements to a composition, select one or several elements and then drag the elements into the 3D Layout or Level Manager.

Creating a Data Resource:

The process for creating a new database is very simple: from the Resources menu, choose Create New Data Resource.

You will then be prompted to choose a location to save your Virtools database (.rsc) - this can be where you like, even on a server so that it is accessible to several people at once. An ordinary Windows folder is created to store your files (.nms for Behaviors, .nmo, .jpg, .wav etc. for Data) and a Virtools .rsc file is created of the same name to reference them. Once you have created your database, it will automatically open up in the default part of the Virtools screen.

Adding Media to a Data Resource:

Once created, it will have by default the following eight default folders - 2D Sprites, 3D Entities (concerning another sub-folder Animations), 3D Sprites, Behaviors, Characters (containing another sub-folder Animations), Sounds and Textures. These folders can be renamed and deleted. Note that To fill them with resources, locate the folder in Windows and copy your files (.jpg, .avi etc.) into the appropriate sub-folder.

Right-clicking a Behavior Graph (BG) allows you to edit the description.

Closing a Data Resource:

To close a database, right click its tab and choose Close or select it by clicking on its tab and press the DELETE key.


Customizing the Virtools Interface

Moving Windows

  • To move windows to different locations, either on the same tab strip or to another one, click the window's tab to select it and then drag it to the new desired position.

Re-Sizing Windows

  • To re-size a window, move the mouse pointer to a tab strip and it will change to a double headed arrow. Click and then move the mouse to size to the size you want.

  • To maximize a window, double-click the tab; to restore the window to its original size, double-click the tab once more.

Closing Windows

  • To close any non default window, either select its tab and then press DELETE, or right-click the tab and choose Close in the menu that appears, or click the [image] that appears at the top right corner of the window.
Note: Virtools' default editors (3D Layout, Level Manager, Schematic) and Building Blocks may not be closed.

Floating Windows

  • To turn any window, including all default windows, into a floating window, right-click the window and select Move to separated window. Then you can reposition and Resize it as you want. This feature is especially useful when working on a workstation with more than one monitor.

Disappearing Windows?

  • If you typically have more than four or more windows in the top right part of the screen, or eight or more windows in the bottom half of the screen, it may look as though a window has 'disappeared'. Simple look for the backwards [image] and forwards [image] icons at the right edge of the tab strip.

Saving Window Positions

  • The position and size of non-default windows are saved with the composition file (.CMO). Note that after loading a composition, the following editors are however returned to their default positions and sizes: 3D Layout, Building Blocks, Resources (if any), Schematic and Level Manager.


Menu Bar

File Menu Resources Menu Editors Menu Options Menu Help Menu

Overview

To access a command from a Virtools menu, you have three choices:

  • Use the mouse to select visually the command.

  • Use the keyboard shortcut, if there is one (e.g. CTRL+L to Load Composition).

  • Use ALT followed by the letter underlined for the menu name or command (e.g. ALT, F, L to Load Composition).

    • The name of selected level/scene is showed in the title bar, the path of the loaded composition is also displayed.


File Menu

Menu Bar - File Menu

Resources Menu Editors Menu Options Menu Help Menu

New Composition
allows you to create a new composition. You will be prompted to save your work as a .cmo file if you have not already done so.

Load Composition... (CTRL+L)
opens a dialog box allowing you to select a composition (.cmo) to work on. You will be prompted to save your work if you have not already done so.

Save Composition (CTRL+S)
saves the composition under the current file name (.cmo). If this is the first time you are saving this file, the Save As... dialog box will appear instead.

Save As...
opens a dialog box allowing you choose where to save your file to and under which name (.cmo).

Save Version (CTRL+Shift+S)
saves the composition under an automatically incremented version of the current file name (.cmo). If this is the first time you are saving this file, the Save As... dialog box will appear instead.

Revert to Saved (CTRL+Shift+Z)
Loads the composition with a decremented version of the current file name (.cmo) if it exists.

Undo (3d Layout/Schematic only) (CTRL+Z)
undo last action done in schematic / 3d Layout

Redo (3d Layout/Schematic only) (CTRL+Y)
redo last undone action in schematic / 3d Layout

Purge Undo
clears the undo history. (Note the number of Undo Steps are defined in the Variable Manager)

Merge Composition...
Merges the current composition with the loaded composition, the current level will receive all objects and scripts from the level loaded from the cmo. If the loaded level contains scenes, they will be loaded too.

Merge Composition as New Scene...
 Merges the current composition with the loaded composition, a scene will be created, it will receive all objects and scripts from the level loaded from the cmo. The current level will also receive all loaded objects. If the loaded level contains scenes, they will be loaded too.

Export to Virtools Player
saves the composition readable by Virtools Players only (.vmo), this means the file cannot be edited in Virtools afterwards. See also Exporting from Virtools.

Create Web Page...
opens a dialog box allowing you to create a web page for the current composition. A html file and a vmo file will then be created. See Virtools Web Player for more details.

Print Schematic...
opens a dialog box allowing you to print scripts from Schematic.
1) to 8)
shortcuts to load the last eight compositions opened or saved.

Exit (ALT+F4)
 closes Virtools, prompting you to save your composition (.cmo) if you have not already done so or if the file has changed since last saving it.


Undo

Overview

Undo in Virtools lets you undo actions in the Schematic View and the 3D Layout.

  • Undo an action with Ctrl+Z or in File Menu with Undo command
  • Redo an action with Ctrl+Y or in File Menu with Redo command
  • Purge Undo history in File Menu with Purge Undo command. (Note: the number of Undo steps is defined in the Variable Manager)

3D Layout

Undo is available for 3D Entity & 2D Entity translation, rotation and scaling, as well as camera movements. Creation and Deletion of objects are not undoable.

Schematic

All actions in Schematic View can be undone and redone, except for cut and paste. External operations that modify the Schematic View state cannot be undone, see chapter Other.

Other

Actions that modify the state of the Schematic View or 3D Layout from another editor are not undoable, such as:

  • Creating scripts from Level Manager.
  • Creating scripts from 3D Layout .
  • Modifying an array in the Array Setup, when some Buildings Blocks using arrays as target are in the schematic.
  • Modify Run VSLBuilding Blocks from VSL Script Manager, by adding or removing some IOs or parameters.


Resources Menu

Menu Bar - Resources Menu

File Menu Editors Menu Options Menu Help Menu

Further information on Data Resources

Open Data Resource:
opens a dialog box allowing you to select an existing data resource to open.
Note: you can now open a resource located in a NXN alienbrain database.
This will give the option to Get Latest Version or Check Out the resources from the Alienbrain database.
A special icon will appear in the data resource window tab, indicating that it is under alienbrain version control.

Create New Data Resource:
opens a dialog box allowing you to choose where to create a data resource and under which name.

Import File:
opens a dialog box allowing you to import files directly into a composition without having to pass via a data resource.

Import File as -> Character/Place/Scene:
opens a dialog box allowing you to import a file as a character, place or scene.


Help Menu

Menu Bar - Help Menu

File Menu Resources Menu Editors Menu Options Menu

Online Reference
opens Virtools's Online Reference.
About Virtools...
displays summary copyright information, and states the version and build of Virtools you are using. Click Credits to see the names of all the wonderful people who bring Virtools Dev!


Editors Menu

Menu Bar - Editors Menu

File Menu Resources Menu Options Menu Help Menu

Attributes Manager
opens the Attributes Manager.

Hierarchy Manager
opens the Hierarchy Manager.

Path Manager
opens the Path Manager.

Variable Manager
opens the Variable Manager.

VSL Script Mamager
opens the VSL Script Manager

Parameter Debugger
opens the Parameter Debugger.

Close All Setups and Managers
closes all windows except the default windows: 3D Layout, Building Blocks, Level Manager, Schematic and any Data Resources.


Action Manager

Overview

In Virtools Dev, an Action is a specific type of VSL script (called a VSL Action script) that is created in the VSL Script Manager and used only in Dev's Authoring environment. Once scripted in VSL, an Action is opened and launched from the Action Manager or a user-defined keyboard shortcut to perform a predefined task on a selection or parameter.

Essentially, the Action Manager allows VSL scripters to create and share their own dedicated tools programmed in VSL and access them in just a few keystrokes - a huge productivity boost. For example, make iterative modifications of media in just a few keystrokes: change the locations, reset positions, align objects, etc.

Using the Action Manager

Important: VSL Action scripts are created, deleted, and coded within the VSL Script Manager.

Choose Action Manager from the Editors menu to open the Action Manager Window.

The Action Manager manages the user's access to these actions. Actions can be organized, executed easily from the Action Manager interface, and/or assigned to a keyboard shortcut. Actions can also loop with a user-specified delay between each iteration.

When an Action is created in the VSL Script Manager, a corresponding .VSL file is created in the "Actions" folder of your Virtools Dev directory. In this folder, you will find also find two files, ActionEditorInterface.ini and ActionEditorList.ini, which save the current Action Manager interface. The VSL Action script contained in the .VSL file can then be opened, organized, executed, and assigned to a user-definable keyboard shortcut, all in the Action Manager interface.

Note : A VSL Action can also be shared simply by copying the VSL file in another Dev user's /Action subdirectory and importing it into the Action Manager. If you want to share all your actions with another Virtools Dev user, you must copy all *.vsl files from the "Actions" folder to the same folder in the destination Virtools Dev directory. You must also copy all *.ini files to provide the same interface for the Action Manager.

The Toolbar

  • The Tabs

    The 1st time Virtools Dev is launched, all actions from your Actions folder are added to the action manager: for each folder in the Actions folder a tab is created and all actions contained in that folder are listed. If there are no actions, a default tab is created, named Default Actions.
    Each tab contains a list of actions and serves to organize your actions. Use the contextual menu to create/remove/move/rename tabs. Tabs can be dragged and dropped to change their positions. At least one tab must be present.
  • Refresh Scripts Descriptions button
    Click this button to update all action's descriptions in the Description column. (Descriptions are specified in the VSL Action script.)
  • Execute Action button
    Click on this button to make a pop-up menu appear with all available actions listed. Clicking on an action in the menu executes that action on the selected items or parameters.
  • Action Timer
    For actions that you want executed in a loop (see below), this delay will be used between each loop and is specified in milliseconds. This timer can be found in the Variable Manager View in the Actions category too.
  • Import all Actions
    Retrieves all actions from your Actions folder and put them in the action manager: for each folder in the Actions folder a tab is created and filled with all actions contained in that folder.

Action Lists

Each tab provides for the organization of a separate list of actions. By default, there is only one tab with an empty list. The user may then add or remove tabs, and add or remove actions in the tab's list to organize actions in the most efficient manner. Use the contextual menu to create/remove/move/edit actions. You may drag & drop tabs in the toolbar to change their position too. Here is the descriptions of columns:

  • Activate
    Click on the button to activate the related action.
    - If the action needs input parameters, a dialog will popup so that the user enters the required values. If the action loops, the action will start only after you press the Ok button if there are parameters to edit, and you may edit the parameters of looping actions with a modeless dialog later, using the "Edit Looping Action Parameter" command from contextual menu (see below).
    - For looping actions, this button will turn into a [image] button after activation.
  • Loop
    Shows the loop flag of the related action. Click in this column to check or uncheck the loop flag on an action. An action with an X will loop when executed with the delay specified in the Action Timer edit control (listed above).
  • Name
    Shows the name of the action.
    - If the corresponding Action is not found in Dev's /actions subdirectory at Dev's startup, "(Not Found)" will appear after the action name. These may be removed using the "Remove Actions Not Found" command from the Contextual Menu.
    - Double click on name to select another action (a popup menu with all available actions will appear). Note that you cannot have the same action twice in the list of the same tab.
  • Description
    Shows the description of the action. Note: to add a description to a VSL action, add the line in its VSL code (in the VSL Script Manager):
    // description : xxxxx xxxx is the description of your action. Note: the keyword description is case insensitive, and that you may put as many spaces as you want around it.
  • Edit
    Click on the button to edit the VSL action in the VSL Script Manager.
  • Keyboard Shortcut
    Shows the keyboard shortcut for the related action. Double click on the Keyboard Shortcut field of an action to edit it.

Action List Contextual Menu

  • Add Action
    Select an action from available actions in submenu to add it to the current tab's action list. The same action cannot be added twice in the same list of a tab but can be listed in several tabs.
  • Remove Action(s)
    Removes the selected action(s) in list of the current tab.

    Important: the same action can be shared by several tabs. If a keyboard shortcut is set for this action, this keyboard shortcut will work until this action is removed from all tabs. If you wish to remove the action from all tabs, just delete it in the VSL Script Manager.

  • Remove Action(s) Not Found
    When launching Dev, the Action Manager tries to map action names to VSL Actions in Dev's /actions subdirectory. If a VSL Action no longer exists (e.g. its file has been removed from the Action folder in Virtools Dev folder), then this action is "not found". Use this command to clear the lost action(s) from all tab action lists.
  • Move Action(s) Up
     Moves selected actions up the list.
  • Move Action(s) Down.
    Move selected actions down the list.
  • Move Action(s) to Top
     Move selected actions to the top of the list.
  • Move Action(s) to Bottom
     Move selected actions to the bottom of the list.
  • Sort Actions by name
     Sort actions in list by their names.
  • Invert Order
     Invert the order of actions in the list.
  • Edit VSL Action Code
     Opens the VSL Manager if not already opened, then shows the code of the VSL Action, ready to be edited.
  • Replace Action
     Opens a popup menu to choose another action and replace the previous one.
  • Edit Keyboard Shortcut
     Opens the Edit Keyboard Shortcuts dialog (listed below) with the focus on the current action's keyboard shortcut.
  • Edit Looping Action Parameters
    Available only for active looping actions. Opens a dialog to edit parameters of action if any.

Editing Keyboard Shortcuts for Actions

First double click on the Keyboard Shortcut field of an action.

A new dialog with all assigned keyboard shortcuts will appear, with the currently edited script selected by default. Currently, only function keys (F1->F10 + an obligatory modifier) may be used as keyboard shortcuts for actions.

In the name field will appear actions names.

In the Keyboard Shortcut field will appear actions keyboard shortcuts. If there are none, then "na" will be shown.

Press the Delete key or use contextual menu to remove a keyboard shortcut (but not the action).

Double click on this field, or press Space key, or use the contextual menu to specify a new keyboard shortcut.

Keyboard Shortcut Contextual Menu

When you see a "?", you can assign a key combination using Control (And/Or) Alt (And/Or) Shift plus a Function Key.

The new keyboard shortcut will be taken into account as soon as the dialog is closed with the Ok button.

Important: Currently, only function keys (F1->F10) + an unique obligatory modifier (shift, control or alt) may be used as keyboard shortcuts for actions.

Edit Keyboard Shortcuts dialog log

At the bottom of the dialog window, the log indicates error messages and warnings. Here are the possible error messages:

  • "Cannot edit Keyboard Shortcut", followed by the reason.
  • "Keyboard shortcut already used"
  • "Conflict with <action name>"


Attributes Manager

Overview

The Attributes Manager displays all Attributes currently available, sorted by category. You can expand a category to see its contents by double-clicking on it. Next to an attribute's name is the attribute type, (the parameter that it contains) such as obstacle. See also Attribute Mode in Entity Setups.

Using the Attributes Manager

Choose Attribute Manager from the Editors menu to open this tool.

Toolbar

Create Attribute
Allows you to create a new attribute and/or new category.

Copy Selected Item Values
Copy the values of the selected attributes in the right window, to paste them in the Schematic, the Parameter Debugger or in the Attribute Manager.

Paste Value On Selected Items
Paste the value previously copied onto the selected attributes, if compatible. Useful to give a value to a selection of objects in a single operation.

Remove All User Attributes
Deletes all Attributes and Categories created by users, regardless of whether they are being used by elements in the composition. Note that you cannot remove system Attributes, i.e. those Attributes defined by Virtools or by custom plugins (see the Virtools SDK for information on creating new Attributes and registering pluigns).

Main Window (Object Name, Attribute Name, Attribute Value)

This window displays the list of the objects which have the attribute(s) currently selected in the left window. From here, you can quickly see and modify the attribute values of multiple objects. Through the context menu (right click) you can also copy and paste values from selected objects by right clicking on the selection, and you can also remove the selected attribute from the selected object. Double-clicking on the attribute value will open the edit dialog box.

Adding Attributes from Attributes Manager

Attributes can be dragged and dropped from:

  • The left list (list of all attributes)
  • The right list (list of objects with the attributes selected in the left list). Note that attribute's values will be copied too in this case.

to :

  • Objects in 3D Layout (if target object belongs to selection, then attribute is added to selection, otherwise to target only)
  • Objects in Level Manager (if target object belongs to selection, then attribute is added to selection, otherwise to target only)
  • Anywhere in an object's setup

Note that if an attribute is not compatible with a target object, the attribute will not be affected to it.


Hierarchy Manager

Overview

The Hierarchy Manager is opened by choosing Hierarchy Manager from the Editors menu. The Hierarchy Manager is a tree view of all renderable Entities (elements that derive from the class Render Object) contained in the composition.

You can collapse/expand a hierarchy by clicking the triangle next to the category, or by using the first two buttons in the top toolbar. This way you can expand/collapse multiple selected items.

To parent an element and all its sub-hierarchy, simply drag the element onto the new parent. If you want to 'orphan' an element (so that it no longer has a
parent), drag the element onto the Root.

You can modify the Render Priority of 3D Entities or 2D Entities directly in the Hierarchy Manager.

  • For 3D Entities, highest priority Entities are rendered first, with priorites ranging from -10000 to 10000.
    The main use of priorities is for transparent Entities, since they do not affect the z-buffer. Another use is to set a lowest priority to background Entities in order to draw the whole 3d scene faster: the main Entities will be rendered first, then the concealed parts of background Entities will not need to be drawn.

  • For 2D Entities, render priority is the "Z Order" field found in 2d sprite setup. In contrast to the render priority for a 3D Entitiy, the highest z order sprites are rendered last, that it is on foreground.

Use the up/down/left/right/home/end/page up/page down keys to navigate the tree.

Popup menu

  • Setup
    show object setup, available only on single selection
  • Rename
    rename object, available only on single selection. Keyboard shortcut is F2. Mouse shortcut is double click on object.
  • Edit Render Priority
    edit render priority. Mouse shortcut is double click on render priority. Works for multiselection.
  • Set Initial Conditions on Hierarchy
    add initial conditions on selected objects.
  • Remove Initial Conditions on Hierarchy
    remove initial conditions on selected objects.

Toolbar

Expand Selected
Expands the selected items in the hierarchy.

Collapse Selected
Collapses the selected items in the hierarchy.

Display/Hide Meshes
Allows the user to display the meshes used by the 3D Entities of the level. The mesh will be displayed as child of the object using it, with a different icon (a wire frame cube).

Display/Hide Materials
Allows the user to display the materials used by the 3D Entities of the level. The material will be displayed as child of the mesh using it. The materials will only be displayable if the meshes are already shown.

Display/Hide Textures
Allows the user to display the textures used by the 3D Entities of the level. The textures will be displayed as child of the material using it. The textures will only be displayable if the meshes and the materials are already shown.

Render Priority Column
Click a priority to edit. 3D Entities and 2D Entities are sorted by hierarchy, then by render priority, then by name.


Parameter Debugger

Overview

The Parameter Debugger is allows you to visualize and edit several local parameters or parameter outputs (pOuts) parameters at the same time. Parameters do not have to be in the same script - you can also paste parameters from Attributes or Arrays into the Parameter Debugger.

The Parameter Debugger editor is opened by choosing Parameter Debugger from the Editors. By default it opens in the lower half of Virtools.

How to use the Parameter Debugger

  • To select the parameters that interest you, hold down the CTRL key and clicking the parameters.
  • Once you have made your selection, right clicke of the parameters and choose Copy Selection or use CTRL+C.
  • click the Parameter Debugger tab to activate it, right click in the main window and choose Paste or use CTRL+V.
  • You will see four columns:
    • Name parameter's name if it is from an out parameter of a building block or a script local parameter; if it is the result of a parameter operation then it will just be 'Out'.
    • Value parameter's value (numerical, TRUE or FALSE if a Boolean or N/A if not available), which is editable by double clicking on it.
    • Owner Object object to which the parameter applies. This is useful if two or more scripts have the same name.
    • Owner Script script from where the parameter was taken (if applicable).

  • The values displayed will be updated when switching between play, pause or reset initial conditions unless you have activated the Schematic's Trace Mode in which case they will updated in real-time.
  • To change the value of a parameter, double click it. A edit parameter dialog box will open, allowing you to change the value.
  • To remove a parameter from Parameter Debugger, select the parameter by clicking on it and then either press the 'delete' key or right-click the parameter and choose delete in the menu that appears.
  • To add any more parameters, just return to the Schematic, copy the parameters, and paste them in Parameter Debugger as described above.
  • You can also watch attributes value, use the "Copy Parameter Value" or CTRL+C in the Attribute Manager or in an object attribute setup.


Path Manager

Overview

The Path Manager allows you to define paths to sources of data (image, sound or other data files).

For example, when a bitmap that is external to a cmo (i.e. not in a data resource or saved with the cmo) is loaded, paths in the Path Manager are parsed in the order displayed in the list. All paths from open data resources are displayed in the list. The Path Manager is a re-sizable dialog box.

About data resources:

  • Adding a data resource will automatically add paths of source data contained in the resource.
  • If you delete a path connected to an open data resource, that path will be back next time you launch the program if the data resource still exists.
  • Removing a data resource will not remove the paths created because of it. You will have to delete them manually.

  • Category:
    You can use the combo to choose between the category of paths to display: either bitmap, data or sound files are available.
  • Add Path:
    Allow the user to add a new path at the end of the path list. Either enter directly the path in the edit box or use the ellipsis button to browse with a standard open dialog box.
  • Delete Path:
    Delete selected paths. WARNING: if you delete a path belonging to an open resource, it won't be added back until you re-open this resource or you exit and launch the program again.
  • Up & Down:
    Allow the user to change the order of the paths in the list.

Mouse/Keyboard Shortcuts:

  • F2 / single click selected path / double click path:
    Edit selected path. The [image] button that appear on the right opens a parsing directory dialog.
  • Delete:
    Delete the selected paths.


Variable Manager

Overview

In Virtools Dev, a variable is an editor's or manager's internal parameter of that is exposed so that you can interact with or change its value. For example, Antialiasing is a parameter of the Virtools rendering engine that lets you specify the antialiasing level of the rendering (0= none, 1= 1x, 2= 2x, 4= 4x). If you want to force antialiasing of a composition at runtime, you would set the antialiasing level in the Variable Manager and mark that variable so that it is saved in the CMO. Here is the current list of variables.

The Variable Manager allows you to edit, save, load and copy variables from one composition to another in Virtools Dev. The Variable Manager lets you set new default values that will apply to other compositions, and you can restore back to default values (defined by dev.ini - see below) or native values (defined in internal code) if you modify a variable in a composition. Variables listed in bold indicate that their values are different from native settings.

User-definable default values of variables are saved in the configuration file dev.ini (located in the same directory as dev.exe). Initial settings of dev.ini are native values, until new values have been commited by the user. The dev.ini file can be edited in a text program for easier consultation and editing.

Certain variables are saved with a composition when indicated by an X in the composition column. A grayed X indicates that this variable is required by the composition. No X means the variable is not automatically saved with the composition, but you can still force it to be by double clicking in this column - that will make a black X appear. This way, you or your audience will be sure to play back the composition in the exact configuration it was saved in.

If you've made changes to variables in a composition, you can restore all or just some variables from the config file; and inversely, you can save all or just a portion of these customized settings to a new configuration file that can be loaded into another composition. Finally, with the Variable Manager, you can drag variables into Schematic and use them like local paramemeters.

Variables v. Preferences

The General Preferences window specifies variables for working in Dev. Modifications to General Preferences remain when a new composition is created. The Variable Manager gives you much more control over variables that affect how your composition is played even outside of Dev. Currently, crossover between the two concerns primarily file saving and compression options, but the Variable Manager offers extensive tooltips, more flexibility, and a better, more intuitive interface.

Using the Variable Manager

Choose Variable Manager from the Editors menu to open this tool.

Toolbar

Change Display Mode
The button lets you toggle between list and folder viewing modes, and you can click column headers to sort (e.g. below is sorted by composition column)

Default Selected Items
This button sets the selected variables back to native values (defined in the code itself) if they have changed.

Default All Variables
This button sets all variables back to their native values (defined in the code itself) if they have changed.

Commit
This button sets a new default value in the dev.ini file; and henceforth, this value will apply to all future composition unless the variable is edited in a composition or a new default value is committed.

Restore
This button restores default values (stored in the dev.ini file).

All/Composition/Application
This toggle button filters the list of variables that affect the composition, the application or both.

Save
This button exports all variables currently listed in an .ini configuration file that can be edited in any text program and imported into new compositions. IE: If the toggle filter is set to "Composition", only variables affecting the composition are exported. If certain variables are selected while saving, only those variables are exported; therefore, you can export just the custom settings you need for importing into a new composition.

Load
This button loads new .ini configuration files into the current composition and contains all or just a few variables that will override current settings.

Main Window

Variable Name
This is the name of the variable. Variables listed in bold indicate that their values have been modified from the default settings. You can click column headers to sort.

Value
The currently defined value. Bold values indicates a difference between the current value and the native value. Double click to change it; however, italicized values cannot be modified (These variables are read-only present only for monitoring).

Category
Identifies the variable's category or folder name depending on your Display Mode. You can click column headers to sort.

Composition
Certain variables are saved with a composition (when indicated by an X in the composition column). A grayed X indicates that this variable is required by the composition. You can force a variable to be saved in the composition by double-clicking the composition column. Once again, the italicized (read-only) variables cannot be saved.

Runtime Editing

There are 2 ways to use variables at runtime:

- Directly by dragging and dropping a variable into a schematic script. It will appear in white to differenciate from other local parameters, but you can use it exactly like a local parameter. (But you still cannot write into a read-only variables)
- By using the bc.GetVariableValue / bc.SetVariableValue methods in a RunVSL BB. (See VSL)

Additional Information

Current list variables, default values and descriptions


Variables List and Default Values

Variable Manager's List of Variables and Default Values

Overview

Below is the current list of variables listed in the Variable Manager. The information is listed in the following manner:
Category/Variable Name: (datatypes: native default values) : descriptions.

The initial default value listed below is the native value define in the source code. If you define a new default value, this information is kept in the configuration file dev.ini (located in the same directory as dev.exe).

Values indicated in the Variable Manager in Italic are READ ONLY. Boolean values ("bool") of 0 are FALSE, and 1 are TRUE. "Enum" is composed of a pulldown menu with a list of values.

Note: * indicates new variables added to this latest Dev release.

Category/Variable Name: (data type:default value) : Description

* Actions/Load At Startup: (bool:TRUE) : Allows you to specify if actions (in the /actions subdirectory) are loaded at Virtools Dev 's startup. In any case, you can still reload all actions with the 'Reload Actions' command (by right clicking on Actions tree root).

* Actions/Compile At Load: (bool:TRUE) Are actions compiled when loaded?

* Actions/Include In Compile All: (bool:TRUE) : Are actions also compiled when pressing 'Compile All' button in the VSL Manager interface.

BehaviorManager/MaxIteration: (int:8000) : This is the maximum iteration count of a behavior in the same frame.

* CK2_3D/BatchingMaxVertexCountToBeBatched: (int:32) : Objects with less vertices will be batched into a single command buffer to avoid sending too small primitives to the video card.

* CK2_3D/BatchingDisable: (bool:FALSE) : The default mode for rendering is to batch objects with same material so that they are rendered together for maximum performance. This can be disabled by setting this variable to TRUE so that object are rendered in hierarchical order.

* CK2_3D/DisableAnimationSorting: (bool:FALSE) : Disables the sorting of animations for character LOD the first time they are used.

* CK2_3D/DebugModeLineCount: (int:10) : Number of lines displayed in Debug Mode (See CK2_3D\EnableDebugMode)

CK2_3D/ForceLinearFog: (bool:FALSE) : Disables exponential fogs and enables linear fogs.

CK2_3D/EnableScreenDump: (bool:FALSE) : Enable CTRL+ALT+F10 to dump screen content to files.

CK2_3D/EnableDebugMode: (bool:FALSE) : Enable CTRL+ALT+F11 to draw render sequence and states.

CK2_3D/VertexCache: (int:16) : Default size of the graphic card vertex cache.

CK2_3D/SortTransparentObjects: (bool:TRUE) : Transparents objects are sorted from back to front before being rendered.

CK2_3D/TextureCacheManagement: (bool:TRUE) : Enable Texture management.

CK2_3D/ForceSoftware: (bool:FALSE) : Disable Hardware renderers.

CK2_3D/DisableFilter: (bool:FALSE) : Force the texture filtering to nearest (useful in software mode).

CK2_3D/DisableDithering: (bool:FALSE) : Disable dithering (useful in software mode).

CK2_3D/DisableMipmap: (bool:FALSE) : Disable mipmap filtering (useful in software mode).

CK2_3D/DisableSpecular: (bool:FALSE) : Disable specular highlights (useful in software mode).

CK2_3D/DisablePerspectiveCorrection: (bool:FALSE) : Disable texture perspective correction (useful in software mode).

CK2_3D/UseIndexBuffers: (bool:FALSE) : Enable the use of indexed buffers.

CK2_3D/UsePixelFog: (bool:TRUE) : Enable Pixel Fog.

CK2_3D/Antialias: (int:0) : Enable antialiasing (values from 2 to 16).

CK2_3D/TextureVideoFormat: (enum:1) : Default Video format for textures being created.

CK2_3D/SpriteVideoFormat: (enum:1) : Default Video format for sprites being created.

CK2_3D/BitmapSystemCaching: (enum:0) : Default system caching for sprites/textures being created.

CK2_3D/DisplayObjectInformation: (flag:0) : Object Information displayed.

CK2_3D/DX5LightingModel: (bool:TRUE) : Use the DX5 Lighting Model (usefull for backwards compatibility). Otherwise use the GL/DX7+ lighting model.

Debug/SaveFileStatistics: (int:0) : Write file statistics along with each saved file (in filenameStats.txt).

File Options/Textures,Sprites: (enum:0) : Saving options of bitmaps used in Textures and Sprites. Image files (used for Textures and Sprites) use the default save settings selected here, unless you choose a specific save setting in an individual Texture or Sprite Setup.

  • Saved as Raw Data saves image files as they appear in memory and includes them in the saved file. This means no compression is used and the size of the CMO/VMO size can increase considerably.
  • External Files saves references (i.e. the path and the filename) to image files inside the CMO file only. Images will not display if a Virtools Player (e.g. Virtools Dev, the Virtools Web Player) cannot find them.
  • Use specific format saves images files inside the CMO using a specific format, shown by a button to the right. Click the button to change the file type. Compression, if any, depends on the chosen file type.
  • Included inside CMO file saves image files inside the CMO in their original formats
File Options/Sounds: (enum:0) : Sound saving options used. Sound files use the default save settings selected here, unless you choose a specific save setting in an individual Sound Setup.
  • External Files saves a reference only to the original sound file inside the CMO file. Sounds will not play if a Virtools Player (e.g. Virtools Dev, the Virtools Web Player) cannot find them.
  • Included inside CMO file saves sound files inside the CMO file in their original format.

File Options/Compression: (enum:8) : This compresses files (CMO/VMO composition, NMO object, and NMS script files) when saving, using the loss-less zlib compression algorithm. The higher the compression level, the smaller the resulting file size. Note that compressed files take longer to save and load then uncompressed files.

File Options/Compression Level: (int:4) : This is the compresssion level of the whole file. Ranges from 1(Min) to 9(Max). The higher the compression level, the smaller the resulting file size. Note that compressed files take longer to save and load then uncompressed files.

* Globals/lastcmoloaded: variable storing the full path of the last cmo that was loaded.

Globals/StartingPath: (string:) : Absolute path of the main executable.

Globals/PluginPath: (string:) : Absolute path of the plugins directory.

Globals/StartingFlags: (flag:0) : Starting options of CK2. With these, you can disable the SoundManager, the InputManager and choose if you want dialog box to pop up on errors.

* Network/AutoProxy: (bool:TRUE) Enable automatic proxy detection under Windows (i.e. use Windows Proxy settings if available).

Profiling/ProfileEnabled: (bool:FALSE) : Enables profiling the behavioral engine's processing.

Profiling/RenderStateCacheHit: (int:0) : Number of hits per frame in the render state cache.

Profiling/RenderStateCacheMiss: (int:0) : Number of misses per frame in the render state cache.

Profiling/Average FPS: (float:0.000000) : Average frames per second.

Profiling/ProfilingBar: (BOOL: FALSE) : Displays the repartition of the processing in a color on-screen bar.

Profiling/ProfilingHistogram: (BOOL: FALSE) : Displays the repartition of the processing in a color on-screen histogram, along with a running FPS.

    The white curve is the FPS.

Profiling/ProfilingHistogramRate: (float: 1000) : Sample rate of the histogram, in ms.

Schematic/SceneFilter: (enum:0) : This is the Scene Filter state of the Schematic (Level=> no filter, Scene=> displays only scripts whose owners are active in current scene).

Schematic/TestShortcutsOnSave: (bool:TRUE) : Tests for when shortcuts are not linked and their sources are not saved in selection. In that case, the user is warned that the shortcut will not be saved.

Sounds/Mixing Method: (enum:8) : Sound Mixing Method.
Software: sound buffers will created be system memory and will use software mixing.
Managed: sound buffers can be assigned to a hardware or software resource at play time.
Hardware: sound buffers must use hardware mixing. If the device does not support hardware mixing or if the required hardware memory is not available the sound buffer will not created.

Statistics/Particles Count: (int:0) : Total Particles Emitted.

Undo/Depth: (int:50) : This sets the maximum number of steps that can be undone.

Undo/Log: (bool:FALSE) : When set to TRUE, undoable action are logged.

Undo/Irreversible Warning: (bool:TRUE) : When set to TRUE, the user is warned when irreversible actions are done.

VSL/Debug Check: (bool:TRUE) : Nullity check and boundary violation.

VSL/Show Warnings: (bool:TRUE) : Show warnings messages.

VSL/Stack Size: (int:1024) : Virtual Machine Stack Size.

VSL/Data Size: (int:262144) : Virtual Machine Data Stack Size.

VSL/User Watch Count: (int:2) : Number of watcher windows in debug mode.

VSL/Beep on compile: (bool:True) : Beep at compilation's end.


Options Menu

Menu Bar - Options Menu

File Menu Resources Menu Editors Menu Help Menu

General Preferences (CTRL+P)
opens the General Preferences setup.

Activate/Deactivate Trace Mode (CTRL+T)
activates trace mode for Schematic, allowing you to see which links are active.

Unused Objects Explorer
opens the Unused Objects Explorer.

Hide/Show Dynamic Objects
alternatively hides then shows objects and scripts created dynamically through building blocks. WARNING: this option must be enable before dynamic objects creation otherwise they won't be displayed afterward, when enabling it. Note: Showing dynamic objects helps you to debug, but, like the Trace Mode, it will slow down your composition, so use it wisely.

Refresh Windows
refreshes all windows, and resets the three main tabbed windows to their default size and position.

Reset Interface
resize all windows to their initial size, and close all separated windows.

Building Block Version Test
The function Building Block Version Test enables you to test all building blocks which do not vary their number of inputs or outputs to see if they are compatible with the current version of Virtools you are using.

Installed Plugins
opens the Installed Plugins setup.


Installed Plugins

Overview

The Installed Plugins window displays all plugins that are currently available to Virtools Dev. A Plugin is a software component that provides some sort of functionality to CK2, the Virtools Behavioral Engine. There are a number of different types of plugins: Behavior Building Block plugins, file reader plugins (for sounds, models images ...) and so on. For information on creating and registering your own plugins, see the Virtools SDK.

Installed Plugins Window

Plugin
The name of the plugin.

Active
The status of the plugin, active or inactive. Note that only plugins listed under Managers can be deactivated.

Description
A short description of the functionality the plugin provides.

Dll
The name of the plugin file.

Author
The author of the plugin.

Unloading Plugins Temporarily

You can temporarily unload a plugin. This allows you to recompile a plugin, such as custom plugins you are developing with the SDK, without having to restart Dev.

  1. Open the Installed Plugins window.
  2. Right-click the plugin you wish to unload and recompile or replace, and choose Temporary Unload.
  3. Compile your plugin, or replace the file (file names must be the same).
  4. To reload the plugin, either
    • right-click the plugin, choose Reload, or
    • close the Installed Plugins window.


Building Block Version Test

Overview

Building Block Version Test enables you to make sure that the building blocks you are using are compatible with the latest version of Virtools, and so your compositions may be viewed without any problems in the Virtools Web Player. This function is accessible from the Options menu only. When an obsolete building block is detected, it can be replaced.

Using Building Block Version Test

When you click Building Block Version Test from the Options menu, the program tests all building blocks in your composition.
If differences between behaviors and their prototype (the description of the BB in the behavior DLL) are detected, a dialog box will appear asking whether you wish these behaviors to be replaced automatically.
Behaviors differences are detected when

  1. the BB version, defined internally, has changed
  2. the number of behavior inputs (bIns) has changed since last version, and the behavior does not allow the creation of new bIns
  3. the number of behavior outputs (bOuts) has changed since last version, and the behavior does not allow the creation of bOuts
  4. the number of parameter inputs (pIns) has changed since last version, and the behavior does not allow the creation of new parameter inputs
  5. the number of parameter outputs (pOuts) has changed since last version, and the behavior does not allow the creation of new parameter outputs (pOuts)
  6. the number of internal local parameter has changed since last version, and the behavior does not have a flag that specifies this number can change.

Regardless of whether you choose to have an obsolete version of a building block replaced or not, the name of the obsolete building block will be recorded in the Error Log, as shown below.

There can be 3 error messages

  • Building Block <bb name> is obsolete
    for case (1)
  • Building Block <bb name > - Version Differences
    for case (2) to (6)

  • Building Block <bb name> is invalid (no prototype guid) (DLL not here / behavior's guid has changed from the last DLL), or
  • Building Block <bb name>'s prototype not found
    In these last 2 cases, you should
  • check that all your behavior .dll files are present, and are up to date
  • if all is OK and the building block you are using is provided by Virtools, you should contact Tech Support
  • if the building block was developed with the Virtools Dev SDK by a third party, you should contact them

Warning

Remember that if a building block allows the creation of bIns, bOuts, pIns, and/or pOuts, Building Block Version Test will not test the differences for this kind of IO with the behavior's prototype (such as the behavior Switch On Key).

See also

TestBB.exe to parse all CMOs in a folder to identify the compositions that need to have BBs updated and Obsolete/Invalid BB Explorer in the Schematic Toolbar.


Using TestBB.exe

Building Block Version Test in Multiple CMOs (TestBB.exe)

Overview

TestBB.exe enables you to make sure that the building blocks in your CMOS are compatible with the latest version of Virtools, and so your compositions may be viewed without any problems in the Virtools Web Player. The application parses a folder's CMOs to identify (in a log file) which compositions need updating. TestBB.exe is accessible from the root folder alongside Dev.exe.

Once the CMO has been identified and opened in Dev, the easiest way to update BBs is to use the Building Block Version Test, accessible from the Options menu only.

When an obsolete building block is detected, it can be replaced in the Virtools interface.

TestBB.exe Interface

- Directory : specify the directory where cmos are to be tested
- Output File : output log file
- Short message window (with text such as "Processing d:\toto.cmo", and "Test Building Blocks completed")
- Check method combo box (see below)
- Recursive check box - for checking compositions in nested folders.
- Identify Variable BBs check box: Checks if the io count/ param count is different from prototype even with behaviors that are known to have variable io / param count. If differences on variable IOs behaviors are found, this is will result in just as a "warning."
- Progression bar
- Test button
- Clear Log button
- Stop button
- Close button

Check Methods

simple check

Only one message for all same BBs

no proto =>
"*-->No Prototype (missing DLL) : behavior_name"

IOs/Params count difference
" *-->To Update : behavior_name"

IOs/Params count differences, but on a BB with variable IOs/Params
" *-->Warning : behavior_name"

simple check with occurences

one message per BBs, even if some BBs are the same (ie, have the same name & prototype)
Path of the BB is added : (Path : <owner_name> / [script_name] / graph / .. / BB_name)

verbose check

Same as simple check, but with additionnal information :

<obsolete>
<old version>
<no function>

<bIn count pb>
<bOut count pb>
<pIn count pb>
<pOut count pb>
<local count pb>

<warning bIn count>
<warning bOut count>
<warning pIn count>
<warning pOut count>
<warning local count>

warning is for BB with variable IOs/Params. It may appear only if "identify Variable BBs" check Box is checked

verbose check with occurences

same as simple check with occurences, but with additionnal information (see verbose check)

just one warning need update

if there are some BBs that really need an update
(BBS with variable IOs/Params are not taken into account,
even if "identify Variable BBs" check Box is checked)
the following message will appear:
" *-->This file has some BBs that need an update";

See Also

Building Block Version Test under Options to replace all obsolete BBs in a composition or Obsolete/Invalid BB Explorer in the Schematic Toolbar.


Unused Objects Explorer

The Unused Object Explorer allows you to quickly find unused resources in your composition, such as textures or meshes.

When launched, the explorer will browse all the objects in the level to determine which objets are used, either directly in the objects rendered or just referenced in a script or in an array. It will then display of all the objects found with a A next to their name, in the column named exclude. You can in fact click the A to check it and exclude the object. When pressing the Delete button, you will delete all the objects with the A unchecked. Clicking Cancel will exist the explorer without destroying anything.


General Preferences

Overview

General Preferences contains controls relating to the general appearance of the Dev user interface as well as options related to specific features such as selection modes, 3D transformation tools, rendering modes and engines, scripting tools and so on.

To open the General Preferences, click the General Preferences icon [image] in the top right corner of the 3D Layout window, or choose General Preferences from the Options menu.

The following sections make up the General Preferences:

  • 3D Layout - Rendering
  • 3D Layout - Actions
  • 3D Layout - Interface
  • 3D Layout - Reference Grid
  • 3D Layout - Snap & Align
  • Schematic
  • Miscellaneous Controls
Use the Current Prefs menu to select the preferences you wish to edit.


Preferences: 3D Layout - Snap & Align

3D Entities

World Sections
Enables snapping a 3D Entity to world sections in the 3D Layout. To change the size of world sections, change the values for World Step (Increments) in World Settings in the 3D Layout - Interface preferences.

Object Axis
Enables snapping the axis of a 3D Entity to the axis of another 3D Entity.

Mesh Vertices
Enables snapping a 3D Entity to the vertices of another 3D Entity.

Mesh Edges
Enables snapping a 3D Entity to the edge of another 3D Entity.

Mesh Faces
Enables snapping a 3D Entity to the face of another 3D Entity.

Translate Influence Radius
The distance, in pixels, within which a 3D Entity snaps. The smaller the value, the closer the selected element must be to the 3D Entity before it snaps into place.

Rotate Step
The amount of degrees a 3D Entity rotates each step.

Scale Step
A percentage defining how much a object scales each step.

2D

Screen Borders
Enables snapping a 2D Entity to screen boundaries.

Screen Guide Grid
Enables snapping a 2D Entity to the screen guides (which are not shown by default). To change the size and dimensions of screen guides, change the values in Screen Guide in the 3D Layout - Interface preferences.

Sprites
unselected sprites.

Translate Influence Size:
The distance, in pixels, within which the selected 2D Entity snaps. The smaller the value, the closer the selected element must be to the 2D Entity before it snaps into place.


Preferences: 3D Layout - Actions

Actions

Objects Manipulation

Translation
When not in Sticky Mode, this is the translation factor for the Move action. Otherwise, the picked object is stuck to the mouse.

Rotation
 Number of degrees to rotate the selection when using the Rotate tool.

Scaling
The scaling percentage when using the Scale tool.

Camera Navigation

You are advised to leave the default Degrees and World Units values set for camera navigation. If you do choose to change any value, you can revert to the defaults by clicking Default in the left bottom corner of the dialog box.

Constant Speed
Continuous navigation action as long as the left mouse button is pressed, even if you do not move the mouse.

NOTE: The FlyCam is activated by pressing Y.

Orbit

Free Cameras Target

A free camera is a camera without target, just with an orientation. An Orbit action needs a target in order to work, so a fake target is created for free cameras. The target is positioned at N units on the Z axis of the camera. N can take one of the following values:

N percent between frontplane and backplane
Percentage

N units plus the frontplane
3D units

Fixed position
3D units

Orbit around selection
When objects are selected, you can orbit either around the target or the selection. Possible values: "only if objects selected", "only if selection is locked", "never".

The frontplane and backplane are clipping planes perpendicular to camera direction. The frontplane is near the camera and the backplane is far from it. Only what is between those planes is shown. See Camera Setup , Camera Characteristics paragraph, clipping sub-paragraph.


3D Layout - Interface

Preferences: 3D Layout - Interface

Interface Objects

Constant Size On Screen

3D Frames/Cameras/Lights/CurvePoints
Ensures elements are always rendered the same size, regardless of how far or close they are to the current camera. Use the slider or text field to the right to set the constant size.

Object Axis, Size

The size of selected objects axis can be customized:

  • Object Axis, Variable Size : the axis size depends on the object's scale
  • Object Axis, Constant World Size : all axis have the same world size, the size is set with the slider or the edit box on the left.
  • Object Axis, Constant Screen Size : all axis have the same size on screen, whatever the distance to the viewpoint is. The size is set with the slider or the edit box on the left.

Setups

On

Automatic show light cone
Selects the Show Influence check box in the Light Setup for any Lights you create.

Automatic show camera cone
Selects the Show cone check box in the Camera Setup for any Cameras you create.

Automatic show entities in player mode
Selects the Show In Player mode check box, if it exists, in the Setup of any elements you create.

Automatic Show Setup
Opens the Setup for any elements you create.

Do not open setups of the same type
Ensures only one Setup per type of class opens. E.g. if a Camera Setup is already open and you create a new Camera, an additional Setup is not opened but the current Setup is instead used for the new Camera. You can switch from Camera to Camera by using the menu next to the Name parameter. If you want to open an additional Setup of the same class type, SHIFT+drag the tab of the Setup.

Curve

View Plane Distance/(Ortho)
Distance from the viewer to a invisible plane parallel to the camera, used for adding points to Curves. You can set different values for perspective and orthographic (Ortho) Cameras.

Global

Show On-screen Debug Data
Displays information useful for debugging in the top-left part of the rendering window: mouse position and state, information about elements intersected by the mouse (3D Objects, Meshes, Materials, Textures, etc.)

World Settings

World Size

X Y Z, Min Max
Defines the boundaries of the 3D space of your world. You cannot move any element beyond the world's boundaries.

World Step (Increments)

X Y Z
Defines the size of world steps. World steps are invisible sections in the world, used by the Snap & Align tool if the World Sections check box is selected in the 3D Layout - Snap & Align preferences.

Screen Guide

The screen grid is used for constraining 2D entities such as 2D frames or 2D sprites to an imaginary grid.

Offset X,Y
Moves the grid by X,Y pixels (or percent if the Homogenous Coordinates check box is selected) relative to the top-left screen origin.

Step X,Y
Size of screen guide sections in pixels (or percent if the Homogenous Coordinates check box is selected).

Homogenous Coordinates
Switches measurements from pixels to percent.


Preferences: 3D Layout - Reference Guide

Grid

Guide Orientation

X+Y, Y+Z, X+Z
The 3D reference guide is aligned to the world according to the plane chosen. You cannot rotate or translate the reference guide with one of these options set.

Free Transformation
The 3D reference guide can be freely rotated or translated in the world.

Sections Count

Number of horizontal and vertical sections that compose the 3D reference guide.

Size per Section

Size of each section in the 3D reference guide, in world values.


Preferences: 3D Layout - Rendering

Author Mode

These settings only apply to Author Mode in Dev.

Render Device
Selects the render engine for Author mode.

Render Type
Sets the shading mode used to render all elements, regardless of the Shade Mode parameter set in individual Material Setups. Wireframe, Flat and Gouraud.

Add Wireframe Layer
Renders the scene a second time adding a wireframe layer. If you just want to render in Wireframe, do not use select this check box but set Wireframe for Render TYpe above instead.

Textured
Renders Textures applied to Materials.

Show Frames/Lights/Curves/Cameras/Portals
Displays elements of this type in the rendering window of the 3D Layout.

Show World Axis
Displays a small image in the bottom left of the 3D Layout rendering window showing world orientation using an X, Y and Z axis.

Show Object Axis
Displays a a small image for selected elements showing their orientation using an X, Y and Z axis.

Realtime setup updates
Update Setups in real-time after any modification in the 3D Layout. For example, if an entity is moved, it's position is updated in real-time with every mouse move. If Realtime Setup Updates is not selected, the position is updated only when the mouse button is released. This feature can slow down action in the interface however.

Player Mode

These settings only apply to Player mode in Dev; they do not apply to any other Virtools Player (e.g. the Virtools Web Player).

Fullscreen Render Device
The device to use for fullscreen in Player mode. This does not have to be the same as the Render Device used in Author mode. To switch from windowed to fullscreen rendering and vice-versa, press ALT+ENTER in Player mode.

Render Type/Add Wireframe Layer/Textured
Same as in Author Mode described above.

Render Mode
Screen resolution and color depth to use when rendering fullscreen. Values are displayed as: Width x Height x Bits per pixel and optional refresh rate. (Hz) (Example: "640x480x16 @ 60Hz" )

Show All Frames/Lights/Curves/Cameras/Portals
Displays all elements of this type in the rendering window of the 3D Layout. If you want to show just certain instances of a type of element, use the Show In Player Mode parameter in the Setup of the element you want to display.

Show Reference Guide
Displays 2D and 3D reference guides, if these reference guides are normally visible in Author mode.

Automatic switching to Fullscreen mode
Switches to fullscreen automatically when you switch to Player mode.

Automatic show selection
Shows elements that are not usually visible in Player (e.g. 3D Frames) mode if they are selected before switching to Player mode.

Realtime setup update every N frames
Updates the parameters of open Setups every N frames. Low values can cause the frame rate to drop dramatically, as CPU time is spent refreshing values.

Update cursor in player mode
Updates the cursor according to any 3D Layout transformation or camera navigation tool you use; leave clear if you are using BBs to set a custom cursor.

Author Level/Scene Settings

Ignore Camera Aspect Ratio
Ignores any cameras aspect ratio set, and instead renders in all the rendering window of the 3D Layout.

Screen size
Sets the size of the render context in the rendering window of the 3D Layout. Options available are:
  • Window extents
    Resizes the render context according to the window's size.
  • 320x200, 320x256, 512x384, 640x400, 640x480, 800x600
    Presets a resolution in pixels, width x height.
  • Custom
    Sets a custom resolution in pixels, width x height.


Preferences: Miscellaneous Controls

CK2 Settings
Displays details about the version of CK2 (the Behavioral Engine) you are using.

Render Engine
Selects the render engine to use (if several are available). The box below this menu displays version and author information about the current render engine.
NOTE: You must restart Virtools for the changes to take effect.

Show Dynamic Objects
Displays objects that are created dynamically at run-time (in Player mode).

Sound Enabled
Enables the sound engine.

Direct Input Enabled
Enables Direct Input in in Player mode. If Direct Input is not enabled, then the Behavioral Engine ignores any keyboard or mouse input.

Compress file using compression level
Compresses files (CMO/VMO composition, NMO object, and NMS script files) when saving, using the loss-less zlib compression algorithm. Select the compression level (1-9) from the menu to the right. The higher the compression level, the smaller the resulting file size. Note that compressed files take longer to save and load then uncompressed files.

Sound files save options
Sound files use the default save settings selected here, unless you choose a specific save setting in an individual Sound Setup.

  • External Files
    Saves a reference only to the original sound file inside the CMO file. Sounds will not play if a Virtools Player (e.g. Virtools Dev, the Virtools Web Player) cannot find them.
  • Included inside CMO file
    Saves sound files inside the CMO file in their original format.
Texture/Sprites save options
Image files (used for Textures and Sprites) use the default save settings selected here, unless you choose a specific save setting in an individual Texture or Sprite Setup.
  • Saved as Raw Data
    Saves image files as they appear in memory and includes them in the saved file. This means no compression is used and the size of the CMO/VMO size can increase considerably.
  • External Files
    Saves references (i.e. the path and the filename) to image files inside the CMO file only. Images will not display if a Virtools Player (e.g. Virtools Dev, the Virtools Web Player) cannot find them.
  • Use specific format:
    Saves images files inside the CMO using a specific format, shown by a button to the right. Click the button to change the file type. Compression, if any, depends on the chosen file type.
  • Included inside CMO file:
     Saves image files inside the CMO in their original formats.

Image Quantization Quality
Sets the quantization level, if any, for 8 bit BMP, PNG and PCQ image files. Quantization is the process of converting the current palette of colors used for an image to fewer colors. The quality of the resulting image depends on this value: low values result in better quality, but also a longer quantization time. Virtools however recommends using specific image software, such as Adobe Photoshop, Jasc Paint Shop Pro etc to quantize images.


Preferences: Schematic

Main

Automatic Link
Activates Link mode automatically when you click a bIn, bOut, pIn or pOut. If you wish to select a bIn, bOut, pIn or pOut with this option selected, hold the CTRL key when clicking the bIn, bOut, pIn or pOut.

Horizontal/Vertical Scrollbar
Displays scrollbars. If you do not wish to display scrollbars, click-drag to scroll in the Schematic.

Strict Multi-Selection
Selects only elements that are entireley inside the selection area when using CTRL+click-drag to select elements.

Save Scripts Snapshots
Saves Script snapshots with the script.

Auto Resize Scripts to minimum height
Resizes the bottom boundary of a script to the minimum height needed to display.

Test Parameter Link after Loading
Tests pLinks more accurately when loading a file. This can increase loading time.

Remove Invalid Link after Loading
Removes invalid links after loading. If this option in not selected, links are still shown in the Schematic, but in a different color (see Schematic Colors below).

Path Finding Link Mode
Calculates the best path when creating a link or moving an element that is linked. You can invert this mode by holding ALT when creating links or moving linked elements.

Easy Finding Parameter Operation Dialog (recommended)
Shows only valid paramOps according to the elements you lock by clicking one or several of the locks next to the pIns, the pOut or the operation type.

Quick Finding Parameter Operation Dialog (1.0.1 style dialog box)
Reverts to the old style paramOp dialog box - it is not possible to lock elements. Valid paramOps only appear once you have selected the two pIns and the pOut.

Automatic Scroll Delay (ms)
Enables automatic scrol. The smaller the value, the faster the scroll. Automatic Scroll is activated for instance when your are linking and when the mouse cursor is near a boundary of the Schematic.

Max Recent Building Block
Sets the maximum number of recently used BBs to display in the menu that appears when you SHIFT+right-click.

Enable Tooltips. Delay (ms)
Shows tooltips. The associated value is the delay before a tooltip appears when the mouse hovers over an element. 1 reseults is immediate tooltip, 0 ddefaults to the global Windows value (commonly 500 ms).

Schematic Colors

Event Link Color
Color for event links (a.k.a bLinks).

Parameter Link Color
Color for pLinks.

Exported Parameter Link Color
Color for exported pLinks.

Parameter Operation Link Color
Color for paramOp links.

Valid Link Color
Color for valid links in link mode, before you close the link.

Invalid Link Color
Color for invalid bLinks (after loading a file).

Obsolete Building Block Color
Color for obsolete BBs (after loading a file).

Behavior Without Prototype Color
Color for BBs that have no prototype (after loading a file).

Behavior Without CKObject Color
Color for BBs that have no CKObject (after loading a file).

Building Block to Replace Color
Color for BBs whose prototype has changed between the version used to save the file, and the version used to open the file (after loading a file). Certain BBs have been improved between 1.0.1 and 2.0. and so you may wish to update a BB to take advantage of new features or bugfixes. E.g. Bezier Progression BB did not previously (1.0.1) have a Progression pOut. As version 2.0 does have this pOut, if you open a file saved with 1.0.1 that contains this BB, the BB is colored the color selected in this option.


alienbrain Menu

Menu Bar - Alienbrain Menu

File Menu Resources Menu Editors Menu Options Menu

Overview

NXN's alienbrain is a complete 3rd-party asset management solution that helps you manage your Virtools projects. The system provides efficient asset and configuration management for graphics, 3D models, textures, video, audio and source code, and now features seamless integration with Virtools Dev.

NXN alienbrain features:

  • Integrated rights management, version control and an intuitive “check in/check out” procedure managed directly in the Virtools Dev interface.
  • Previews of Virtools objects made available to all team members, all the time. Instead of opening Virtools Dev, assets can be accessed via the user-friendly alienbrain interface and the Virtools Web Player.
  • Easy-to-insert comments and logs for each object to improve archiving, retrieval and overall project management (NXN offers an extension to link alienbrain to Microsoft Project).

You will need to own NXN alienbrain version 6 (Service Pack 2 : Version 6.0.2.383) in order to use this new feature in Virtools Dev.
Contact http://www.nxn-software.com for more information.

Installation

Please refer to the NXN alienbrain Reference Material for instructions on installing alienbrain on your server and workstations.

If NXN alienbrain Release 2 is installed on your computer, the NXN alienbrain menu will be available in Virtools Dev main menu.

Menu Options

The following alienbrain options will be available to you depending on the state of the project or element that you are working with.

Load Composition from NXN alienbrain
To open and check out a Virtools composition from an NXN alienbrain project.

Check Out
To Check a file Out for editing marks the document as being in use. Others may only view the content or Get Latest Version.

Check In
To check a file In copies your local version to the project database and makes it available to other users.

Undo Check Out
To cancel any changes made to the file while it was Checked Out. This means the Check Out flag is removed from the project file in the server database.

Get Latest Version
To get a local copy (or update your local copy if you already have one, in which case the items would be marked with the grayed out file icon rather than the question mark).

Remove from Source Control
Removes the file from source control by deleting the server copy.

Import
To import a new file or a whole folder into the database.
Show History
To view the history of a file. The History Dialog lists all versions of a file with additional information like user name, date of a particular action (such as Check Out, Check In, etc.).

Show Properties
To display the NXN alienbrain settings for a file.

Show Database Explorer
To open the NXN alienbrain Database Explorer. Here you can browse through the NXN alienbrain tree (as in the NXN alienbrain Client), open files by drag and drop and perform actions such as Check In/Out by right-clicking the tree icons. The NXN alienbrain Database Explorer can also be used to perform advanced operations such as version rollback.

Show Settings
To display and edit alienbrain settings and preferences in Virtools Dev.

For each setting:

  • always: automatic check out/check in/get latest version without dialog
  • ask: a dialog is opened before any check out/check in/get latest version.
  • never: no action is taken by the NXN alienbrain plugin in the setting's

Note: "When opening a file with references" performs a "Get Latest Version" for resource tabs opened within the Virtools Dev interface and for loading a CMO with external resources such as textures and sounds.

Disable / Enable NXN alienbrain
To disable/enable the asset management through NXN alienbrain. The enabled state is saved when a Virtools Dev session is closed.

Resources Management within Virtools Dev with Alien Brain

You may have several resource tabs opened within Virtools Dev, and a source control icon on each resource tab indicates whether or not it is managed by NXN alienbrain.

The resource is fully managed by NXN alienbrain. It is located in a folder that mirrors a project folder of NXN alienbrain server.

The local resource folder is not currently synchronized with the Project on the NXN alienbrain server. (The resource folder itself does not exist in the Project folder on the NXN alienbrain server.)

The resource is not manageable by NXN alienbrain, or NXN alienbrain plugin in Virtools Dev is disabled.

Note : When launching Virtools Dev, if the NXN alienbrain plugin is enabled and if the settings allow it, you get the latest version of each resource folder managed by NXN alienbrain. The setting used is When opening a file with references.

Contextual menus for Resources

Below is an example of a resource tab:

A contextual popup menu for each part of the window is available with the right mouse button.
Areas 1 and 2 target the entire content in folders, while Area 3 target specific files.

The commands related to NXN alienbrain are the same as the main menu (listed above).

Loading Virtools Dev files (nmo and cmo) with textures or sounds stored as (external) filenames

When loading a file that contains references to external textures or sounds (if these resources are manageable by NXN alienbrain), the NXN alienbrain plugin will ask whether you want to get the latest versions of these files. To do this, the NXN alienbrain plugin must be enabled, and the setting When opening a file with references should be set to Ask.


Status Bar

Click an area below [image] for help on a specific element. Position the mouse pointer over an area to see a short description of that element.

Event Log Profiler Play/Pause - Time Settings

More details for the following features are described on separate separate pages:

  • Event Log
  • Profiler
  • Initial Conditions
  • Time Settings

Selection Name:
Show the name of selected objects in 3D Layout. Shows the name of elements rolled over or selected in Schematic. This is very useful to know Input (bIn/pIn) and Output (bOut/pOut) names.

Action:
Displays the name of the current tool, if one is selected.

X Y Z Coordinates:
Shows 3D Layout selection world coordinates.

Event Log Information:
Shows Event Log messages. See Event Log for more details.

FPS:
Shows frame rate in frames per second. Display NA when not running. See also Time Settings.

Restore Initial Conditions:
Stops playing and/or Restore Initial Conditions for Objects having some (shortcut is Ctrl+Backspace). See also Initial Conditions and Initial Conditions in Level Manager.

Play/Pause - Time Settings:
Starts playing the composition or pauses the composition. Note that Pause does not reset Initial Conditions (shortcut is Ctrl+Spacebar).
You can access Time Settings by right-clicking the Play button.

Step One Frame:
Process only one Frame whether if you are in play, stop or pause mode (shortcut is Alt+Spacebar).


Event Log

Overview

The Virtools Event Log serves to warn you when you try to do something that is not possible, such as applying a behavior to an Entity that may not accept it. The Event Log also keeps track of the any scenes you load, and any media that you add to your composition.

Using the Event Log

The Event Log is accessed by clicking on the Event Log icon [image] which towards the bottom of the Virtools screen close to the play button [image].

Above you can see what the Event Log looks like just after opening Virtools. Virtools reports an error by flashing the Event Log icon red and displaying the message in the bottom status bar.

Clear:
Clears the Event Log. The Event Log can be cleared by right clicking on the [image] icon too.

Close:
Closes the Event Log


Time Settings

Play/Time Settings

Overview

Switched from Author mode to Play mode ("plays" the composition) or vice versa ("pauses" the composition). Note that Pause does not reset Initial Conditions.

To accessTime Settings, right-click the Play button. Normally the framerate is linked to the behavioral rate. This can sometimes be problematic if you have a powerful computer, in which case it can sometimes be better to limit the frame rate. Time settings allow you specify whether the Frame and Behavioral Rates should be linked or separate, and also allows you to customize these settings.

Using Time Settings

To access Time Settings, right-click on the play [image] or pause [image] button. The following dialog box will appear:

Frame Rate:

  • Free:
    The Frame rate is free, the rendering and behavior processing is called without any wait time.

  • Synchronize to Screen:
    The frame rate cannot be faster than the monitor refresh rate. The frame is rendered synchronously with the VBL to avoid tearing effects. In this mode if the scene is too complicated to be rendered in one frame, the frame rate will be an integer divider of the refresh rate.

  • Limit:
    if you select this option, you must specify a maximum permitted Frame Rate in frame per second. Useful if you want your composition adapted to a specific computer type or when authoring for the web, to free CPU time for other applications.

Scale Time:
By selecting this option, you can speed up the normal progression of your scene by a set amount.

Behavior Rate:

  • Linked to Frame Rate:
    If selected, then Behavior Rate will be connected to Frame Rate.

  • Limit:
    Selecting this will separate the Behavioral Rate. You must then select the maximum Behavioral rate in frame per second.

Delta Time:
Specify these values to set the minimum and maximum Delta Time that will be passed to behaviors. It can be used to avoid huge Delta Time on really slow machines or too small Delta Time on fast machines.

Virtools Web Player

You are advised to limit choose Frame Rate, Limit (e.g. to 60) for all compositions that are designed to be viewed using the Virtools Web Player. This way the Virtools Web Player will not use all available resources on the target machine.

Troubleshooting

If you have a powerful graphics card and/or CPU, and the Frame Rate is too high, you should try limiting the Frame Rate to the same speed as your graphics card (for example 60 FPS).


Profiler

The profiler allows you to see how much computing time is devoted to particular tasks. The Profiler accessed by clicking on the profiler icon [image] which is located towards the bottom of the Virtools screen near to the play button [image]. Below you can see how the Profiler looks in use:

Execution:
This is where the execution times of the main sections of the processing loop are displayed. Next to the name is a bar which represents the percentage of this part in the whole process, then the time spent doing it in milliseconds. The main sections are:

  • Interface/Windows:
    Time spent by the interface, catching and sending events, drawing widgets, etc.

  • Rendering:
    The rendering of the 3D Objects, including for Virtools Dev SDK users, pre-main and post- render call-backs.

  • Behavior Graphs Management:
    Processing of behavior graphs: inputs and outputs, transfer of parameter values etc.

  • Behaviors Code Execution:
    Processing of the behaviors' core code (see details below).

  • Parametric Operations:
    Time spent to evaluate the parameter operations.

  • Animations:
    Processing of the animations (Keyed or morph).

Database:
Information about the scene currently being rendered. Number of 3D Objects, Textures, Sprites and Behaviors. Also displayed is the number of faces and vertices processed.

Refresh:
Refreshes the databases values.

Render:
Display the frame rate in frame per second (See also Time Settings), number of Objects, Faces and Lines Drawn.

Video:
Display number of Textures and Sprites and total size.

Behavioral:
Information on the behavioral objects processed. Number of behaviors executed, number of BB executed, links parsed and delayed links.

Details:

By clicking the icon [image], you can expand the window and access a tree view, where all behavioral objects, all scripts, all behaviors and finally all building blocks are listed, with their cumulative execution times. You can also see the User Profile Times, which are timers a Virtools SDK user can put into their code to profile a specific section of code. You can also sort the behaviors by executing time by selecting Sort By Execution time.
Double-click a script will show it in Schematic.


3D Layout

Click an area below [image] for help on a specific element. Position the mouse pointer over an area to see a short description of that element.

Snapshot 3D Layout Explorer Selection Group Select Camera General Preferences Selection Tool Lock Selection Selection Mode Select and translate Select and Rotate Select and Scale Constrain Axis or Plane Referential Toggle Snap Toggle Hierarchy Pivot Axis Toggle Guides Create Camera Create Light Create 3D Frame Create Curve Create Grid Create 2D Frame Create Material Create Texture Create Portal Camera Dolly Camera FOV Camera Zoom Camera Roll Camera Pan Orbit

  • 3D Layout Shortcut Menu
  • 3D Layout Keyboard Shortcuts
  • Flycam

The 3D Layout (default: top left) displays the content of your project in a real-time 3D environment and provides tools for creating, selecting or manipulating 3D Entities (such as 3D objects, lights, cameras, curves and so on), as well as navigation tools.

n.b. You can access the preferences for the majority of tools by right-clicking the icon.


Toggle Guides

Toggle Reference Guide

The Reference Guide provides with 3D lines allowing you to see perspective better.

Don't forget right clicking opens guide preferences!

G - Toggle Reference Grid On/Off
SHIFT+G - Toggle Screen Grid On/Off
CTRL+G - guide preferences

Toggle Screen Guide

The Screen Guide provides a grill allowing you to place and line up 2D elements more easily.

Don't forget right clicking open interface preferences!


3D Layout Shortcut Menu

The Pop-Up Menu can be used by right clicking in the 3D Layout View. The display changes depending on whether the mouse is over an entity, or if any entities are currently selected and if current active camera is one of the default cameras. The parts available are:

  • Object related
    Using this part you can call the setup of the entity under the mouse, and to some other entities attached to it. For example, a 3D entity might have a mesh and the mesh a material. On the screen shot above, you can clearly see that these setups are available on the menu.
  • Camera related
    If current camera is not part of default cameras, you can popup the setup for the camera. Any camera can be reset to its defaults. In this case, all its settings will be lost. You can change the current camera through a sub-menu.
  • Initial Conditions on Current Object
    Use this controls to memorize/set/remove the initial conditions of the object under the mouse.
  • Scripts related
    Scripts can be created on current object, and on entities attached to it. Scripts can also be created on current camera. If objects were selected, scripts can be created on each object of the selection. If current entity or camera have any scripts, they can be shown in the Schematic.
  • Selection related
    Select All selects all visible objects in the scene. Clear Selection removes any object in the selection. Invert Selection adds to selection every unselected object, and vice versa. Copies of selected object can also be made through Duplicate Selection. Delete Selection removes definitely the objects from the memory.

About 3d Frames representation:

Selected 3d frames representation can be changed in 3d Layout with the Pop-Up Menu that should look like this

See 3d Frame setup to learn more about how to customize 3d Frames shapes.


3D Layout Keyboard Shortcuts

Player/Author Mode:
  • CTRL+SPACE - Play / Stop
  • CTRL+BACKSPACE or Alt+BACKSPACE - Restore Initial Conditions
  • ALT+SPACEBAR- Do One Step
  • ALT+ENTER - Toggle windowed / Fullscreen mode in Player Mode

Object Selection:

  • CTRL+C - Copy selection
  • CTRL+D - Clear selection
  • CTRL+A - Select all
  • CTRL+I - Invert selection
  • SPACEBAR - Lock selection
  • DELETE - Delete selection

Transformation Tools:

  • X - Move
  • C - Rotate
  • V - Toggle Scale (Normal/Volumetric/Uniform)
  • S - Toggle Snap
  • H - Toggle Hierarchy

Axis and Plane Constraints:

  • F5 - Switch to X constraint
  • F6 - Switch to Y constraint
  • F7 - Switch to Z constraint
  • F8 - Toggle XY/YZ/XZ constraints
  • F9 - Toggle anchor (selection center/object center/other object)

Reference and Screen Guide:

  • G - Toggle Reference Grid On/Off
  • SHIFT+G - Toggle Screen Grid On/Off
  • CTRL+G - Grid Setup

Creation Tools:

  • 1 - Create a camera
  • 2 - Create a light
  • 3 - Create a curve
  • 4 - Create a 3D frame
  • 5 - Create a grid
  • 6 - Create a 2D frame
  • 7 - Create a Material
  • 8 - Create a Texture
  • 9 - Create a Portal

Navigation Tools:

  • Z - Camera zoom
  • SHIFT+Z - Zoom on selection
  • O - Toggle Orbit camera / Orbit target around camera
  • P - Pan camera
  • F - Change camera FOV
  • D - Dolly camera
  • N - Next Camera in scene
  • SHIFT+N - Previous Camera in scene
  • A - Switch to selection mode
  • W - Zoom all
  • Y - Flycam
  • Mouse Middle Button - Pan
  • Alt + Mouse Middle Button - Orbit
  • Mouse Wheel - Zoom

Drag and Drop Operations:
You can assign a building block to an entity by simply dragging it onto the corresponding entity in the 3D Layout. If the entity is a character, you have two choices.

  • Assign the behavior to the character by simply dragging it onto the character
  • Assign it to a bodypart of the character by holding the Ctrl key when dropping the building block.


3D Layout Top Toolbar

  • Snapshot
  • 3D Layout Explorer
  • Selection Groups
  • Select Camera
  • General Preferences


3D Layout Explorer

Overview

The 3D Layout Explorer allows you to see which items you have in the current scene of your composition and to select them. The selection is synchronized between the 3D Layout Explorer and 3D Layout. The selection can also be managed in groups, by using the 'Selection Group' drop down box of the 3D Layout. Note than you cannot change a group if a selection has been locked.

Using the 3D Layout Filter

To open the 3D Layout Explorer, click the Filter icon [image] at the top of 3D Layout window.

On the left side:

Item List:
The main part of the setup is the list of entities currently in the scene. The list is sorted by name, regardless of type.
You can go to any Entity's setup by right clicking on it and selecting "Show Setup" in the menu that appears, or alternatively by double clicking on it. You may only open one setup at a time using this method, although of course you may have multiple setups open at any one time. If you select multiple objects and right-click, the "Show Setup" option is disabled, indicating that it is not possible to go to the Entities' setups.

On the right side:

  • Show in list:
    The check boxes on the right side control the type of entities that are shown on the list. In the image above for example, deselecting the 'Lights' check boxes will remove all lights from the list (but not the scene). You may only deselect a box if no object of this type is currently selected.
  • Selecting items:
    You can select items in the list as you normally would in Windows, using the mouse or arrow cursor keys in conjunction with CTRL or SHIFT. Should you make any changes in another editor, for example deleting a character in Level Manager, the 3D Layout Explorer will automatically update.
  • Lock mode:
    If you have locked [image] one or more Entities in the 3D Layout, "Selection Locked" is displayed in white characters on the right side of the list. In this mode it is not possible to change the selection in the list view, or in the group list.
  • N Entities Selected:
    Indicates how many objects are selected.
  • Text Filter:
    Constraints the listing to entities which name contains the given substring.
  • Selection buttons:
    • All: Selects every object visible in the list, but not in the scene.
    • None: Clears all selections.
    • Invert: Inverts the selection in the list (every object not previously selected is now selected and vice versa).

On the bottom:

  • Select:
    Confirms the selections.
  • Cancel:
    Cancels any selections made since you opened the Explorer (selection, lock or groups).


Select Camera

Select Camera

All cameras, both default and any cameras you have created, are listed in this pull-down menu. You can change the active camera in use by simply selecting one from the menu.

Virtools provides the following camera types by default:

  • Perspective view
  • Top view
  • Front view
  • Right view
  • Orthographic view
An alternative way to change the active camera in 3D Layout is through the context menu.


Selection Group

Selection Groups

Selection Group

Used to create or switch to a selection group.

To create a selection group in 3D Layout:

  • Select objects using the selection tools, then type the name you wish to give this group; pressing ENTER will create the group.

To switch to a selection group in 3D Layout:

  • Recall a selection using the drop down combo box and select an entry. Each object of the selection group will be selected, any objects currently selected will no longer be selected.
  • If a selection made though the 3D Layout (or any other editor) matches a selection group, the selection group is automatically selected in the combo box.


Snapshot

Snapshot:

This tool allows you to capture images of 3D Layout or of a specific part of it. Images can then be dragged onto a script in Schematic or into an object's Setup, allowing you to have a graphical representation of an object.

To use Snapshot, click the button [image] in the 3D Layout top toolbar. The Snapshot Buffer will open, which contains all snapshots previously taken. Right-clicking an image will produce a menu allowing you to:

  • Load Bitmap - replaces the image with one from a file.
  • Save as...- saves the image to file.
  • Delete - deletes the snapshot.

Take:
Adds a snapshot of the 3D Layout view to the Snapshot buffer.

Capture:
Allows you to take a snapshot of a specific area of the 3D Layout.
Click Capture, and a white box will be attached to the mouse. Move the mouse over the 3D Layout and click the left button to take the snapshot.

Close:
Close the Snapshot Box.


3D Layout Transformation Tools

Transformation tools are used to select, and then translate (move), scale (re-size) or change the orientation of one or several objects. Some of these tools can be used with a specific referential point in mind, or using a plane or one axis (out of X, Y and Z). 3D entities as well as 2D entities can be modified in such way.

Available tools are:

  • Selection Tool
  • Select and Translate
  • Select and Rotate
  • Select and Scale

See also Additional settings and flags


Select and Translate

Overview

This tool performs a geometric translation on a given selection. The translation parameters such as direction, coordinate system or constraints are controlled by a set of flags described below in Additional settings and flags.

Use Select and translate

To change the position of an existing selection:

  • Click with the left mouse button on a selected object, then hold down the button.
  • Drag the mouse around to translate the entire selection.
  • Release the left mouse button to end the action.
  • While holding the left mouse button you can cancel the movement by clicking on the right mouse button.
    The position for each selected entity will be restored to their initial value at the beginning of the action.

Add/remove entities to selection, and then change their position:

  • Click with left mouse on a unselected object:
    • The object will replace the selection (if any).
    • The object will be added to the selection if the CTRL key is hold down.
  • Now you can start dragging the mouse around to move the selection, as explained above.
  • If you do not click an entity, you can perform a region selection, as for the Selection Tool.

Direction of Movement and additional flags:

  • Determined by the constrain axis, or the constrain plane (see Axes Constraint)
  • Also determined by the current coordinate system (see Referent Axis)
  • More constraints can be set, using the Toggle Snap.
    When snapping, the object under the mouse may be aligned to another entity, depending on the settings in the Snap Setup.
  • Sub-hierarchy of the objects in the selection can move or not, depending on the state of the Toggle Hierarchy Button, found near the snap button.

General Preferences settings:

  • Under the section 3D Layout - Actions, paragraph Object Transformation, the Translation parameters allow you to switch between two Transformation types:
    • Incremental: clear the Sticky Mode check box, and enter an increment value in world units or local units, relative to the Referential Axis.
      Now, for each mouse movement, the selection position will be incremented by the value set in the General Preferences (see General Preferences for more information).
    • Constrained to the mouse cursor: select the Sticky Mode check box.
      Now, the object under the mouse will strictly follow the mouse movement (and so will the other objects in selection, if any).


Select and Rotate

Overview

This tool performs rotations, in degrees, of given set of 3D objects. Alternately, it can modify the selection before rotating it. The rotation parameters such as speed, coordinate system or constraints are controlled by a set of flags described in Additional settings and flags.

Use Select and Rotate

Change the orientation of an existing selection:

  • Click with the left mouse button on a selected object, then hold down the button.
  • Drag the mouse around to rotate the selected objects (except for the selected 2D entities).
  • Release the left mouse button to end the action.
  • While holding the left mouse button you can cancel the movement by clicking on the right mouse button.
    The orientation for each selected entity will be restored to their initial value at the beginning of the action.

Add/remove entities to selection, and then change their orientation:

  • Click with left mouse on a unselected object:
    • The object will replace the selection (if any).
    • The object will be added to the selection if the CTRL key is hold down.
  • Now you can start dragging the mouse around to rotate the selection, as explained above.
  • If you do not click an entity, you can perform a region selection, as for the Selection Tool.

Rotate constraints and additional flags:

  • Determined by the constraining axis or constraining plane (see Constraining an Axis or Plane)
  • Also determined by the current coordinate system (see Referential Axis)
  • More constraints can be set, using the snap feature. When snapping, the orientation is constrained to angle increments.
  • Sub-hierarchy of the objects in the selection can rotate or not, depending on the state of the Hierarchy button, found near the snap button.

General Preferences settings:

  • Under the section 3D Layout - Actions, paragraph Object Transformation, the Rotation parameter allow you to set the rotation increment (expressed in degrees). Now, for each mouse movement, the selection orientation will be incremented by this rotation value (see General Preferences for more information).


Select and Scale

Overview

This tool changes the local scale of given set of 3D objects. Alternately, it can modify the selection before scaling it.
The scale parameters such as increment, coordinate system or constraints are controlled by a set of flags discussed in the Additional settings and flags.

Three scale modes are available and selectable though the scale icon. To popup the menu, click and hold the left mouse button on the scale icon:

  • Uniform scaling (default) - object(s) are scaled uniformly along the three axes (axes are not used in this mode).
  • Volumetric scaling - Scaling is done keeping the volume of the object always the same.
  • Normal scaling - The objects are scaled along the specified axis (X, Y, Z or double axis).

Use Select and Scale

Change the scale of an existing selection:

  • Click with the left mouse button on a selected object, then hold down the button.
  • Drag the mouse around to scale the selected objects.
  • Release the left mouse button to end the action.
  • While holding the left mouse button you can cancel the action by clicking on the right mouse button.
    The scale for each selected entity will be restored to their initial value at the beginning of the action.

Add/remove entities to selection, and then change their scaling:

  • Click with left mouse on a unselected object:
    • The object will replace the selection (if any).
    • The object will be added to the selection if the Ctrl key is hold down.
  • Now you can start dragging the mouse around to scale the selection, as explained above.
  • If you don't click an entity, you can perform a region selection, like for the Selection Tool.

Scale constraints and additional flags:

  • For Normal and Volumetric Scaling, the axis constraint is determined by the constrain axis, or the constrain axes (see Axes Constraint).
    For Uniform Scaling the constrain axis is set to X, Y, Z.
  • More constraints can be set, using the snap feature. When snapping, the scaling is constrained to percentage increments.
  • Sub-hierarchy of the objects in the selection can be scaled or not, depending on the state of the Hierarchy button, found near the snap button.

General Preferences settings:

  • Under the section 3D Layout - Actions, paragraph Object Transformation, the Scaling parameter allow you to set the scale increment (expressed in local units). Now, for each mouse movement, the selection scale will be incremented by this scale value. (see General Preferences for more information)


Selection Tool

Overview

This tool is used to select 2D or 3D entities, in order to perform certain actions on the selection, such as basic geometric transformations (translate, scale, orientate) or any other editor-specific operations. Two modes are available: selecting/deselecting single entities or multiple selection.

Use Selection Tool

To select an entity:

  • Click the Select button.
  • Point to the entity you want to select.
  • The cursor changes to the select cursor, indicating that you can select the entity.
  • click the entity to select.
  • Clicking on a entity which is already selected, will deselect it.
  • Clicking on another object with CTRL pressed will add it to the current selection. If the entity is already selected, it is then deselected.

Selection by region:

Selection by region is used to select all the entities contained within a rectangular zone.
If you need to select entities that are strictly inside the rectangle you can use the Selection Mode button on the top of the Left Toolbar:

  • If [image] is picked only entities contained within the rectangular are selected.
  • If [image] is picked entities which intersect the rectangle are also included in the selection.

To select several entities:

  • Click the Select button.
  • In the 3D Layout, point to the upper-left hand corner of the zone you want to select.
  • Hold down the left mouse button and drag the pointer over the a region until the rectangular zone in the 3D Layout includes all desired entities.
    Entities that lay within the rectangle will be selected.
  • Clicking on nothing will clear the selection.
  • If you hold down CTRL key before starting the region selection, the new selection will be added to the existing one.

Special Actions for 2D Sprites:

A selected 2D Entity/2D Sprite provides a useful way to be moved or scaled, by using the special controls:

  • To move the sprite:
    • Click and hold the left mouse button on the top-left box.
    • Drag the mouse around to translate the sprite.
    • Release the left mouse button to confirm the new position.
    • While holding the left mouse, press the right mouse button to cancel the action and to set the sprite to its initial position.
  • To scale the sprite:
    • Click and hold the left mouse button on one of the resize boxes (on the bottom-right, on the middle-right and on the middle-bottom).
    • Drag the mouse around to scale the sprite (the scaling may be constrained to one axis only, depending on the box you clicked on).
    • Release the left mouse button to confirm the new size.
    • While holding the left mouse, press the right mouse button to cancel the action and to set the sprite to its initial size.

Useful Shortcuts:

  • A - Toggles the selection tool On/Off
  • CTRL+A - Selects all objects in the scene
  • CTRL+D - Deselects the objects
  • CTRL+I - Inverts selection


Additional Settings for Transformation Tools

This is the list of flags used by the Transformation Tools (used to translate, scale or orientate an object).

The Lock Selection and Selection Mode icons are visible at all times, whereas the other icons appear only when you have selected a transformation tool.

Right-clicking an icon will open the relevant part of the General Preferences allowing you to adjust its settings.

Selection Flags:

  • Lock Selection
  • Selection Mode

Transformation Flags:

  • Constraining an Axis or Plane
  • Referential Axis
  • Toggle Snap
  • Toggle Hierarchy
  • Pivot Axis


Constraining an Axis or Plane

Overview

An Axis or Plane (formed by two axes) must be selected for all transformations. This is used to specify the axis or plane used when performing the transformation.

Only one axis button is active at a time. When a button is active, transformations are limited to this axis. The first three buttons (X,Y,Z) limit the transformation to one axis. The fourth button is a pop-up button and limits the transformation to combinations of two axes: XY, YZ, XZ.

Constraints

To constrain to a single axis:
  • Click the button corresponding to the axis you want to constrain / unconstrain.
  • You can also use the keyboard shortcuts to change quickly the axis:
    • F5 - X axis
    • F6 - Y axis
    • F7 - Z axis

To constrain to a plane:

  • click the icon to set the Constrain Plane.
  • Click and hold down the mouse button over the icon to popup more Constrain Planes. Release the button over the desired constraint.
  • Use the F8 keyboard shortcut to change quickly the constraint.

Warning! In some specific situations only a few axes are selectable. For example, when the current camera is set to the Top View, only X and Z axis are available for Select and Translate.


Lock Selection

You can lock an existing selection in order to perform specific actions, like moving or scaling objects.

As well the lock icon appearing closed, there is is a thin green border around the preview pane of 3D Layout showing this mode to be active.

When in lock mode, you cannot select any other objects (i.e. the selection tool is inactive). To activate the lock mode, click the icon or press the SPACEBAR (be sure to have the 3D Layout be the current active window, otherwise the SPACEBAR action won't result in lock). You cannot use this mode if nothing is selected.

Warning! While the Lock mode is active, the selection in 3d Layout cannot be modified from any other editor.


Pivot Axis

The pivot axis is a referential which the action refers to (i.e. for example, an object rotating around itself or rotating around the another object will not produce the same effect).

Three pivot axis modes are available, and can be used while in the scale or the rotate tool:

  • Local:
    The referent axis is object's own axis.
  • Selection Center:
    The referent axis is the barycenter of the selection.
  • Object:
    The referent axis is another object. If the referent object is in the selection, it won't rotate or scale.

For the Selection Center and the Object modes, the objects may also move (i.e. translate).


Referential Axis

The reference point or referential is used as a reference for a transformation (a translation, scale or orientation). You can select the reference point in the reference box.

The following reference points are available:

  • Local: Using entity's axes.
  • World: Using world axes (always static, never moves, rotates or scales).
  • View: Relative to the position of the current camera axis.
  • Parent: Relative to the position of the parent entity (if any, world axis otherwise).
  • Reference Guide: Relative to the reference guide.


Selection Mode

This mode is a state icon used by the Selection Tool in region mode to decide if it must include the objects that intersect the selected region.

Objects that are wholly inside the region are always selected.


Toggle Hierarchy

The hierarchy flag determines if a transformation applied to an object should apply to an object's children. For example, if the hierarchy flag is activated, moving an object with multiple children attached to it will move its children as well.


Toggle Snap

Overview

Snap Mode allows you to 'snap' an object onto another in the 3D Layout when performing a transformation.

When the object being transformed comes within a certain proximity of the other object, it will jump or 'snap' into place. The type of 'snap' depends on the transformation tool used for the transformation and whether the object is 2D or 3D. The distance at which an object will snap is set in the 3D Layout - Snap & Align section of the General Preferences.

Use Toggle Snap

Right-click the snap icon opens the 3D Layout - Snap & Align section of the General Preferences that sets the snap mode.


Creation Tools

Creation tools are used to create the following objects:

  • Cameras
  • Lights
  • 3D Frames
  • Curves
  • Grids
  • 2D Frames
  • Materials
  • Textures
  • Portals

Whenever you create one of these objects, its Setup is created and opens in the lower half of the screen.
You can turn off this option by clearing Automatic Show Setup in the General Preferences.
If you close an object's setup, you can re-open it by right-clicking it in the 3D Layout or in Level Manager and selecting Show Setup.
More information on Setups and parameter settings.


Create 2D Frame

Overview

A 2D frame is similar to a 2D Sprite except that it has no image attached to it, it is just a position and size. However a 2D Frame may have a material and texture attached to it. 2D Frames, even with materials and textures, are a lot quicker to render than 2D sprites.

Create 2D Frame

To create a 2D frame:

Click the Create 2D Frame icon. The new frame is created in the middle of the screen with a default size.
Frames can be moved and re-sized using the transformation tools, or the special controls available only when the frame is selected.

These settings can also be modified by using the 2D Frame Setup.


Create 3D Frame

Overview

A frame is a plain 3D entity without any geometry attached to it, having just an axis with a position, orientation and scale.

Create 3D Frame

To create a 3D frame:

Click the Create 3D Frame icon. The new frame is placed in front of the current viewpoint. Frames can be moved, rotated and scaled using the transformation tools. These settings can also be modified by using the 3D Frame Setup.


Create Camera

Overview

A camera can be created to visualize the scene from a particular viewpoint. A Virtools camera behaves in the same way as a video camera. Two types of cameras are available: targeted or free. If is targeting, it will always track its target, that is, it will always face the target. Free cameras, or cameras without target, can be freely rotated by the user.

Create Camera

To create a camera:

  • Click the Create Camera icon.
    You can choose the type of camera, and whether it is targeting in the Camera Setup.
  • The new camera will replace the previous one, by copying all its parameters (position, orientation, FOV, etc.).
    These parameters can be changed in the Camera Setup; certain camera parameters can be set using building blocks.

To change the active view, see the section "Select Active View". The camera can be moved using the navigation tools described in the next section.


Create Curve

Overview

3D curves can be created directly in the 3D Layout. A curve can be attached to any 3D entity and used as a path for the entity to follow.

Create Curve

To create a curve:

  • Click the Create Curve icon. A new curve is created (a Curve Setup appears) but the curve is not visible because it does not contain any points.
  • To add points and change the properties of the curve, use the Curve Setup.


Create Grid

Overview

The grid manager system provides an easy way to control 3D issues in 2D planes.

Create Grid

To create a grid:

Click the Create Grid icon. The new grid is placed on the default XZ plane.
There are actually two setups for grids:

  • the first Grid Setup which opens automatically, allows you to create layers and associate values to them.
  • The second setup, which you can open by right-clicking a grid in Level Manager and selecting Show Setup allows you to set its physical parameters (position, orientation, scale and world size).


Create Light

Overview

A light can be created to illuminate a scene or specified objects. Several types of lights are available:

  • Point: Only position and an orientation
  • Spot: A position and a target
  • Directional: Only an orientation vector.
  • Parallel: A position from which a lighting vector will be computed for each object (not for each vertices).

Create Light

To create a light:

Click the Create Light icon. A new light is placed in front of the current viewpoint.
The light can be moved/oriented using the transformation tools.
A light's parameters can be edited in the Light Setup; certain parameters can be set using building blocks.


Create Material

Overview

A material holds the surface description for faces or for 3D Sprites. Materials can be shared by multiple faces or sprites.
See the Material Setup for more information.

Create Material

To create a Material:

Click the Create Material icon.
Other settings can be modified by using the Material Setup


Create Portal

Overview

Portals are used, along with places, as a system to improve the rendering of big scenes, which is done by avoiding unnecessary calculations.
See the Portal Setup for more information.

Create Portal

To create a portal:

  • Click the Create Portal icon. The portal is created in front of the current viewpoint, and its representation is a semi-transparent box.
  • An alternate method is to select a given object before creating the portal.
    This way, the portal will be created using the object's position, orientation and size.

    • Portals are colored blue when activate, and red when inactive. You can use the Level Manager to toggle the current state.
    Other settings can be modified by using the Portal Setup.


Create Texture

Overview

Textures are used to render images within material applied to 3D Objects. Though a texture is mostly used within materials, it is sometimes useful (for some building blocks) to be able to create a texture from scratch.
See the Texture Setup for more information.

Create Texture

To create a Texture:

Click the create Texture icon.
Other settings can be modified by using the Texture Setup.


3D Layout Navigation Tools

The following tools can be used to navigate in 3D view:

  • Camera Dolly
  • Camera FOV
  • Camera Zoom
  • Camera Roll
  • Camera Pan
  • Orbit Camera / Orbit Around Object / Orbit Around Camera
  • Flycam

Most of these actions can be canceled by clicking the right mouse button while holding left one. (Ex. while dragging the left button in orbit mode and you became aware that you didn't really wanted to move the camera that way, pressing the right button will move the camera to its old position before you started the action)
Set the navigation tools in the 3D Layout-Action part of the General Preferences.
See also the Keyboard Shortcuts.


Camera Dolly

Moves the camera and its target (if any) incrementally along the Z axis of the camera. (keyboard shortcut is D)

Set the Camera Dolly in the 3D Layout-Action part of the General Preferences.


Camera Field of View

Overview

The camera Field of view tool represents the angle cone seen by the camera.

Camera Field Of View

To change the field of view:

  • Click the Field of view button (or use the keyboard shortcut F).
  • In the 3D view, drag the pointer to the top or to the bottom of the view to change the value of the current field of view.

The field of view can also be changed in the Camera Setup by editing the value in degrees or by changing the focal length in millimeters.
The positions of the camera and its target remain unchanged.

Set the Camera FOV in the 3D Layout-Action part of the General Preferences.


Camera Pan

Overview

Moves the camera and its target on the cameras XY (view) plane.

Camera Pan

To pan the camera:

  • Click the Pan button. (Or use the keyboard shortcut P)
  • Drag the mouse in the 3D view to move the entity and camera in the view plane.

or

  • press mouse middle button and move the mouse the same way. Navigation with mouse middle button is disabled when the orbit button or the pan button is pushed.

Set the Camera Pan in the 3D Layout-Action part of the General Preferences.

Note

When the camera is far from the world center (0,0,0), press shift to pan faster.
For instance, if there is a cube at (0,0,0), when panning with shift pressed, the cube will move at the same speed whatever its distance to the camera.


Camera Roll

Overview

Rotates the camera around its Z axis.

Camera Roll

To roll the camera:

  • Click the Roll button. (Or use the keyboard shortcut R)
  • Drag the mouse around the screen to rotate the camera.

Note: This tool is available only for cameras without target (and the perspective view has a target).
Set the Camera Roll in the 3D Layout-Action part of the General Preferences.


Camera Zoom

Overview

The Zoom tool is used to move the camera towards or away its target.
The target remains fixed and does not move.
Three options available:

  • Zoom: (default) Behaves like Dolly camera but only the camera is moving, not the target. (keyboard shortcut is Z)
  • Zoom on Selection: Automatically zooms in on an entity or a group of entities. (keyboard shortcut is Shift+Z), and set camera target position to the center of the selection.
  • Zoom on Scene: Automatically zooms in order to make all the objects visible in the 3D layout. (keyboard shortcut is W)

Camera Zoom

To zoom the camera:

  • Click the chosen Zoom button.
  • In the 3D View, drag the mouse - Up to zoom in - Down to zoom out

or

  • use mouse wheel to zoom in or out.

Note : to change the target position, select objects and press [image] button to zoom the selection (Keyboard shortcut Shift+Z)

Set the Camera Zoom in the 3D Layout-Action part of the General Preferences.


Flycam

Overview

The Flycam is a special action type, which can be used for a fast navigation within the level or a scene.
It provides several camera functions in one camera; consequently the Flycam can take some practice to use efficiently..

Use the Flycam

To activate this mode, use the keyboard shortcut Y.

You cannot activate the Flycam during Play mode. To use the Flycam during Play mode:

1. activate the Flycam in Author Mode.
2. go in Play mode by pressing CTRL+SPACEBAR

Dolly/Rotate:

Once you have activated the Flycam the default action is Dolly / Orbit.
This provides a motion similar to the 'walk' found in Quake-like games.
The controls are as follows:

  • Move the mouse on Y axis to translate the camera and its target (if any) along the camera's Z axis.
  • Move the mouse on X axis to rotate the camera around the world's Y axis.

Orbit:

  • Click and hold the left mouse button to activate the Orbit action (similar to the Orbit Around Camera action).
  • Drag the mouse around to rotate the target around the camera.
  • Releasing the button will fall back to the default Dolly/Orbit action.

Orbit Around Object:

  • click a object with both mouse buttons to activate the Orbit Around Object action.
  • Drag the mouse around to rotate the camera and its target around the selected object.
  • Releasing the button will fall back to the default Dolly/Orbit action.

Pan:

  • Click and hold the right mouse button to activate the Pan action.
    This is similar to the Pan action except for the translation plane, which is world's Y axis and camera's X axis.
  • Drag the mouse to translate the camera and the target around the translation plane.
  • Releasing the button will fall back to the default Dolly / Rotate Rotate action.

Set the Fly Cam in the 3D Layout-Action part of the General Preferences.


Orbit

Overview

The Orbit tool is used to make the camera orbit around its target. The target remains in the same position.
Two states available:

  • Orbit/Orbit around Object:(default) Moves the camera around its target, keeping the distance always constant. Orbit Around Object moves the camera around the selection's center and is available when the selection contains 3D Entities.

  • Orbit Around Camera: Moves the target around the camera, keeping the distance between them constant.

Orbit

To make the camera orbit around its target:

  • Click the Orbit button. (Or use the keyboard shortcut O)
  • In the 3D view, drag the pointer in the direction you want it to rotate.

or

  • Keep the Alt key pushed then press mouse middle button and move the mouse the same way. Navigation with mouse middle button is disabled when the orbit button or the pan button is pushed.

Note : to change the target position, select objects and press [image] button to zoom the selection (Keyboard shortcut Shift+Z)

Set the Orbit tool in the 3D Layout-Action part of the General Preferences.


Level Manager

Click an area below [image] for help on a specific element. Position the mouse pointer over an area to see a short description of that element.

Creation Tools Level and Scenes Toggle Show/Hide Expand/Collapse Selected Set Initial Conditions for Selected Show/Hide Layer Name Column Initial Conditions Visible Column Activate at Scene Start Column Reset at Start Column Active Now Column Priority Column

The Level Manager displays the content of the composition by CK Class and is used to manage the composition. A composition contains a level section and may contain several scene sections.

  • Using Level Manager
  • Level Manager Shortcut Menus
  • Level Manager Keyboard Shortcuts


Level Manager Keyboard Shortcuts

NAVIGATION:

  • UP,DOWN, PAGE UP, PAGE DOWN, HOME, END - Scroll functions
  • RIGHT - Open hierarchy of selected item if available
  • LEFT - Close hierarchy of selected item if hierarchy is opened, otherwise select parent item.
CREATION TOOLS:
  • P - Create a new Place and adds selected 3D Entities to the place.
  • R - Create a new Array.
  • C - Create a new Scene.
  • W - Create a new Workset.
  • S - Create a new Script on selected items.
  • G - Creates a group and adds selected items to the group.

FIND:

  • F - Opens the Find dialog box
  • F3 - Find Next.
  • Shift+F3- Find Previous.
  • Ctrl+F3 - Find Next that contains the string/text currently selected.
  • Ctrl+Shift+F3- Find Previous that contains the string/text currently selected.

SELECTION:

  • F2 - Renames entities.
  • DEL - Deletes selected entities.
  • SPACEBAR - Toggles selection lock in 3D view.
  • V - Show selected 2D/3D entities.
  • H - Hide selected 2D/3D entities.
  • A - Activate selected entities in their context scene.
  • D - Deactivate selected entities in their context scene.
  • 1 - Set Show/Hide Flags on selected items.
  • 2 - Remove Show/Hide Flags on selected items.
  • + - Moves the entity up in the group order.
  • - - Moves the entity down in the group order.
  • RETURN or Middle button on a script - Show in Schematic.
  • RETURN or Middle button on a entity - Show Setup.
  • CTRL+A - Selects all children of the selected item.
  • CTRL+C - Copies the selection to the clipboard.
  • CTRL+V - Pastes the clipboard content on the selection.
  • Alt+S- Saves the current selection to an object file.


Level Manager Shortcut Menus

Overview

The shortcut menu that appears when right-clicking in Level Manager Name Column depends on the context - there are different menus for folders, scripts, entities and multiple selections.

Folders

Select Children:
Selects all the components of the folder.

Scripts

Show In Schematic:
Opens the Schematic editor and displays the script.

Rename:
Allows you to rename the script.

Save as... :
Opens the Save dialog box allowing you to save the script as a .nms, with the option to protect your work by selecting the option Hide script representation in Schematic view.

Delete:
Deletes the script.

Set / Restore / Remove Initial Conditions:
Memorizes the state of the script / Returns a script to its initial conditions / Deletes a script's initial conditions.

Single Selection only

Show Set Up:
Opens the 3D entity's set up window.

Load Script:
Loads a script previously saved in the .nms file format.

Rename:
Allows you to rename the entity.

Single or Multiple selection

Set / Restore / Remove Initial Condition:
Memorizes the state of the selected entities / Returns selected entities to their initial conditions / Deletes selected scripts' initial conditions.

Add Attributes:
Opens the Attribute Dialog Box for selected entities.

Send to Scene:
Creates a reference of selected entities in the chosen scene.

Save as...:
Opens the Save dialog box allowing you to save selected entities as a .nmo, with the option to protect your work by selecting the option Hide script representation in Schematic view.

Delete:
Deletes selected entities.

Save Objects as...:
Appears only if a Scene or the Level is selected Saves the level or scene object in Virtools object file format, all object referenced in the Level will saved except the Level itself.

Create Group:
Creates a group an adds the current selection to the group.

Create Place:
Creates a place an adds the 3d entities in the current selection to the place.

Send to Place:
Send the selected 3d entities to a place.

Send to Scene:
Adds the current selection objects to the scene. The object's dependencies will also be added to the scene.

One Object In a Group

Move Up:
Moves the entity up in the group object list.

Move Down:
Moves the entity down in the group object list.

Object In a Place

Remove From Place:
Removes the entity from the place and moves it to the Global.

On a Workset

Create Workset:
Creates a new child workset of the selected workset.

Show/Hide Workset Scripts in Schematic:
Shows/Hides scripts in Schematic for selected items.


Using Level Manager

Moving and Copying in Level Manager

Moving and copying in Virtools is very simple - simply drag the element to move it, and hold down the SHIFT key to copy the element. The effect of dragging components depends on the type of component: 3D entity, Group, Place, Script.

Scripts:

  • Move:
    Moves the script to the drop target entity if compatible.
  • Copy - with SHIFT key pressed:
    • Copies the script to the drop target entity if compatible.

Objects:

  • Move:
    • On the Level - If the entity was in a place it is moved back to Global, no effect otherwise.
    • On a Place - 3D Entity is moved the place and is no longer referenced in Global.
    • On a Scene - BeObject is added to the scene.
    • On a group - BeObject is added to the target group.
    • On a Workset - Script or Objects are added to the workset.
  • Copy (move with the SHIFT key pressed) (a dialog box, shown below will open):
    • On the Level - a copy of each selected item is created and added to the level.
    • On a Place - a copy of each selected item is created and added to the place.
    • On a Scene - a copy of each selected item is created and added to the level in the Global section and added to the scene.
    • On a Group - a copy of each selected item is created and added to the target group.

    Like this, you can choose if you want to copy or not the associated elements too:

    • No Dependencies:
      Only the selected object is copied, none of its dependencies will be duplicated. For example, copying a mesh with this option will not copy its materials
    • Full Dependencies:
      All Dependencies of the selected object will be copied. For example copying a 3D Object will copy its meshes, for each mesh it will copy its material and for each material, its textures
    • Custom Dependencies:
      Lets you choose which dependencies you want to copy, on a per class basis.

Dragging components from a resources database

Building Block or Behavior graph from a Behavior resource:

  • On an Entity or a multiple selection of Entities:
    • If it's a Building Block or a Behavior graph it is added to the first entity script.
    • If it does not have a script a new script is created.
    • If it's not compatible and the Building Block is targetable, it will be added using target mode.
    • If it is a whole script the script is loaded and added to the entity if it is compatible.
  • On a Script:
    If it is a Building Block or Behavior it will be loaded and added to the script if it's compatible, if not and the Building Block is targetable, it will be added using target mode.

Entity or media (character, sound for example) from a Data resource:

  • On the Level
    The data is loaded and added to Global selection
  • On the Place
    Data is loaded and added to the Place.
  • On a Scene
    Data is loaded, added to level in Global section and added to the target scene.
  • On a Group
    Data is loaded, added to level in Global section and added to the target group.
  • On other entities
    The load mode will be defined by the entity containing the drop target entity.
    In this context, if you drag an animation onto a character, the animation will be added to the character's list of animations if the animation is compatible (if the character has the required body parts for example).
    If you drag an animation onto a 3D Entity, it will be added to the entity's list of animations.

You cannot drag components from the Level Manager Editor to another Virtools editor.
The Level Manager is automatically updated when 3D entities or places are dragged into a scene.
Nevertheless, you can also drag 3D entities directly into the level.

Miscellaneous

Copy / Paste:
Is contextual in Level Manager, i.e. the target of the paste operation defines its meaning.

  • Pasting Scripts on items creates a copy of these scripts and adds them to the selected items.
  • Pasting Entities on a place moves them to the place.
  • Pasting Entities to a scene makes them participate in the scene.

Mouse clicks:

  • Double Click:
    • If the item has no child, its Setup will be opened.
    • If it has children, it expands the item.
    • If the item is a script, Schematic will be opened with a focus on the script.
  • Left Click:
    • On an item selects it. (Add mode toggle using Control or Shift keys like in Windows)
    • On a column:
      • Layer Column:
        Toggle Hide layer On/Off.
      • IC Column:
        No effect only indicates the presence of Initial Conditions on the item.
      • Visible Column:
        Toggles the visibility in 3D View for any entity derived from 3D entity and 2D Entity.
      • Activate At Scene Start Column:
        Toggles entities activity when the scene starts
      • Reset At Scene Start Column:
        Specifies if Objects or scripts Initial conditions must be reset when the scene starts
      • Active Now Column:
        Reflects the objects current activation state
      • Priority Column:
        Sets entity/script behavioral priority

Right Click:

Displays contextual menu.

Middle Click:

  • Shows entity Setup if applicable.
  • Shows Script in Schematic if applicable.


Level Manager Columns

  • Show/Hide Layer Column
  • Name Column
  • IC Column
  • Visible Column
  • Activate at Scene Start Column
  • Reset at Scene Start Column
  • Active Now Column
  • Priority Column


Level Manager Activation at Scene Start Column

Level Manager Activate at Scene Start Column

Activating and Deactivating Scripts

In Level Manager you can enable or disable an object or a script at two different moments, at scene start and now by using the the following activation flags:

  • script active:
    If you set the activation flag to active on an item of the Level Manager (like 3D object, character, texture, etch), the state its scripts is not modified.
  • script inactive:
    If you set the activation flag to inactive on an item of the Level Manager (like 3D object, character, texture, etc.), all its scripts become inactive.
  • Nothing:
    Leaves the Object or Script in its current state, i.e. active or inactive.
To switch between states, click the icon.


Level Manager Active Now Column

Activating and Deactivating Scripts

This column reflects the current activation state of the object or script. In Level Manager you can enable or disable an object or a script, by setting the the following activation flags:

  • Object/Script active:
    If you set the activation flag to active on an item of the Level Manager (like 3D object, character, texture, etch), it enables the processing of its active scripts (but it does not change the scripts activation settings)
  • Object/Script inactive:
    If you set the activation flag to inactive on an item of the Level Manager (like 3D object, character, texture, etc.). Setting an object as inactive, disables the processing of all its scripts (but it does not change the scripts activation settings).
To switch between states, click the icon.


Level Manager Name Column

Overview

Level Manager is a view of all object in the Level and of all Scenes. Is allows to create narrative elements such as Scene, Place or Scripts scenes and to set entities scene related settings.

A shortcut menu appears when right-clicking in Level Manager Name Column depending on the context.

Level Section

Level Scripts:
Abstract entity that manages scripts available on the entire level (i.e. environment settings, logical tests).

Global :
Contains objects which will be used in various scenes. Categorized into the folders below. Each folder can have associated sub-folders:

  • 2D Sprites
  • 2D Frames
  • 3D Frames
  • 3D Sprites
  • 3D Object
  • Arrays
  • Cameras
  • Characters
    • Animations (note that animations can be saved via shortcut menu)
    • Body Parts
  • Curves
  • Global Animations (note that animations can be saved via shortcut menu)
  • Grids
  • Groups
  • Lights
  • Materials
  • Meshes
  • Portals
  • Sounds
  • Textures

Places :
Contains a list of places. See also Place Setup.

Worksets:
Allows you to make logical selection of objects or scripts. By right clicking on workset in the Level Manager, you can Show/Hide these elements in the Schematic. A workset is an user interface only item.
See also Level Setup.

Scene Section

Level Scripts:
Abstract entity that manages Level scripts activation in a particular scene.

Scene Scripts:
Abstract entity that manages scene scripts list and settings.

Entities:
Entity contains references to the objects of referenced in the scene.

Places:
A list of references to places referenced in the scene.

Worksets:
Allows you to make logical selection of objects or scripts. By right clicking on workset in the Level Manager, you can Show/Hide these elements in the Schematic.

See also Scene Setup.

Sorting Level Manager Name Column

To sort the Level Manager folders by name (alphabetical order), click the name column header.


Level Manager Priority Column

Setting a Priority

The behaviors loop parses the objects according to their priority.
For each object, scripts are executed according to their priority.
To change the priority order of an object or a script, double click the priority number to enter a new value.

Sorting Level Manager by Priority

To sort the Level Manager by priority, click the the priority column.


Level Manager Reset at Scene Start Column

Resetting at Scene Start

In Level Manager you can specify if an object must be reset to its initial conditions when the Scene or the Level starts, using the the following reset flags:

  • Reset:
    The object will be set back to its initial conditions when the scene starts, these flags are used in conjunction with the Initial Condition.
  • Don't Reset:
    The object will keep its current state when the scene starts.
To switch between states, click the icon.


Level Manager Visible Column

Hiding/Showing objects in a scene (i.e. in 3D Layout)

The following two icons show whether an object is hidden or visible in a scene:

visible/ [image] hidden / [image] Hierarchical hide To switch between states, click the icon.
If you click an icon of an object contained in a multi-selection, all the visibility flags will be modified, taking the state of manipulated flag.
An object in Hierarchical Hide state is not visible (as a hidden object) but all its hierarchy will be hidden as well. If an object is hidden due to its parent state, its icon will be slightly grayed.
visible , hidden by its parent/
hidden , hidden by its parent/
Hierarchical hide , hidden by its parent


Level Manager Side Left Toolbar

  • Creation Tools
  • Level and Scenes


Level and Scenes in Level Manager Left Side Toolbar

: Click the Level button to set the behavioral context to Level mode.

: Click the Scene button to set the behavioral context to scene mode, the current scene is specified using the list box below.

Up Arrow: Selects the previous scene.

Scene List box: Clicking an item in list box will set Virtools to scene mode, using the selected scene as current scene.

Down Arrow: Selects the next scene.


Level Manager Creation Tools

Level Manager Creation Tools are used to create a group, array, scene, place, script, or workset.
By default, the name of a the object newly created is "new object".
To rename the object, select it and press F2 or right-click and choose Rename in the menu that appears.

Create New Place:
Creates a new place in the Place folder of Level Manager. See also Place Setup.

Create New Groups:
Creates a new empty group folder in Global folder of Level Manager. See also Group Setup.

Create New Array:
Creates a new array in Global folder of Level Manager. For information on arrays, please see Array Setup.

Create New Scene:
Creates a new scene in Level Manager. See also Scene Setup.

Create New Workset:
Creates a new workset or sub-workset in the workset folder of Level Manager.

Create New Script:
Creates a new script for the selected object in Level Manager.

Only Behavioral Objects (BeObject) may have scripts. The script is created in Schematic but is referenced in Level Manager.
To edit the script in Schematic, double-click the script, choose Show in Schematic from the right-click menu or select one script and hit Return.


Level Manager Top Toolbar

  • Toggle Show/Hide
  • Expand/Collapse Selected
  • Set IC for Selected


Expand/Collapse Selected

Expand button:
Expands the selected branch.

Collapse button:
Collapses the selected branch.


Initial Conditions (IC) the in Level Manager

Initial Conditions (IC) in the Level Manager

See the Initial Conditions page for information on Initial Conditions (IC). Besides being able to set IC for an element with [image], you can also set, remove or restore IC using the context menu. The IC Column of the Level Manager allows you to see at a glance which elements have IC:

: There are no Initial Conditions for the element.
: Initial Conditions have been saved for the element.


Show / Hide Layer

Hiding/showing objects in Level Manager

In order to organize the visualization of your composition in the level view , you can choose to show or hide some entities. Use the flag hidden/visible to switch between the mode hide/show.

How / Hide Layer Column

hidden / [image] visible:
To switch between states, click the icon.

How / Hide Layer Top Toolbar Button

Hide Layer button
Toggles hide layer on/off. When this mode is on every item with the hide layer flag set will be hidden.


Schematic

The Schematic is used to view, edit and debug scripts. A script is simply a visual representation of a behavior attached to a (behaviorial) object. A script has two parts - a header to the left that displays the name of the script, the script owner and other usefull information, and a script body that describes the behavioral interactivity with BBs, BGs, links and so on.

Click an area below [image] or on a toolbar icon for help on a specific element. Position the mouse pointer over an area to see a short description of that element.

Start Behavior Building Block (BB) Parameter Input (pIn) Behavior Input (bIn) Parameter Output (pIn) Behavior Output (bOut) Parameter Link (pLink) Parameter Link (pLink) Parameter Link (pLink) Parameter Operation (paramOp) Parameter Shortcut <This> Parameter Local Parameter Targetable Behavior Link Comment Behavior Graph (BG) Expand/Collapse Selected Scripts Schematic Explorer Link Mode Showing and Hiding Scripts Show/Hide Local Parameters Show/Hide Script Script Headers Show/Hide Control Points Show/Hide Link Informations title= Behavior Link Properties Show/Hide Priorities Reset Schematic Zoom and Position Zoom Mode Script Debugger Trace Mode Links with Errors Explorer Message Explorer Script Header Closed Script - Click here for Help on Script Find (Ctrl + F) Obsolete or Invalid Building Block Explorer

See also: Schematic Keyboard Shortcuts


Schematic Keyboard Shortcuts

NAVIGATION:

  • ARROW KEYS, PAGE UP, DOWN, HOME, END (when no script is selected) - Scroll functions
  • PLUS, MINUS (+, -) - Zoom in, Zoom out (3 predefined levels)
  • R - Zoom out and scroll to first page
  • SHIFT+R - Refresh schematic
  • SHIFT+Up/Down keys - If a script is selected, select previous / next script and scroll
  • CTRL+Up/Down keys (when no script is selected) - Page scroll
  • CTRL+Up/Down keys ( when a script is selected) - Move highlighted script
  • Right/Left keys (when only scripts are selected) - Open/close selected scripts
  • CTRL+B - Select/deselect highlighted script
  • SPACEBAR - Force mouse scroll (even if mouse is on a moveable item)

SELECTION:
  • CTRL+X - Cut selection to clipboard. Scripts cannot be cut.
  • CTRL+C - Copy selection to clipboard
  • CTRL+V - Paste from clipboard
  • Fast Copy and Paste - There is another fast way to copy and paste a selection: press Shift before moving the selection by dragging it.
  • CTRL+SHIFT+V - Paste shortcut (only if output/local/shortcut parameters has been previously copied)
  • DELETE - Delete selection
  • SHIFT + DELETE - Delete behavior graph but keeps its content
  • CTRL+click and drag mouse - Rectangle selection (selects everything that is strictly inside [schematic preference - strict multi-selection active] otherwise everything that intersects the drawn rectangle.)
  • Hold SHIFT down to add items to current selection by clicking on them.
  • Hold CONTROL down to invert selected state of clicked items.
  • SHIFT+Move Selection - copy moved selection
  • CONTROL+Move Selection - invert Search Best Path while Linking preference
  • SHIFT+Q - Set Initial Conditions on selected scripts
  • CTRL+Q - Remove Initial Conditions on selected scripts
  • ALT+Q - Restore Initial Conditions on selected scripts
  • SPACEBAR
     - Change display of selected local parameters
    - Open/close selected behavior graphsand scripts
  • F1 - Open building block help if building block is selected and doc is available
  • F2 - Edit name or comment box. Return or click elsewhere to accept new name, press escape to cancel
  • F9 - Add/remove breakpoint
  • Shift+F9 - Configure breakpoint
  • E or RETURN - Edit selected item's Parameters (behavior, parameter operation, link)
  • K- Opens CK Properties dialog to analyse the currently selected parameter input/output/local.
  • M - Modify selected Parameter Operation
  • P - Update path of selected links and links connected to selected items. Switch between direct path (no control points) and best path
  • S - Edit Settings of selected building block if available
  • Shift+S - Save selection
  • T - Add / remove Target Parameter to selected Building Blocks
  • V - Opens / shows Vsl Script Manager and edit selected Run Vsl building block script.
  • X - Execute selected scripts
  • Y - Edit selected behaviors priority

MODES:

  • G - Create graph mode
  • L - Create link mode
  • ESC or right-click or L - End link mode if in link mode

BEHAVIOR BB/BG CONSTRUCTION:
  • C - Creates a comment (graph and script only)
  • I - Creates an input for selected
  • O - Creates an output for selected
  • ALT+I - Creates an Parameter Input for selected
  • ALT+O - Creates an Parameter Output for selected
  • ALT+L - Creates a local parameter for selected / in script
  • ALT+T - Creates a This parameter for selected / in script

MOUSE SHORTCUTS:
  • Double-Click Link - Open Edit Link Delay dialog box
  • Double-click Script Name - Open/close script
  • Double-click Scrip Owner - Open Level Manager with owner selected
  • Double-click Graph - Open/close graph
  • Double-click Building Block- Edit building block parameters
  • Double-click Input/Parameter Output - Edit that parameter only
  • Double-click Local Parameter - Edit local parameter
  • SHIFT+Right-Click - show menu with 10 most recently used building blocks
  • Middle button - show menu with building block categories
  • Drag&Drop input/output or parameter input/output- link
  • Shift + Drag&Drop input/output or parameter input/output- export and/or move if moved object is a parameter that belong to a graph.
  • Alt + Drag&Drop input/output or parameter input/output- change connected link source/destination
  • Drag&Drop linked parameter local outside graph- export local parameter. Opposite operation is possible too.

MISCELLANEOUS:
  • H - Open Message - Sender and Receiver Retrieval dialog box
  • ALT+S - Save selection as nms file
  • CTRL+F - Find text, open find text dialog
  • F3 - Find text, next
  • Shift+F3 - Find text, previous
  • CTRL+Shift+F - Open Schematic Explorer
  • ALT+P - Creates a parameter operation in script
  • CTRL while linking - invert Search Best Path while Linking preference


Schematic Top Toolbar

Overview

The Schematic toolbar tools, from left to right:

  • Expand / Collapse Selected Scripts
  • Schematic Explorer
  • Message explorer
  • Find Text
  • Link Mode
  • Level / Scene script filter
  • Showing and Hiding Scripts
  • Show / Hide Local Parameters
  • Show / Hide Script Headers
  • Show / Hide Control Points
  • Show / Hide Link Information
  • Behavior Link Properties
  • Show / Hide Priorities
  • Reset Schematic Zoom and Position
  • Zoom Mode
  • Script Debugger
  • Trace mode
  • Links with Errors Explorer
  • Obsoletes or Invalid Building Block Explorer


Behavior Link Properties

Behavior Links (bLinks)

A behavior link (bLink) has a propagation delay, expressed in frames (see The Virtools Dev Process Loop for a definition of the frame).

A link delay of 1 indicates that that bLink will not activate the BB linked to it until the next frame. A link delay of 0 indicates that that the linked BB is activated immediately.

Take care that you do not use a link delay equal to 0 in a loop, except in special circumstances such as iterating a Group or an Array. A link delay of 0 can generate a never-ending loop, in which case Virtools's event log icon will flash and an error message will appear in the event log.

The iterating BBs that normally use a link delay loop of o are the Group Iterator and Iterator or Iterator If BBs.

Clicking this icon open the behavior link properties dialog box:

Default link delay:
When linking bOuts or bIns, the Behavior Link Delay is set to this value which is the number of behavioral frame to wait before continue the process. Default is 0.

Prevent Infinite Loop:
If selected, the delays for links that are part of a simple loop (i.e. linking a BB bOut with one of its bIn) are set to 1 instead of 0 (only if default link delay is set to 0).

Max Behavioral Iterations:
The maximum number of actions the Behavioral Engine can perform in a single frame before an infinite loop is declared.


Expand / Collapse Selected Scripts

Maximize (Open)
Click this button to expand selected scripts.

Minimize (Close)
Click this button to close selected scripts.


Link Mode

Level / Scene script filter

When L button is active
there is no filter for shown scripts in schematic.

When S button is active
only scripts of active scene can be shown. Active scene may change during play, or can be changed manually through the level view. Note that the active scene name is written at the top of Virtools Dev window.


Link Mode

/
Activates link tool, so that you can create bLinks and pLinks. Keyboard shortcut is L. If you have have activated auto link mode, the Auto link mode button displays instead. You can activate auto link permanently via the Schematic Preferences or by pressing A (to deactivate, press Z).

Using Link or Auto Link Mode to create Links

Select either the source or the destination you want to link with a mouse click, then each click will create a control point until you click to the final item to finish the link.

If your are in an automatic path finding link mode, you can just go from a bIn/bOut to another bIn/bOut directly (without even specifying the control points).

Note that Link and Auto link are just two possible ways of creating links - see the Links page for alternative ways that may suit your workflow better.

Invalid or existing pLinks

If you try to create a link that is invalid (destination type and source type are different), Virtools will warn you with an error message. If there is already an existing link on a pIn, Virtools asks if you want to delete previous link or to cancel the link operation. If you choose to delete a link that is between a local parameter and a pIn, the local parameter will be deleted too.

For more detail about linking


Links with Errors Explorer

Open the Link with Errors after Loading Explorer:

This icon appears only when a composition contains invalid links and you choose not to delete invalid links automatically in the Schematic Preferences.


Message explorer

Clicking this button opens a dialog box allowing you to retrieve message sender and receivers that have local parameter of type Message.

Select a message in the message list. BB which send this message are shown in the Senders List while BB receiving this message are shown in the Receivers list.

Double-click an item (or clicking the goto button when item selected) will center Schematic on this item.


Reset Schematic Zoom and Position

Click this button to reset the zoom factor to 1 and/or showing the first page of the schematic.


Schematic Explorer

Overview

The Schematic Explorer allows you choose which items you wish to see in the Schematic - Scripts, Behavior Graphs, Building Blocks, Comments, Shortcuts,parameter operations, Parameters, Inputs and Outputs -, and to select all or some of these elements manually or by type.

Using the Schematic Explorer

To open the Schematic Explorer, click the icon [image] which is towards the left half of the Schematic Top Toolbar, or press Ctrl+Shift+F with the focus on the schematic window. The main part of Explorer is the list of items present in Schematic. What you see will depend on the mode you are in: List View or Tree View. To switch from one to the other, click the Toggle button. For example to pass to Tree View from List View, click [image].

Press Select to accept changes made to selection in the Schematic. Press Cancel to revert the selection to its state when the Schematic Explorer had been opened. Note that it will not restore deleted items.

Note that the Schematic Explorer and the Schematic View are synchronised for deleted or selected items.

List View

List View mode opens by default.

Items List

The main part of the setup, with a list of items that you have selected to appear. The list is sorted alphabetically, no attention is paid to element type.
Icons in front of an item is the element type:

: Script
: Behavior Graph
: Building Block
: Comment
: Parameter Operation
: Shortcut
: Local Parameter
: Parameter Input
: Parameter Output
: Behavior Input
: Behavior Output

Selecting Items

You can select items in the list as you normally would in Windows, using the mouse or arrow cursor keys in conjunction with CTRL or SHIFT. Items will be also selected in the Schematic. Double-clicking on an element will center Schematic on this element. Right-clicking on an element allows you to edit it. To edit the name of an item, select it and press F2, or click it. The number of selected entities appear down in the Show in List tab.

Show in list

Check Boxes (Scripts, Behavior Graphs, Building Blocks, Comments, Shortcuts, Parameter Operations, Local Parameters, Parameter Inputs, Parameter Outputs, Inputs, Outputs)
Controls the type of entities shown in the list.

CKID Filter
Allows you to display the item having the specified CKID. It can be usefull if you use the SDK. Note that at most one item will be listed, and that this filter is used in combination with all previous and following filters.
For example, you are looking for a local parameter with CKID of 185 : you should check the Local Parameter button and enter 185 in the CKID filter edit.

Text Filter
Allows you to display only items containing the text string you enter.
For example in the image above, entering script would result in all of the items still being displayed. Entering funda however, and only the entries FUNDA script and FUNDA. Copy script would remain in the list.

Object Parsing: and
These buttons are used to toggle between 2 modes: parsing only visible objects in Schematic or parsing all objects.
Visible items are elements belonging to visible scripts.

Selection Actions

All
Selects all elements listed

None
 No elements will be selected

Invert
 Inverses any selection.

Goto
 Will show you where the first selected item in list can be found in the Schematic graph. An alternative is simply to double-click item in the list.

Delete
 Deletes the present selection.

Parameter Filter

All item in list can be filtered with parameter criteria. There are 3 available options that can be choosen in the top left combo box:

No Filter

Filter Type
Only parameters with the type specified in the top right combo box will be listed. Note that [image], [image] and [image] buttons are disabled when that filter is activated.

Filter Value
Only parameters with the type specified in the top right combo box, and with the same value specified in front of the [image] , will be listed. You can replace all filtered parameter with a replace value.

Type Filter
Can be changed with the top right combo box.

Edit Reference Value
Reference value is shown in front of that button.

Edit Replace Value
Replace value is shown in front of that button.

Replace All Filtered Parameters with Replace Value
Note that to keep listed parameter in list, the edit value is set to the replace value.

Local Parameters, Parameter Output and Shortcuts are affected by all parameter filters. Parameter Inputs are affected only by the Type Filter. Value Filter will hide them in the list.

Tree View

Tree view is activated by clicking on the toggle button [image].

Item List
The main part of the setup, with a list of scripts and an under list of BB and BG in the order they appear in Schematic.
You can only select one item at a time that will be also selected in schematic. Double-clicking on an element will center Schematic on this element.
To edit the name of an item (only scripts and BG, select it and press F2).

Show in list
only Parse All Items or Parse Visible Items feature is available

Selected Actions
only GoTo and Delete buttons are available. An alternative way to GoTo is simply to double-click item in the list.

Parameter Filter
This tab is disabled.


Schematic Find

Overview

Icon in schematic toolbar to open Find dialog. This dialog can be opened with Ctrl+F keyboard shortcut too.

This tool is used to find quickly any item with a specific text in its name. It can be a behavior, any parameter, parameter operation, comment, building block,... Each time a fitting item is found, it will be focused and selected in schematic.

  • Find: enter here the text you are looking for.
  • Search Closed Scripts/Graphs: select this checkbox if you want to include closed scripts and graphs in the search.
  • Search Hidden Scripts: select this checkbox if you want to include hidden scripts in the search.
  • Search Backward: select this checkbox to find previous item with the searched text in. Note that script order in schematic is used when searching forward or backward. Then in a specific script, the order used is the creation order, not "left to right" order, so do not be confused.

Keyboard Shortcuts

  • Ctrl+F: open Find dialog
  • F3: find next
  • Shift+F3: find previous
  • Ctrl+F3: if one and only one item is selected in schematic, it will find the next item with the same name or containing that name.

When the last item with the searched text is found, next call to Find Next tool will only write in error dialog the "Passed the end of Schematic" message, and selection in schematic will be cleared.


Script Debugger

Overview

Script Debugger allows you to see which behaviors and bLinks are activated at a given time: these ones are drawn in red. There are 2 debug modes:

  • a normal or trace debug mode, activated by clicking on the Trace button
  • a full debug mode, activated once the "Debug Inside Frames" button in Trace Options is checked. This one is more precise than the previous one but much slower.
Script Debugger allows you to examine how your scripts execute in detail, and so help you solve any problems should your composition not work as you intend.

Before using Script Debugger, you should understand how the Virtools Execution Loop or Frame works.

Using Script Debugger

The Script Debugger panel is opened by clicking on the Script Debugger icon [image] located towards the top right of the Schematic tool bar. Script Debugger is used in conjunction with Trace Mode, which must be activated. Trace mode runs slower when used with Script Debugger.

Trace Options

Debug Inside Frames
When checked, the behavioral engine will run with a smaller step than the normal one (corresponding to the [image] button from the status bar). This smaller step is called "Debug Step". At the same time, it unlocks "Debug Step" and "Leave Behavior" buttons. If not selected, then those buttons are disabled. It is used to follow more precisely the activation flow in trace mode.
Note: the behavioral engine will run slower if this feature is active.

Warning: the debug context must be locked to use this feature efficiently. Otherwise the behavioral engine will execute all activation flows (process) sequentially and it will be hard to follow just one flow.

Redraw Schematic only when Breakpoint Reached
 When selected, the Schematic will not be redrawn until a breakpoint is reached. If checked, this mode remain active even if the Script Debugger panel is closed. It can speed up the debugging process.

Trace Tools

Debug Step
Forces the behavioral engine to advance one Debug Step. Available only when "Debug Inside Frames" is selected.

Leave Behavior
Keeps the debugging engine executing until the Current Behavior's output is activated. Note that the behavioral engine stops however if number of frames specified in "Max CK Frames" is reached first, even if no behavior outputs have been activated.

Max CK Frame
Limits the number of frames that can be taken by the "Leave Behavior" button.

Simulated Fps
Number of frames per second simulated by debugging engine.

Debug Context

Current Object/Script/Behavior
Identifies which behavior, of which script, of which owner, is running. The check boxes to the right of the Current Object and Current Script are used to lock the context when using the Debug Step button. Locking the context does not mean that only the locked script/scripts of the locked object will be traced. Other scripts will still be executed, but the interface will advance with Debug Steps until the locked context is activated. It can be very useful to see what happens in a specific script.

Breakpoints

Note: breakpoints are copied during copy-paste action, as well as the selection. This is true when dynamic scripts are created by copy, if preference Show Dynamic Objects is checked: this may be helpful to debug dynamic scripts.

Add Breakpoint
Allows you to add a breakpoint to a behavior or a behavior link. When selected the mouse cursor seems as [image], just click a BB, a BG or a bLink to add a breakpoint. You can add and remove breakpoint through contextual menu too. A Breakpoint is a point which stops the debugging process it seems as a [image] in BB, BG or bLink.

Configure Breakpoints
Opens Breakpoint Configuration Dialog to add conditions to breakpoints.

Breakpoint List
Opens a window with a list of all breakpoints:

    • Remove Breakpoint: Removes all breakpoints
    • Remove All: Removes selected breakpoint.
    • Configure: Opens Breakpoint Configuration Dialog to add conditions to breakpoints.
    • Goto: Show the selected breakpoint in its script.

Breakpoint Reached
Flashes when a breakpoint is reached.

Goto
Moves focus to the reached breakpoint in the Schematic. If several breakpoints have been reached at the same time, continue clicking Goto to cycle through all reached breakpoints.

Message
Opens/Closes the debugging message log.

Clear
Clears the message log. This button is visible only when the message log is visible.

Tips

You should essentially use the breakpoint tools, and, if you need more speed while in debug mode, use the "Redraw Schematic Only When Breakpoint Reached".

The Debug Context and Trace Tools are useful in if you want to trace with a lot of accuracy, that is inside CK frames. It may be useful to detect exactly when the value of a local parameter changes.


Obsolete or Invalid Building Block Explorer

Overview

The Obsolete or Invalid Building Block Explorer provides a more convenient way to replace obsolete or invalid BBs than the Building Blocks Version Test (i.e. all or nothing) or manually (i.e. through the Schematic).

After loading and answering No to the Building Blocks Version Test Dialog (from the Option pulldown menu), open the Obsolete or Invalid Building Blocks Explorer [image] from the Schematic Toolbar.

You may then select a Building Block from the list and select one of the options below:

Goto: Focus on the BB in the Schematic View (to check its settings connections). You may then choose another option below.
Replace: replace the selected BB
Replace Same: replace every bb in the list with the same name.
Replace All: replace all Building Blocks in this list.

This tool is usefull to manually check and replace Building Blocks, particularly when the automatic replace proposed by the Building Blocks Version Test fails to work correctly - e.g. you can selectively examine and change a few BBs, and then use the automatic Replace All button for the rest.


Script Debugger

Configuring Conditional Breakpoints

Overview

Breakpoints can have conditions to be active. A condition is a proposition that can be true or false. Its form is :

<Schematic Parameter> <condition> <Reference Parameter> [<operation>]

where <Schematic Parameter> can be any parameter local or parameter out in the schematic

<Reference Parameter> is the value that will be use for comparison, <condition> the comparison operator, and <operation> is used for multiple conditions on the same breakpoint.

Related Keyboard Shortcut

  • F9: add or remove breakpoint on selected item (parameter: link/ behavior).
  • Shift+F9: configure breakpoint on selected item.

Configuration

The Breakpoints Configuration dialog can be accessed through Configure Breakpoints button in script debugger, or the Configure button in Breakpoint List dialog.

Breakpoint List Combo Box

  • Breakpoint list combo box : select here the current breakpoint you want to configure.

Command Buttons

  • Add Condition : adds a condition on current breakpoint
  • Remove Condition : removes selected conditions from current breakpoint
  • Pick Schematic Parameter : select schematic parameter.
  • Edit Reference Parameter : edit reference parameter value if refence parameter is a constant, or pick another reference parameter in schematic otherwise.
  • Pick Reference Parameter : select reference parameter
  • Go To Breakpoint : focus breakpoint in schematic
  • Go To Schematic Parameter : focus schematic parameter in schematic
  • Go To Reference Parameter : focus reference parameter in schematic, if available

Conditions List

  • Schematic Parameter column : double click to select another schematic parameter
  • Condition Column : double click top open a combo box and select a new condition.
  • Reference Parameter Column : double click to select another reference parameter.
  • Operation Column : double click on an operation to open a combo box and select a new operation :

Schematic Parameter

The Schematic Parameter is the first parameter of the condition.

To edit it, double click on it or push Pick Schematic Parameter button after selecting the right row in list, then pick a parameter in schematic.

The Reference Parameter must be of a compatible type with the Schematic Parameter. If the Reference Parameter is picked in schematic and is not compatible, it will not be taken into account.

On the above picture, the user is in picking mode , as shown by the "Pick Schematic Parameter in Schematic" text at the bottom of the dialog. The lower left text ("none") is the name of the parameter currently under the mouse cursor in schematic.

Condition

Double click on a condition to edit it.

Can be : equal, different, equal to parameter, different from parameter, less, less or equal, greater, greater or equal, less than parameter, less or equal to parameter, greater than parameter, greater or equal to parameter.

Note : [> / >= / < / <=] and [> / >= / < / <=] parameter conditions are available only if the Schematic Parameter type is compatible with the integer or float types.

  • If [= / <> / > / >= / < / <=] parameter is selected, the condition is called parametric condition and the reference parameter will be a parameter from the schematic
  • if [= / <> / > / >= / < / <=] is selected, the condition is called constant condition and the reference parameter will be a constant.

Reference Parameter

The Reference parameter is the second parameter of the condition. It can be a constant or a parameter from the schematic depending on the condition.

Note that if the Schematic Parameter has not been picked, the Reference Parameter cannot be edited / selected.

  • To edit a constant Reference Parameter, double click on it or push Edit Reference Parameter button after selecting the right row in list.
  • To edit a not constant Reference Parameter, double click on it or push Pick Reference Parameter button after selecting the right row in list, then pick a parameter in schematic. The selected parameter type must be compatible with Schematic Parameter type to be taken into account.

On the above picture, the user is in picking mode , as shown by the "Pick Reference Parameter in Schematic" text at the bottom of the dialog. The lower left text ("none") is the name of the parameter currently under the mouse cursor in schematic.

Operation

Double click on an operation to edit it.

Can be : And, Or, Xor.


Show/Hide Control Points

This button Shows/Hides the Link control points.


Show/Hide Local Parameters

Toggle between 2 display modes.
When the hide mode is activated, closed local parameters, directly link to an Parameter Input, through a link without control points, are hidden.


Show /Hide Priorities

Shows/Hides the priority order for the execution of each behavior and scripts.
The default is hide.


Show/Hide Link Information

Click this button to show/hide link delays.

See also Behavior Link Properties.


Show/Hide Scripts Header

Show/Hide Script Headers

This button Shows/Hides the script headers.


Showing and Hiding Scripts

Show all Scripts

Click this button to display all scripts.

Hide all Scripts

Click this button to hide all scripts.

Hide Selected Scripts

Click this button to hide selected scripts.

Hide Non-selected Scripts

Click this button to hide all non-selected scripts.


Trace Mode

Overview

Activates/Deactivates Schematic Trace Mode.

When you activate Trace Mode, all active scripts, behaviors and links are drawn in red during Play Mode. This allows you to follow the activation flow and see when exactly when behaviors are activated and deactivated.

In addition you can add Breakpoints or even Conditional Breakpoints with the Script Debugger so that Dev pauses play whenever a breakpoint or particular condition is reached.

Using Trace Mode

Trace Mode is particularly useful when used in combination with breakpoints: you can add or remove breakpoint through the context menu to BBs, BGs, bLinks, Parameters and Parameter Shortcuts. Several more options for breakpoints are available through the Script Debugger.

Behavior *Not Working*

If a behavior (BB, BG) does not seem to be working, try the following steps:

1) set behavior link delay that precede the behavior at 1 if they were set to 0
2) add breakpoint on that link
3) play in trace mode until the breakpoint is reached, then use the Step button to examine what happened exactly.
4) if the breakpoint is not reached, try to go back further through the links, setting their delay at 1 and adding breakpoints.

*Incorrect* Parameter

If a Parameter does not have the value you expect, try the following steps:

1) if the parameter is a parameter out, copy it then paste it as a shortcut
2) display the value of the parameter or the shortcut in the schematic by using the contextual menu command "Display Value".
3) run in trace mode to see the evolution of the parameter
4) if you cannot explain what happen, try to use breakpoint on behaviors that should modify the parameter, even if the behavior is in a loop, and use the Step button.

Note: the Parameter Debugger is also useful to follow Parameter values; the Parameter Debugger will show values in real-time if Trace Mode is activated.

Message *Not Received*

If Wait Message or any behavior waiting for a message does not receive a message, try the following steps:

1) check that the messages are the same between the sender and the receiver.
2) set a breakpoint on the message sender to check if the message is really sent.
3) set a breakpoint on the link that comes from the message waiter, to check if the message is received.
3) when the message is sent, check that the script that contains the message waiter is active: the name of the script should be in red, and any possible graph that contains the message waiter should be in red as well.

About Breakpoints

There are 3 types of breakpoints:

  • BG or BB breakpoint: active when graph or building block is active
  • bLink breakpoint: active when link is active
  • Parameter breakpoint: active when parameter value has changed

Virtools is paused by a breakpoint if that breakpoint is active and was not active previous frame.
Virtools is paused when a breakpoint is reached and the breakpoint state has changed : this means that if a breakpoint is activated at frame t, and is still activated at frame t+1, Virtools will not be paused at frame t+1 by that breakpoint since there was no activation state change.

Conditional breakpoint
Press Configure Breakpoints button in Script debugger or Configure button in Breakpoint List dialog to open the Breakpoints Configuration dialog

Note: Schematic breakpoints are saved with behaviors/script and are copied when copying behaviors/script.

Tips

When a behavior is not working, always check that the owner script is active, as well as any behavior graph that contains the behavior. The building block "Deactivate Script" is useful, but it may be tricky sometimes.

When debugging a dynamic script, remember to:
1) check "Show Dynamic objects" in Preference dialog, Miscellaneous Controls: scripts must be visible in schematic
2) in there is a Dependencies parameter, select the "name" check box, so that all items in any copied script have a name
3) try to put a breakpoint just before or after the script is copied, so you can put breakpoint in the dynamic script as well. Otherwise you can try to pause when the dynamic script is present.

Note: breakpoints on the original script are not copied in dynamic scripts.


Zoom Mode

Click the Zoom Mode button to activate the Zoom Mode.
Zoom mode allows you by click and dragging the mouse up and down to modify the zoom factor of the scripts.


Setups

Overview

The majority of Behavioral Objects have parameters that you can edit via a Setup. Some parameters can also be changed at run-time via BB.
  • The setup of an Entity created (camera, light, grid etc.) is opened on creation by default, except if you have specified otherwise in General Preferences.
  • All setups can be opened via the Level Manager (double-click an element without sub-folder, or via the shortcut menu).
  • Render Objects setups can be opened via the 3D Layout (using the shortcut menu).
  • Scripted objects can be opened via the Schematic (shortcut menu on script's owner header).
  • Sometimes setups can be opened through other setups (for example a material's setup can be opened from its texture).

Here are shortcuts to the different setups you can find in Virtools:
2D Frame - 2D Sprite - 3D Frame - 3D Object - 3D Sprite - Array - Body Part - Camera - Character - Curve - Grid - Group - Level - Light - Material - Mesh - Place - Portal - Scene- Sound - Texture

Top Toolbar

Picker Tool:
This is used to choose another entity of the same type to replace the one currently edited.

Entity Name:
The object name. The combo box lists all objects that can be edited by the current setup. Press F2 to edit the name of the currently edited object when the combo box has the focus. Otherwise, you can edit the name by selecting the object in the level view in the same way. You can also use the drop-down box to select another object from the list. The entities available are only objects of the same type, in the same scene.
You can use this combo box to rename an entity (change the name and press Enter) of find another object (enter the object's name [or just the beginning of its name] and press Down Arrow).

File Name: (Available only for some entity types, such as Textures,Sprite or Sounds)
Shows the external filename of this object. The object can be replaced by clicking on the folder.

Close Setup:
 Closes the window. The setup can also be closed by pressing the Delete key, or by selecting Close Window on the pop-up menu over the tab.

Left Toolbar

Thumbnail:
Can be altered by dragging an image from the Snapshot Dialog. There is 2 contextual menu options available by right clicking on the snapshot, Load Snapshot to use any image as new snapshot, and Remove Snapshot to remove the snapshot from the entity. Images loaded as snapshot are stretched to the visible size of the snapshot.

Parameter:
This subsetup is activated by default when opening a setup. It holds information and parameters about the current entity. See the documentation corresponding to the entity type for more information.

Attribute:
Each entity has a list of Attributes, which can be managed locally using this subsetup or globally by using the Attributes Manager.
See attribute mode documentation for how using it.

Main Setup Area

This is the main part of the setup. There are two mode for setups, Attribute Mode is opened by clicking the Attribute buttons allows to set attributes to entities. Parameter Mode is opened by default and allows to change parameter of an object. Parameter mode depends on entity type setup. Here is a list of different setups accessible in Virtools:

  • 2D Frame Setup
  • 2D Sprite Setup
  • 3D Frame Setup
  • 3D Object Setup
  • 3D Sprite Setup
  • Array Setup
  • Body Part Setup
  • Camera Setup
  • Character Setup
  • Curve Setup
  • Grid Setup
  • Group Setup
  • Level Setup
  • Light Setup
  • Material Setup
  • Mesh Setup
  • Place Setup
  • Portal Setup
  • Scene Setup
  • Sound Setup
  • Texture Setup


Attribute Mode

All behavioral objects may have Attributes. You can manage Attributes globally using the Attributes Manager, or using the Attribute Mode for elements that have Setups.
To open the Attribute part subsection of a Setup, click the Attribute Button [image].

Add Attribute:

Opens the standard Add Attribute dialog box so that you can add Attributes.

Main Window:

Lists all Attributes (name - type - value) currently attached to the object. You can remove attributes by selecting them and pressing DELETE. You can also change attribute values by double clicking the Value column. You can change the sorting order of the attributes by either clicking on the header 'Name' (therefore sorted by the attribute's name) or on the header 'Category' (then sorted by the category name.)

Copy & Paste Attributes on another object

Copy selected attributes to the clipboard with the command Copy Attribute Parameter Value from the right click menu, then paste these attributes in another attribute setup with the Paste Attributes command from right click menu (in the list out of existing attributes).

Add Attribute Dialog Box

Clicking on the Add Attribute button open the following window:

Select an attribute for the entity and click add selected. The attribute will appear in the entity attribute setup main window. Click Close when finished.

Extended Mode:

This mode allows you to create new categories and new Attribute Types. The created category/Attribute Type will appears on the tree view.


2D Frame Setup

General

Pickable
Allows the 2D Frame to be 'picked' or selected. Picking allows you to know the element a user clicks or moves over.

Homogenous Coordinates
Uses percent and not pixels to position and size the 2D Sprite. This means that if the window changes size, the 2D Frame's position and size change automatically.

Clip To Camera
If the 2D Frame is outside the camera aspect ratio, this tells the renderer if the clipping zone is the entire screen or the camera ratio.

Relative To Viewport
to complete

Material

Name of the Material currently used, if any. The material can be changed by selecting another from the drop down menu. Clicking on the icon [image] opens the Material setup.

Position

Position X, Y
The position on screen - in percent if Homogenous Coordinates is selected, otherwise in pixels.

Z Order
Sets the rendering priority. The 2D element that has the lowest priorty is drawn first, then the next lowest element until finally the 2D element with the highest priority is drawn. It is not possible to predict which element will be rendered first if two or more elements have the same priority.

Background Sprite
Makes the 2D Frame a background sprite. The render engine draws background sprites first (using the Z order to decide the processing order), then draws 3D elements, and finally draws foreground sprites (again using the Z order).

UVMapping

Active
Activates UV Mapping.

Left, Top, Right, Bottom
Coordinates of the crop rectangle.

Size

Width, Height
2D Frame size, in pixels or in percent depending on whether Homogenous Coordinates are used.

Parent

Parent List
2D Frame have a similar hierarchy management to 3D Entities. You can change the parent of the frame by selecting a new one in the drop-down box.

Clip To Parent
Clips the 2D Frame to its parent, i.e. regions that are outside (bigger than) the parent's extents are cropped.

Stick Left, Right, Top, Bottom
Stick to chosen borders of the parent at the current distance.


2D Sprite Setup

Image Format

2D Sprite Information

System Memory Format
Displays image information concerning the Size, Color Depth and Mask Description as it is stored in system memory.

Desired Video Format:
Display sprite's image information concerning the Color Depth and Mask Description as it is stored in video memory.
If an asterisk appears at the right of the texture information, the sprite can be used with this desired image format in video memory (thus the 'Video Memory Information' will be the same as the 'Desired Video Format'). If there's no asterisk at the right of the image information, the closest available image format supported by the user's 3D card will be used.
The 'Desired Video Format' is saved inside the .CMO file. Therefore, even if the 3D card used to develop the composition doesn't support the desired image format, the end-user of the composition will be able to see the sprite in the desired image format if its 3D card is good enough.

Video Memory Information:
Displays information about the file as stored in the video memory: height x width in pixels, color depth in bits, video format in bits per argb component (space taken up in video memory). Note that for AVI files only the current frame is stored in the video memory, and subsequent frames are streamed.
Note: you can see the total video memory size used by all image files in the Profiler window.

System Caching
This combo box, located on the right of the texture's Video Memory Information, is available when Save Options are set to Original file or External. Selection types are:

    • Procedural:
      The texture is stored in a raw 32 bit (ARGB) per pixel format for easy read and write operations. This is usefull when you want to alter the texture with a VSL script for example (Texture.SetPixel).
    • Video Shadow:
      The system memory format is a straight copy of the video memory format.
    • Discard:
      Texture is discarded from system memory, and cannot be drawn in the setup.

Slot Navigation and Modification

First
Displays first image slot.

Prev
Displays image just before current slot.

n/n
Slot currently selected/number of slots in image file.

Next - N
Displays image slot just after current slot.

Last - P or SHIFT+N
Displays last image slot.

Add Texture - O
Opens a dialog box so that you can browse to a folder and choose an image file to load. The image you load, which must be of the same height and width, is stored in a new slot. Alternatively, you can add an image file to a new slot by dragging an image from a Data Resource into the preview window while holding the SHIFT or CTRL key.

Remove Current Slot
 Removes the current slot, but only if there are 2 or more slots.

Preview Window and Shortcut Menu

The preview window displays the current slot and allows you to zoom in or out. Right-click the preview window for additional options:

Add new slot - O
Opens a dialog box so that you can browse to a folder and choose an image file to load. The image you load, which must be of the same height and width, is stored in a new slot. Alternatively, you can add an image file to a new slot by dragging an image from a Data Resource into the preview window while holding the SHIFT or CTRL key.

Replace slot - R
Opens a dialog box so that you can browse to a folder and choose an image file to load, replacing the current slot. The image you load must be of the same height and width, unless the 2D Sprite only has a single slot. Alternatively, you can replace a slot by dragging an image from a Data Resource into the preview window.

Remove slot
Removes the current slot, but only if there are 2 or more slots.

Reload slot
Reloads the current slot. This is useful if the slot has been modified by building block since loading.

Save slot - S
Saves the current slot to an image file.

Zoom In/Out - +/-
Changes the zoom factor. Mininum zoom is 7%, maximum is 5000%.

Zoom 1:1 - /
Changes the zoom factor so that the slot is displayed at it's real size, pixel for pixel.

Zoom Best Fit
Changes the zoom factor so that the entire slot is visible in the preview window.

Interactive zoom
Hold the right mouse button over the sprite and move the mouse around. You can scroll a zoomed image by holding and moving the left mouse button.

General Image Properties

General

Pickable
Allows the 2D Sprite to be 'picked' or selected. Picking allows you to know what element a user is clicking or moving over.

Homogenous Coordinates
Uses percent and not pixels to position and size the 2D Sprite. This means that if the windows size changes, the 2D Sprite's position and size changes automatically.

Clip To Camera
If the sprite is outside the camera aspect ratio, this tells the renderer if the clipping zone is the entire screen or the camera ratio.

Relative To Viewport
To update.

Position and Size

Position X, Y
The position on screen, in pixels or in percent depending on the state of Homogenous Coordinates check box.

Z Order
Sets the sprite's priority. Drawing starts at lowest sprite priority, going to highest. Background sprites are managed in a different list that Foreground sprites. Behavior is unknown when sprites share the same priority.

Background Sprite
If activated, the sprite is drawn first before the 3D objects, otherwise it is drawn after all other objects.

Size Width, Height
The size on screen, in pixels or in percent depending on the state of Homogenous Coordinates check box.

Save Options and Color Key Transparency

Save Options List
The sprite can share the default save settings (see General Preferences), or use an independent save format. Selection types are:

  • Raw Data
    Sprite is not compressed, it's saved as it is (this usually take a lot of space in the cmo file, depending on the size).
  • External
    Only a reference to the original sprite file is saved inside the cmo file (i.e. the path and the filename).
  • Specific Format
    The sprite is saved inside the cmo file by taking advantage of the compression of one of the image savers. Use the button below to change the saver type.
  • Global Settings
    Uses default settings, which can be changed in the General Preferences.
  • Original File
    The sprite is saved in the cmo file as it was in the source file (for example,using this type, an AVI file will be stored inside the cmo file, and you won't need the original file anymore).

    • Color Key Transparency
    Allow selection of a transparent color.

    • Active: The selected color is not rendered, letting anything behind appear.
    • Picking Tool: Chooses the color.

    Because of the generic way the color key is process inside Virtools, activating the color key will destroy your alpha channel image.

    Cropping

    Active
    If activated, uses the rectangle from top-left to bottom-right as cropping. The region inside the rectangle will be considered as the extents of the sprite (i.e. as it was a whole sprite).

    Left, Top, Right, Bottom
    Coordinates of the crop rectangle.

    Parent

    Parent List
    2D Frame/2D Sprites have a similar hierarchy management to 3D Entities. You can change the parent of the sprite by selecting a new one in the drop-down box.

    Clip To Parent
    If activated, the sprite will be clipped according to its parent, regions outside the parent's extents will be cropped.

    Stick Left, Right, Top, Bottom
    Stick to chosen borders of the parent at the current distance.


3D Frame Setup

3D Properties

Position
Coordinates expressed in the world coordinate system, and in the local coordinate system if the frame has a parent.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, and in the local coordinate if the frame has a parent.

Scale
Scale expressed in the world coordinate system, and in the local coordinate system if the frame has a parent.

Other Properties

Show in player mode
If selected, the 3D Frame is displayed in Player mode. Note that this option can be forced in the 3D Layout - Interface Preferences by selecting "Automatic Show Entities In Player Mode".

Frame Representation

A 3D Frame representation can be changed with various shapes. By default :

  • Cross
  • Cube
  • Frame
  • Sphere

All shapes are meshes stored in the file [Virtools Dev install folder]\InterfacePlugins\interface.nmo.

To add or modify available 3D Frame representation, open interface.nmo in Virtools Interface after a New Composition, then modify or add some meshes. At most you can have 62 meshes for 3D Frame representations. A mesh name must be : VIRTOOLS_Frame_(desired name). When modification are done, select all available objects in Level Manager, then save them as a new interface.nmo.

This way you can customize your 3D Frames, by adding meshes with different color for instance (using vertex color, or using a material).

3D Frames representation can be changed in 3D Layout too, by using the contextual menu on a selection of 3D Frames.


3D Object Setup

3D Properties

Position
Object's coordinates expressed in the world coordinate system, and in the local coordinate system if the object has a parent.

Reset World Matrix
Resets the scale to 1:1:1, useful if the scale value is invalid (ie 0:0:0) and the mesh is no more visible for instance.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, and in the local coordinate system if the object has a parent.

Scale
Scale values in the world coordinate system, and in the local coordinate system if the object has a parent.

Set As Unit
Scales the mesh vertices in order to set the scale to 1:1:1.

World Size
Size of the object's bounding box expressed in the world coordinate system.

Mesh Properties

Object Meshes
Lists all Meshes that are available to the 3D Object (note that only one mesh can be active at any one time). Double-clicking Mesh will open its setup.

Current mesh
Shows summary information about the current active Mesh.

Procedures

To add a Mesh to the Object Meshes box

  • Select a Mesh in the Level Manager and drag it into the Object Meshes box.
  • Right-click in the Object Meshes list and choose Add Mesh, select the mesh in the combo box of the dialog.

    • To change the current active Mesh

    Right-click a Mesh in the Object Meshes box and choose Set As Current.

    To remove a Mesh from the Object Meshes box

  • Select a Mesh in the Object Meshes box and press DELETE.
  • Right-click a Mesh in the Object Meshes box and choose Remove Mesh(es).

    • To go to the Setup for a particular Mesh

  • Double-click a Mesh in the Object Meshes box.
  • Right-click a Mesh in the Object Meshes box and choose Show Mesh Setup.

    • Other Properties

    Pickable
    If this checked, the object can be picked in the 3D Layout (it's the default behavior), and could be retrieved from a '2D Picking' building block. If not checked, this object can't be picked in the 3D Layout and any picking attempt will react as if the object wasn't there (i.e. result in picking the object just behind if this one is pickable).


3D Sprite Setup

3D Properties

Position
Coordinates expressed in the world coordinate system.

Orientation (for Orientable 3D Sprites only)
Orientation expressed in degrees (Euler angles) in the world coordinate system, or in the local coordinate if the 3D Sprite has a parent.

Scale
XY values in world scale.

3D Sprite Properties

Sprite Type
The type of 3D Sprite:

  • Billboard (default)
    Always faces the camera.
  • X Rotate
    Same as above, but keeps the X axis free.
  • Y Rotate
     Same as above, but keeps the Y axis free.
  • Orientable
    Free, ruled only by the orientation.

Pickable
To complete.

Offset
On creation an axis is created in the middle of 3D Sprite. You can set Offset values for the X and Y axes to align the 3D Sprite to other entities, such as next to a wall or along the ground for example.

UVMapping
 Mapping coordinates of the top left and bottom right corners. The render engine uses this information to map the Texture image to the 3D Sprite surface.

Material
Displays the name of the Material currently being used. To open the Material's Setup, click the icon [image] to the left of the Material's name.


Array Setup

Main View

The top row contains the array format (number of columns and their names.), and the first to the far left column contains the row (number starting with row 0).

Selected rows appear in a darker gray. You can move the selection with the keyboard arrows, and can select multiple rows using CTRL or SHIFT. A darker cell (or many if you have a multiselection) represents the cell to edit. You can move this cell horizontally on the selected row by pressing the left and right arrows. By pressing ENTER or F2 you can change the value of this element (or these elements in a case of a multiselection). Alternatively, double click an element to change its value.

You can delete a selection of rows by pressing 'delete' key and move rows by pressing '+' and '-' keypad keys after selecting one.

Toolbar

Add Column:
Allow the user to add a column in its array. Open a dialog box to choose the type of the column, one of the four basics types (integer, float, string, object) or the extended parameter type, which allow you to store whatever data that is provided by Virtools into your array.

Add Row:
Add a row at the end of the array, giving the created row elements default values.

Column Header and Cell Context Menus

Column Header

Right click a column header to display the context menu:

Sort Ascending / Sort Descending
Allows you to sort the rows of the array following a column. It only works with integer, float or string basic types.

Edit Column Properties
Allows you to change the name and the type of the column. Can also be accessed by double clicking on the column name.

Make Key Column / Remove Key Column
Allows you to set or remove the column as a key column (materialized by a darker gray background on the header). If the column is a key column, new or changed values on this column will be checked for uniqueness, during setup edition, not at run-time.

Delete Columns
Allows you to remove the selected column.

Move Column Left/Right
Allows you to swap the column selected with the one next left/right to it.

Insert Column
Allows you to create a column by opening the Add Column dialog box and insert it before the selected column.

Cell

Right-click any element in a cell to display the context menu:

Insert Rows
Allows you to insert a new row, before the row selected.

Delete Column
Allows you to remove the selected row.

Edit/Edit multiple
Allows you to edit the element(s) value(s). Multiple edition is only available for a non-key column and when selecting multiple rows with SHIFT or CONTROL pressed.

Copy
Allows you to copy the parameter, for copying the value in the schematic. You shouldn't try to paste this parameter as a shortcut in the schematic because this won't be saved. This option only appear if the column type is a parameter.

Paste as Shortcut
Allows you to shortcut a parameter formerly copied from the schematic into the array (value will then appear in brackets). this option only appear if you have actually copied a local parameter or an Parameter Output in a script and the column parameter type is compatible with the copied parameter.

Paste
Allow you to paste a parameter formerly copied into the array. All selected compatible parameters will have their value updated. This option only appear if the column type is a parameter.


BodyPart Setup

The BodyPart class derives from 3D Object. There is only one parameter specific to BodyPart in addition to the standard parameters found in the 3D Object Setup:

Character
Shows the name of the character the bodypart belongs to. You can access the character's setup by clicking on the button [image] next to the name.


Camera Setup

3D Properties

Position
Coordinates of the camera in the world coordinate system, and in the local coordinate system if it exists.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, or in the local coordinate if the parent is non-null.

Target Cameras Only

Distance from camera to target
Distance between the camera and the target, expressed in the world coordinate units.

Target position
Coordinates of the target in the world coordinate system.

Camera Properties

Visibility and Target

Show camera in player mode
If activated, the camera and the target are displayed in player mode, otherwise they are not visible.

Show cone
 This actives the representation of the camera view. This is shown as a pyramid with the camera as the top. The direction vector is drawn in yellow. Also, near and far clipping planes are represented as two crossed planes.

Target
You can select the camera's target using this drop-down list of 3D Frame. When set to 'none' camera is free.
If you're sure not to use anymore a target for this camera, you'd better remove the 3D Frame used as the target.
If you want a 3D object to be the camera target, simply parent the 3D Frame used as target to the object by using the Hierarchy Manager.

Projection Type and Aspect Ratio

Projection type
Specifies the type of the projection on the image plane. It can be set to: Perspective (default) or Orthographic.

Aspect ratio X,Y
Sets the horizontal/vertical components of the camera aspect ratio.

    • Active
      When this camera is the current active camera, the rendering view is re-sized to match the chosen aspect ratio. The aspect ratio is always taken into consideration in the Virtools Web Player, but in Virtools this flag is used for each camera only if the Preference flag 'Ignore camera aspect ratio' is unchecked.
    • Type
      Used to select a preset aspect ratio from the following: Normal (4/3), Extended (16/9), Widescreen (7/3), Panoramic (20/7) and Custom which is set by the user.

Perspective

Perspective
Used to select a preset camera lens length from the following: 15 mm, 20 mm, 24 mm, 28 mm, 35 mm, 50 mm, 85 mm, 135 mm, 200 mm and Custom which is set by the user when he changes the following values:

    • Field of View
      This is specified in degrees. The focal length parameter is also modified when this parameter is changed. Values between 0 and 180° can be entered.
    • Focal length
      This is specified in millimeters. The field of view parameter is also modified when this parameter is changed. Values between 0 and 250 mm can be entered.

Clipping

Clipping
For performance reasons, every camera has a near and a far plane, in order to clip objects that are too far or too close, particularly to optimize rendering speeds. Interior scenes usually have the far clip reduced to improve processing, allowing for a greater number of objects in interior scenes. Outdoor scenes typically have a distant far clip, and have a reduced number of objects to compensate.
Note: if you encounter Z Buffer problems (known as Z Fighting) reducing the Far Clip, and increasing the Near Clip often gives a better result.

    • Near clip
       Objects closer than this distance to the camera are not displayed. Near clip must be smaller than far clip.
    • Far clip
       Objects further than this distance from the camera are not displayed. Far clip must be greater than near clip.


Character Setup

3D Properties

Position
 Charcter's coordinates expressed in the world coordinate system, and in the local coordinate system if the object has a parent.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, and in the local coordinate system if the Character has a parent.

Scale
Scale values in the world coordinate system, and in the local coordinate system if the Character has a parent.

World Size
Size of the Character's bounding box expressed in the world coordinate system.

Character Properties

Character BodyParts
Lists all the BodyParts that make up the Character.

To go to the Setup of a BodyPart

  • double-click the Bodypart

  • right-click the BodyPart and select Show Body Part Setup.

    • Other Properties

    Pickable
    If this checked, the object can be picked in the 3D Layout (it's the default behavior), and could be retrieved from a '2D Picking' building block. If not checked, this object can't be picked in the 3D Layout and any picking attempt will react as if the object wasn't there (i.e. result in picking the object just behind if this one is pickable).


Curve Setup

3D Properties

Curve

Position
Coordinates of the curve base in the world coordinate system, and in the local coordinate system if it exists.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, or in the local coordinate if the curve has a parent.

Scale
Values of the curve base expressed in the world coordinate system, and in the local coordinate system if it exists.

Curve Point

Current Point Position
Coordinates of the current point expressed in the world coordinate system.

Curve and Curve Point Properties

Curve

Show in player mode
If set, the Curve is displayed in player mode, otherwise it is not.

Curve Type

    • Linear, Spline
      Linear, where points are linked with straight lines, or Spline (default) where the links are curved.
    • Open/Close
      When set to Close, the first point on the curve is linked to the last.

Curve Aspect

    • Step count
      The detail of the drawing is increased as the step count is increased. Values between 1 and 1000 can be entered. The default is 100.
    • Fitting coefficient
      Values between -1 and 1 can be entered. The default is 0.
    • Curve length
      Expressed in world coordinate units.

Modify Curve

Adding, deleting, inserting and editing Points

    • To add points to the curve
      Click Add Points button. In the 3D view, click with the left mouse button where you want to create a point. When you add a point the curve is automatically extended from the previous point. Use the right mouse button to create a point at the end of the curve. You can use 3D layout navigation tools to move in the 3D view.
    • To insert points in the curve
      Click Insert Points button. click the curve where you want to insert a point.
    • To edit points in the curve
      Click Edit Points button. Drag the desired points of the curve in the direction you want.
    • To delete points in the curve
      Click Delete Points button. click a point to delete it.

Referential
This allows you to constrain the control points of the curve to be on a specific plane. Available options are:

    • Guide
      The curve plane is parallel to the grid plane.
    • View plane
      The curve plane is parallel to the view plane.

Show curve points
If selected, displays curve points.

Changing Point Coefficients

You can modify the curve shape near its control points by changing the coefficients below:

    • Bias
      Values between -10 and 10 can be entered. The default is 0.
    • Tension
      Values between -10 and 10 can be entered. The default is 0.
    • Continuity:
      Values between -10 and 10 can be entered. The default is 0.

Points

Current point (x out of n)
The point on the curve which is currently selected.

First
Selects the first point on the curve.

Previous
Selects the previous point on the curve.

Next
Selects the next point on the curve.

Last
Selects the last point on the curve.

Next Segment Is Linear
Transforms the next segment following the current point into a linear segment.

Point distance on curve is
Indicates the distance between the first point and the current point along the curve.


Grid Setup

3D Properties

Parameters relating to the 3D Properties of a Grid are not in the main Grid Setup; to access 3D Properties, right-click a Grid in the Level Manager and choose Setup.

Position
 Object's coordinates expressed in the world coordinate system, and in the local coordinate system if the Grid has a parent.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, and in the local coordinate system if the Grid has a parent.

Scale
Scale values in the world coordinate system, and in the local coordinate system if the Grid has a parent.

World Size
Size of the object's bounding box expressed in the world coordinate system.

Pickable
If this checked, the object can be picked in the 3D Layout (it's the default behavior), and could be retrieved from a '2D Picking' building block. If not checked, this object can't be picked in the 3D Layout and any picking attempt will react as if the object wasn't there (i.e. result in picking the object just behind if this one is pickable).

Grid Properties

Parameters relating to a Grid are in the main Grid Setup; to access 3D Properties, right-click a Grid in the Level Manager and choose Grid Setup.

Top Toolbar

Grid Name
The grid currently selected. You can use the pull down menu to select a different grid. Go to Level Manager if you need to change either a grid's name or visibility.

X, Y
Displays the mouse cursor position in the grid's referential, or # if cursor is out of grid range.

Value
Value of the square in the currently selected Layer at mouse cursor position. If you want to view square value at (X,Y) grid position on the selected Layer, you must first select the Layer in the Layer List.

Width, Length
Width and length of the grid. The height of the grid is always of 1 unit in the grid referential. Be sure to give to your grid a sufficient Y scale (height) to include objects supposed to be subject to the grid.

2D View and Sliders

Gradation Slider (horizontal slider above 2D View)
Lets you define the value (integer [0,255]) to be put on a layer square with the cursor. Click into the slider and slide from right to left to change this value (values are represented by there intensity in the grid 2D representation).

Opacity Slider (vertical slider on the left)
Transparency of a grid when editing. This setting is not saved with the grid, and is reset to the default 50% when the grid is reloaded. Grid Visibility however is saved as it is a real 3D Entity Attribute, and has nothing to do with the Opacity Slider).

2D View
View representing the grid in 2D. Layers are cumulated and their square value (intensity*layer color) are added. Therefore, if you have a green layer and a red layer, 2 squares of these layers at the same (X,Y) position with a full value (255) will render as if the square where yellow (255 red + 255 green).

    • Putting a value on a square:
      Select layer(s) to work on in the "Layer List", and start painting (i.e.: putting values) at cursor position. The value put in square(s) will be the one selected with the "Gradation Slider".
      You can also Double-click a square to open the Square Value Parameter Dialog Box, and enter manually the square value. If the Layer Type is a "Linker" parameter, then you'll have to choose (after Double-click the square) between: None, Start, End, Start/End, Door.
    • Erasing a square value:
      Select layer(s) to work on in the "Layer List", and hold RMB to put null value on square(s). Note: you can perform the same by setting the "Gradation Slider" value to 0, and start painting on grid.

Orientation Mode
Sets an internal grid flag which may be useful for building blocks aiming to perform more optimized calculations if a grid is supposed to be permanently orientated in one way (horizontal for example). Note: this feature does not constrain the grid's orientation (if you use this flag it is supposed that the grid's orientation will never change).
By now, there's no default BB that take this flag into account, but it could be used to optimize some custom grid building block (coded with the SDK).

Priority
Sets the priority of a grid when several are present. This feature is used in building blocks like Get Square From 3D Pos or Switch On Square if several grids overlap. Note: it has no effect on the Layer Slider building block.

Grid Cross
Large arrows are for adding columns/rows, and small white arrows are for deleting columns/rows.

Layers

Layer List (top-left)
List of all layers applied to the grid.

    • Adding a registered layer type:
      Drag the layer from "Global Layer List" to "Layer List". Now the grid can contain information of this type (e.g.: information regarding danger, or obstacles)
    • Show/Hide a layer:
      Select layer(s) you want to hide/show, and click the eye item.

      Note: you can also change the layer type color in the Layer List as if you were in the Global Layer List.

Global Layer List (top-right):
List of all registered layers. Note: if a registered layer type isn't applied to any grid, it will not be saved, and so will not be found when reloading.

    • Registering a new layer type:
      Right-click and select New Layer Type
    • Renaming a layer type:
      Select the layer type, and press F2 (if the new name is already in use, it will not be registered and the old name will remain)
    • Changing a layer type color:
      Select the layer type, right-click and the Color Box will automatically appear.
    • Changing a layer type parameter type:
      Right-Click and choose between "Integer" and "Linker".

      Note: the "Param Type" column is set by default to "Integer", which means values stored in each square of a layer will be an integer. Integers are currently the only parameter types allowed and up to a limit of 255. Type "Linker" is used for path finding.

Classification

Classifications List
List of all classifications applied to the grid. As classification are attributes, this list match the list of attributes from the "Grid Classification" category that was given to the grid. Therefore, you can use the Attributes Mode to add or remove "Grid Classification" attributes to the grid.

Global Classification List
List of all registered grid classifications (attributes that can be found in the "grid classification" attribute category).

    • Registering a new classification
      Right click and choose "New Classification". Note: Once a grid classification has been registered, it is accessible in the Attributes Mode, enabling you to apply this attribute to any object (Character, Frames, 3D Entity...). If you create a new classification named "Dwarf" and attribute it to an object, the object will now only be affected by Dwarf grids (if classification is named "Dwarf") and by "- Default Grid Class -" grids.
    • Renaming a Classification
      Select classification, and press F2 (if name is already used, renaming will have no effect, and keep the name as it is)

Note: Since "Grid Classification" are attributes, and since unused attributes are not saved, if you did not apply the classification to a grid or object, the grid classification will disappear when reloading.

Currently no standard BB that takes this flag into account; however, you can write a custom BB using the SDK that takes advantage of this flag (e.g. you could create BB that would affect only Dwarf grids).


Group Setup

There are no parameters specific to a Group. The only relevant Setup mode for a Group is the Attribute mode.


Level / Scenes Setup

Level / Scene Setup

Colors

Ambient
Base environment color which is added to scene light color.

Fog
Base fog color, which will modulated depending on fog settings or camera's position.

Background
Color used to clear the screen on every redraw.

Fog Settings

Type
Can be Exponential, Exponential Squared, Linear. Only Linear is commonly supported. Select None to deactivate the fog.

Fog Start
Distance from the camera's viewpoint to where the fog begins. It must be smaller than Fog End.

Fog End
Distance from the camera's viewpoint to where the fog ends. It must be greater than Fog Start.

Fog Density
Used by the Exponential mode. Not supported by some 3D cards for now.
Density curve, changes the fog aspect along distance. This setting is dependent on the driver and graphics card used.

Scene Start and Other Settings

Use Settings at Scene Start
Tells the renderer if the environment settings must be set when the scene is launched. If not set, all other parameters in the setup will have no effect. Useful when switching between scenes by using building blocks.

Background Image
Use the drop-down box to choose a texture to be set as a background image. The texture will be stretched to the window size, whatever the size is. Set to None to disable the background image.

Starting Camera
The scene can activate a camera when launched. Set to None to disable this feature.


Light Setup

3D Properties

Position
Coordinates expressed in the world coordinate system, and in the local coordinate system if the Light has a parent.

Orientation (Directional and Spot type Lights only)
Orientation expressed in degrees (Euler angles) in the world coordinate system, or in the local coordinate if the Light has a parent.

Light Properties

General Light Properties

Show in player mode
If set, the light is visible in player mode.

Specular
Adds a highlight to an illuminated object (if the material has the specular option tuned on). Specular is an additive affect that can give metallic effects or give a more realistic looking to water or glass materials. It takes also a little more time to be processed.

Type
Select the light type under the drop-drown box. Virtools uses three types of Light. Directional Lights are slightly faster than Point Light sources, but Point Lights have a better appearance. Spot lights offer interesting visual effects but take more processing time than the other types of lights.

  • Point
    The light is projected in all directions from a point source. This is similar to a domestic electric light bulb.
  • Spot
    A cone of light is emitted and only objects within this cone are lit.
  • Directional
    A directional light is projected. This is equivalent to using a point source at an infinite distance. This is similar to the sun seen from a human scale.

Target (Spot Type Light only)
The Target of the current Spot Light. To choose a different Target, select another element from the list.

Influence Properties

Note that the parameters Range and Show Influence are not available for Directional Type Lights.

Active
State of the light. This acts like a real light switch.

Color
Defines the red, green and blue components of the light. Each component can take a value from 0 to 255. The default is 255, 255, 255 (white).

Range
Defines the radius of the lighting area. The default value is 100.

Show influence
If active, shows the light's representation cone in the 3D Layout.

Attentuation Properties

Defines the attenuation factor. The light intensity falls off more quickly with distance if this factor is increased. Note that Attentuation is not avalilable for Directional Type Lights.

Constant
Changes the lighting factors, values between 0 and 10 can be entered. The default is 1.

Linear
Changes the lighting factors,Values between 0 and 10 can be entered. The default is 0.

Quadratic
Changes the lighting factors,Values between 0 and 10 can be entered. The default is 0.

Spot Cone Properties

The following paraneters are avialble for Spot Type Lights only.

Hot Spot
Sets the value of the hot spot of the light. Values between 0° and 180° can be entered.

Fall Off
Sets the light fall off rate. Values between 0° and 180° can be entered.

Fall Off shape:
Sets the value of the light fall off shape. Values between 0 and 10 can be entered.

In the central cone, light intensity is more or less the same, whereas between the two cones, intensity falls according to the ‘fall off’ curve.


Material Setup

Main Material Properties

Color Parameters
(Click a color parameter to open the Color Box dialog to change the color properties.)

    • Ambient: multiplied by the Scene Ambient color.
    • Diffuse: default surface color, dependent on any Lights in the Scene.
    • Specular: used to make a surface look shiny (a metallic effect for example) by making highlights that 'reflect' light.
    • Emissive: self-illumination color of an entity; not modified by any other parameter.

Alpha (visible only in Transparent and Custom modes)
Sets the global transparency factor. The range is between 0 (completely transparent) and 255 (opaque). Note this parameter is dependent on valid blending modes; if no valid blending mode is set, this parameter has no effect.

Power
Determines the strength of Specular highlights. Note that Specular highlights are only possible if a Scene contains at least one Light, and if that Light has the Specular flag activated.

Mode

Mode
Three modes that display only relevant parameters are proposed in addition to a Custom mode that displays all parameters.

    • Opaque: the Material is fully opaque.
    • Transparent: simple alpha based transparency, with an alpha tweaking value.
    • Mask: Mode for opaque, outlined objects (e.g. a 3D Sprite used in Billboard mode to represent a tree).
    • Custom: all available parameters (for advanced users).

Both Sided
Forces the render engine to render both faces of an element, effectively doubling the number of triangles the rasterizer has to draw. Normally the render engine only draws the front face of an element as the the back face is not visible (backface culling).

Fill Mode
Defines how the render engine draws faces.

    • Point: draw only vertices.
    • Wireframe: draw edges between the vertices.
    • Solid: fills the areas created by the edges between vertices.

Shade Mode
Sets the light calculation mode for faces using this Material.

    • Flat: all pixels are lit with the same light color.
    • Gouraud: the light color is linearly interpolated between vertices.

Used By List and Texture Properties

Used By

A list of all the elements curently using the Material. Double-click or right-click an and select Show Setup to go to the setup for that element.

Texture Properties

Note that Texture properties only appear if the Material uses a Texture.

Texture
Name of the Texture currently used. To change the Texture, select another from menu. Click [image] to go to the Texture Setup.

Texture Blend
Sets the Texture copy mode. Note that Mask blends are supported by DirectX 5 and later only; at the time of writing no graphics cards currently support these modes.

    • Decal: Texture will not be blended with other surface color parameters except for the specular highlight.
    • Modulate: Texture will be blended together with every other color parameter.
    • DecalAlpha: blends alpha channel with surface color values.
    • ModulateAlpha: behaves as Modulate except that alpha channel is blended as well.
    • DecalMask: limited support.
    • ModulateMask: limited support.
    • Copy: behaves as Decal mode.
    • Add: adds shading to the texture pixels.

Filter Min/Mag Modes
 Texel interpolation method (a texel is a plain, unaltered texture pixel). Min stands for Minimization (i.e. texture is reduced onscreen) and Mag stands for Magnification (texture is enlarged onscreen). Note that the Mip modes work only if you have generated a MipMap for the Texture (Mip Levels must be set to Automatic in Texture Setup).

Filter Min
Available modes are:

    • Nearest: copy the nearest texel.
    • Linear: Bilinear interpolation filtering. A weighted average of a 2×2 area of texels surrounding the desired pixel is used.
    • Mip Nearest: Nearest-point mipmap filtering. The rasterizer uses the color from the texel of the nearest mipmap texture.
    • Mip Linear: Trilinear mipmap interpolation. The rasterizer linearly interpolates pixel color, using the texels of the two nearest mipmap textures.
    • Linear Mip Nearest: same as Mip Nearest, with Bilinear interpolation filtering.
    • Linear Mip Linear: same as Mip Linear, with Bilinear interpolation filtering.
    • Anisotropic: Anisotropic texture filtering. corrects distortion visible in the image of a 3D object whose surface is oriented at an angle with respect to the viewing plane.

Filter Mag
Only Nearest, Linear and Anistropic are available, as described above are available.

Address Mode
Describes how the texture mapper behaves when an texel coordinate goes out of the buffer. Possible values are:

    • Wrap: given a coordinate C, it becomes abs(C mod 1) when going above 1 or under 0. See also the Texture Wrap settings in the Mesh Setup.
    • Mirror: given a coordinate C, it becomes 1-C when going above 1 or -C if under 0.
    • Clamp: the coordinate is restrained to [0-1] interval, for values outside the interval the color is set to the color of the border. Note that this mode is not widely supported by graphics cards.
    • Border: same as clamp except that the color can be defined by the user.

Perspective Correct
Enables perspective correction, a technique used to avoid distorting a Texture applied to a model that faces away from a Camera. Note that most graphics card enable perspective correction by default (in which case this parameter has no effect).

Border Color (only visible when Address Mode is 'Border')
Defines the border of the material (click to open the Color Box).

Alpha and Custom Properties

Alpha Test
If set, the alpha channel will be used in such a way that the 'Alpha Test Function' combined with the 'Alpha Ref Value' will decide which pixels should be visible. If Alpha Test is not selected, you still can obtain alpha texture transparency by using a blending mode including alpha, or by using Color Key in the Texture Setup.

Alpha Test Function
Choose between Never, Less, Equal, Less Equal, Greater, Not Equal, Greater Equal, Always. These operations determine if the alpha channel pixel (gray pixel) must be greater than, less than, ... the 'Alpha Ref Value' for the texture pixel to be visible.
Note: Once a pixel is said to be renderable (i.e. the testing function returns TRUE), it is is still dependant on the alpha pixel value.

Alpha Ref Value
The threshold value that determines if a pixel should be drawn or invisible.

Blend
Activates blending (transparency feature). If Blend is not selected, the Alpha (Main Material Properties above) and Source/Destination Blend (directly below) parameters are not displayed.

Source Blend (visible only if Blend Mode is enabled)
Sets surface's source blending coefficient. Supported blend factors are as follows (RGBA values, with s and d representing source and destination components respectively):

    • Zero: 0, 0, 0, 0.
    • One: 1, 1, 1, 1.
    • SrcColor: Rs, Gs, Bs, As
    • InvSrcColor: 1–Rs, 1–Gs, 1–Bs, 1–As
    • SrcAlpha: As, As, As, As
    • InvSrcAlpha: 1–As, 1–As, 1–As, 1–As
    • DestAlpha: Ad, Ad, Ad, Ad
    • InvDestAlpha: 1–Ad, 1–Ad, 1–Ad, 1–Ad
    • DestColor: Rd, Gd, Bd, Ad
    • InvDestColor: 1–Rd, 1–Gd, 1–Bd, 1–Ad
    • SrcAlphaSat: f, f, f, 1 where f = min(As, 1–Ad).
    • BothSrcAlpha: Obsolete mode. Use SrcAlpha/InvSrcAlpha instead.
    • BothInvSrcAlpha: Uses InvSrcAlpha/SrcAlpha as blend modes. The destination blend mode is overidden.

Destination Blend (visible only if Blend Mode is enabled)
Sets surface's destination blending coefficient. See above for available factors.

Z-Buffer Write
Allows Faces using this material to write to the Z-Buffer while rasterizing. Note that if Z-Buffer Write is not selected, face sorting may be wrong.

Z Compare Function
Test function used when writing to the Z-Buffer. If the test fails, the pixel will not be written to the buffer.

Effect

Creates special effects that otherwise often involve multiple passes or processing by behaviors. Note that a graphics card or rasterizer may not support all or any of these effects.
DX7 and DX8 rasterizers support all the effects and only depend on the graphic card's capabilities.
When you select an effect, a short description and an example image displays.

Existing Effects :

    • Texture coordinates Generation and
    • Texture coordinates Generation width Referential
      • Instead of using a building block to calculate texture coordinates these effects use the graphic card hardware to automatically generate the appropriate texture coordinates.
    • Environment Bump Mapping
      • Requires a Bump Texture and a Environment Texture.
    • Combines 2 Textures and Combines 3 Textures
      • Combines the base texture and 1 or 2 texture using DirectX combine style. Texture coordinates are generated according to a given parameter.

For effects that require one or two Textures to work, additional parameters (such as a Float representing the amplitude for a Env Bump Map, or a referential for the "Texture coordinates Generation width Referential ") appear allowing you to fine-tune the effect.

Shaders

On of the newest feature of Dev, a Shader is a small piece of code that describes the way a surface is rendered. Nowadays, a Shader is a small piece of code executed by the GPU (on certain 3D graphics cards) for each vertex and/or each pixel, hence the terms Vertex Shaders and Pixel Shaders. Shaders must be created in the Shader Editor.

Once created in the Shader Editor, a Shader is assigned to a material by selecting it in the Material Setup's shader combo box. This combo box is located in the Shader area (the right side of the Material Setup menu bar).

The Shader Setup button will bring to front the shader editor and select automatically the shader used by this material.

Once a Shader is selected in the Material Setup shader combo box, a button named Shader Params appears to the right of the combo box.

Once clicked, this button opens the Shader Params modeless dialog box. This dialog box contains two permanent parameters:

  1. Technique - Lets the user choose which technique should be executed by this shader.
  2. Find Next Valid Technique- Lets the user decide whether that following techniques should be used as a replacement if the chosen technique isn't supported by the hardware.

once a shader is selected, the Shader Params button appears on the right

All other parameters of the Shader Params dialog box are linked to the exposed variables defined as Manual in the Shader program.

Note: This dialog box is modeless, meaning the dialog does not need to be closed in order to give focus to the rest of the interface.

Furthermore, if you add exposed manual parameters in the shader program and compile it, the Shader Params dialog box will update automatically to reflect changes.

Be sure to read Shaders Inside Virtools for more information.


Mesh/Patch Mesh Setup

Mesh Properties

Progressive Mesh (not available for Patch Meshes)
Activates Progressive Mesh and builds the optimized Mesh Structure (this can take several seconds for large Meshes).

Vertices (Progressive Meshes only)
Number of vertices currently being rendered. Use the slider to test the decimation of your Mesh, and to calculate the minimum number of vertices the Mesh should always contain.

GeoMorphic Transition (Progressive Meshes only)
Activates Geomorphic Transition and sets the level of decimation. The default value of 0 uses dichotomic decimation, e.g. a 500 vertex Mesh morphs from 500 vertices to 250, then from 250 to 125, and so on. If decimation is set to 50, the same Mesh goes from 500 vertices to 450, then from 450 to 400, etc.

Iterations (Patch Meshes only)
Number of iterations to evaluate the patch Mesh. The higher the count, the more precise the resulting object, but also the slower the rendering. Note that the Virtools Dev render engine (CK2_3D) cannot process Patch Meshes with more than 65,000 iterations.

Texture Wrap
Sets the wrapping mode for any Textures the Mesh uses. This can be useful to correct incorrect Texture mapping. Note however this parameter works with DirectX only and has no effect in OpenGL.

    • None: no wrapping is performed.
    • U: wraps along the horizontal axis only.
    • V: wraps along the vertical axis only.
    • Both: wraps along both (UV) axes.

Lit Mode
Sets the lighting mode.

    • Lit: Meshes depend on scene lighting to be visible.
    • Prelit: Mesh vertices store their own colors (diffuse/specular) and do not need any lighting to be visible. In fact real-time lighting has no effect on prelit Meshes. Typically you create prelit Meshes in a modeling application, however you can add vertex color to Meshes in Dev with the Precompute Lighting and Set Vertex Properties BBs. The advantage of prelit Meshes is to save save CPU or GPU rendering time. Note that if a Mesh is prelit, any additional channels are automatically prelit.

Mesh Info

Vertices
Number of points in the Mesh.

Faces
Number of triangles in the Mesh.

Channels
Number of additional Materials blended over the default Material.

Line Count
Number of line primitives in the Mesh.

Consolidate
Consolidates the Mesh, i.e. removes faces that are not used. A report that tells you how many faces were removed (if any) is displayed in the Event Log.

Stripify
Activates Mesh stripification (the rearrangement of the vertices of a Mesh into a strip order to optimize the render process). Note that if you select this option, the Mesh is stripified each time it is loaded, i.e. the stripify information is not currently saved (in an .NMO or .CMO). As stripification can take a long time to calculate for large Meshes, you are advised to use this option selectively and for Meshes that have between 200 and 2000 faces.

Geometry Info

Radius
An imaginary sphere that include every point of the Mesh.

Bounding Box
An imaginary rectangular box enveloping the entire Mesh. The box is locally oriented.

Barycenter
The weight center of the Mesh.

PatchMesh Info

Control Points
Total number of control points used to define the Patch Mesh.

Edges
Number of edges used to link control points.

Patches
Number of patches that define the Mesh. Each patch is defined by 4 control points; a control point can however be shared by several patches.

Texture Vertices
Total number of UV coordinates (Texture Coordinates).

Used By List and Materials

Used By
A list of elements (3D Objects or Bodyparts) that use this Mesh. You can view the entity's setup either by double-clicking on it or by selecting 'Show Setup' in the Shortcut Menu.

Channels
A list of additional Materials to blend with the main Material or other Material Channels.

    • Material Name
    • Active: enables or disables the Channel.
    • Lit Mode: sets the lighting mode, [image] = Lit and [image] = Prelit. Note that if you set the Lit Mode above to Prelit, then this flag has no effect - all channels are prelit.
    • Src/Dest Blend: the blending mode, double-click to edit.
    • Pass:
      • the pass in which that particular effect is rendered; the number of passes required to render all effects is the last number in this column.

Note that the ability to render several Channels is dependent on the API (version of rasterizer) used, the performance of the graphics card, and the complexity of the blending operation. As Channels put a large strain on graphics cards, you are advised not to use more than 8 Channels.

Add a material in Channel list

  • Drag materials from the Level Manager into the list.
  • Right-click in the Channel list and choose Add Material, select the material in the combo box of the dialog.

Remove a material from Channel list

  • Right click on a material in the Channel list and choose 'Remove Channel'.
  • Select a material in the channel list and press DELETE.

Materials Used
A list of Materials used by the Mesh. You can view a Material's setup either by double-clicking it or by selecting 'Show Setup' in the Shortcut Menu. You can replace Materials by dragging them from the Level Manager onto the 3D Entity in the 3D Layout: the Material for the Mesh that lies directly under the mouse is replaced.


Place Setup

3D Properties

Position
 Place coordinates expressed in the world coordinate system, and in the local coordinate system if the Place has a parent.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, and in the local coordinate system if the Place has a parent.

Scale
Scale values in the world coordinate system, and in the local coordinate system if the Place has a parent.

Set As Unit
Scales the mesh vertices in order to set the scale to 1:1:1.

Portals and other Places

Visible Place
A Place seen from the current Place. Places can always be visible by setting the corresponding portal to None.

Through Portal
Portal through which a Place is seen. You can add multiple portals for a Place.

Active
Toggle activation status for a Portal. Activated Portals are blue whereas inactivated ones are red.

Context Menu

Attach New Place
Creates a new link to a portal. Default portal is set to None.

Remove Place
Removes this link to portal.

Setup
Pop-up corresponding portal or place setup depending if the menu was called over a place or over a portal in the list.


Portal Setup

Position
Coordinates expressed in the world coordinate system, and in the local coordinate system if the frame has a parent.

Orientation
Orientation expressed in degrees (Euler angles) in the world coordinate system, and in the local coordinate if the frame has a parent.

Scale
Scale expressed in the world coordinate system, and in the local coordinate system if the frame has a parent.

Pickable
If selected, .


Sound Setup

General Sound Properties

Sound Features

Sampling rate
Sampling rate of the sound, in Hertz.

Sample Size
Sample size of the sound, in bits (i.e. 8 or 16).

Channels
Number of voices in the sound (1 or 2).

Duration
Sound duration (in minutes:seconds:milliseconds).

Streamed
Enables streaming - a initial 2 second buffer is loaded into memory and subsequent sections of the sound file are read from disk when needed. If you do not choose streaming, the entire sound file is loaded into the system memory.
Note: You cannot use streaming with the Play Sound Instance BB.

Save Options
Selects the way Dev saves sound files.

  • External: Only saves a reference to the sound file (filename and path). The sound files must be placed at the same level as the composition file or in a subfolder.
  • Global Settings: Uses default settings, which can be changed in the General Preferences.
  • Original File: The sound file is saved in the composition.

Type

Background
Sound is played as a background 2D sound; there is no notion of position or orientation.

Point
Sound is played in 3D as the sound now has an origin/source and a listener; the sound can have spatial effects (several additional parameters are available for Point Sounds).

Distance to listener (Point Sounds only)
Displays the distance of the sound to the listener, in world units. You can designate a Listener with the Set Listener BB.

Sound Position (Point Sounds only)
Displays the position of the sound origin, expressed in the in the world coordinate system.

Relative Angle (Point Sounds only)
Displays the angle between the center of the Sound Projection Cone and the listener.

Misc

Loop
Starts replaying the sound as soon as it finishes.

/ [image] /
Plays, pauses or stops playback of the sound.

2D Properties

Gain
Sets the gain for the sound, in effect reducing the volume of the sound. 1=original volume, 0.5=half volume, 0=no volume.

Pitch
Changes the pitch (playback speed) of the sound. 0.5=lowest pitch, 2=highest pitch.

Pan (Background Sounds only)
Controls the panning of the sound, that is the relative volume between the left and right audio channels. -1=full left, 0=center, 1=full right.

3D Properties (Point Sounds only)

The following parameters apply to Point Sounds only.

3D Properties

Attached Object
Attaches the origin of the sound to an object. __NULL__ means the sound is not attached.

Relative Position
Specifies the position of the sound, in the referential of the attached object (or in the world coordinate system if the sound is not attached to an object).

Relative Orientation
Specifies the orientation of the sound, in the referential of the attached object (or in the world coordinate system if the sound not attached to an object).

Sound Projection Cone

Inside Angle
Sets the size of the angle for the inside sound cone.

Outside Angle
Sets the size of the angle for the outside sound cone.

Outside Gain
Sets the gain (i.e. by how much the volume of the sound should be reduced) for sounds that are outside the sound cone.

Min and Max perception distances

Min
Sets the distance at which the sound is at its loudest; the sound volume does not increase even if the listener gets closer to the sound source.

Max
Sets the distance at which the sound is no longer attenuated; i.e. beyond this distance the volume of the sound does not go any lower.

Current Value
to complete.


Texture Setup

Image Format

Texture Information

System Memory Format
Displays texture information concerning the Size, Color Depth and Mask Description as it is stored in system memory.

Desired Video Format:
Display texture information concerning the Color Depth and Mask Description as it is stored in video memory.
If an asterisk appears at the right of the texture information, the texture can be used with this desired texture format in video memory (thus the 'Video Memory Information' will be the same as the 'Desired Video Format'). If there's no asterisk at the right of the texture information, the closest available texture format supported by the user's 3D card will be used.
The 'Desired Video Format' is saved inside the .CMO file. Therefore, even if the 3D card used to develop the composition doesn't support the desired texture format, the end-user of the composition will be able to see the texture in the desired texture format if its 3D card is good enough.

Video Memory Information:
Displays information about the file as stored in the video memory: height x width in pixels, color depth in bits, video format in bits per argb component (space taken up in video memory). Note that for AVI files only the current frame is stored in the video memory, and subsequent frames are streamed.
Note: you can see the total video memory size used by all image files in the Profiler window.

Slot Navigation and Modification

First
Displays first image slot.

Prev
Displays image just before current slot.

n/n
Slot currently selected/number of slots in image file.

Next - N
Displays image slot just after current slot.

Last - P or SHIFT+N
Displays last image slot.

Add Texture - O
Opens a dialog box so that you can browse to a folder and choose an image file to load. The image you load, which must be of the same height and width, is stored in a new slot. Alternatively, you can add an image file to a new slot by dragging an image from a Data Resource into the preview window while holding the SHIFT or CTRL key.

Remove Current Slot
 Removes the current slot, but only if there are 2 or more slots.

Texture Properties

Save Options
The texture can share the default save settings (see General Preferences), or use an independent save format. Selection types are:

    • Raw Data:
      Texture is not compressed, it's saved as it is (32 Bit ARGB) (this usually take a lot of space in the cmo file, depending on the size).
    • External:
      Only a reference to the original texture file is saved inside the cmo file (i.e. the path and the filename).
    • Specific Format:
      The texture is saved inside the cmo file by taking advantage of the compression of one of the image savers. Use the button below to change the saver type.
    • Global Settings:
      Uses default settings, which can be changed in the General Preferences.
    • Original File:
      The texture is saved in the cmo file as it was in the source file (for example,using this type, an AVI file will be stored inside the cmo file, and you won't need the original file anymore).

Mip Levels
This sets how many mip maps the engine may use (the maps are automatically generated). You can either let the engine to automatically select the maps count (which will be the maximum map count your 3D card can support), or you can choose on the list how many maps do you want. Selecting None will disable the mip-mapping feature.
WARNING: To be able to use mipmap you need also to set the 'Filter Min' mode of the material to some mode that include mip-mapping (like 'LinearMipLinear' or 'MipLinear'). Usually, the material's 'Filter Min' mode is the only one that need texture mip-mapping.

Cube Map
Enables the storage of cubemaps. 6 slots are allocated when cube map is selected, each slot representing one of the face of the cube map (right,left,up,down,front,back).

Color key transparency
Allow selection of a transparent color (invisible color). Choose the color with the Picking Tool [image]. WARNING: Activating the color key will destroy your alpha channel image!

Alpha Picking Threshold
This threshold is used only for picking purpose (and only if the texture owns an alpha channel texture). When you pick an object on an area that is filled with this texture, Virtools will consider the picking as successful only if the picked alpha channel texel is greater than the 'Alpha Picking Threshold'.

Used By
A list of entities using this texture. You can view an entity's setup by double-clicking on it or by selecting 'Show Setup' in the Shortcut Menu.

System Caching
This combo box, located on the right of the texture's Video Memory Information, is available when Save Options are set to Original file or External. Selection types are:

    • Procedural:
      The texture is stored in a raw 32 bit (ARGB) per pixel format for easy read and write operations. This is usefull when you want to alter the texture with a VSL script for example (Texture.SetPixel).
    • Video Shadow:
      The system memory format is a straight copy of the video memory format.
    • Discard:
      Texture is discarded from system memory, and cannot be drawn in the setup.

Preview Windows and Shortcut Menus

There are two preview windows that allow you to zoom in and out on the Texture itslelf (left), or an optional Alpha Channel (right). Right-click a preview window for additional options.

Texture Preview Window

Add new slot - O
Opens a dialog box so that you can browse to a folder and choose an image file to load. The image you load, which must be of the same height and width, is stored in a new slot. Alternatively, you can add an image file to a new slot by dragging an image from a Data Resource into the preview window while holding the SHIFT or CTRL key.

Replace slot - R
Opens a dialog box so that you can browse to a folder and choose an image file to load, replacing the current slot. The image you load must be of the same height and width, unless the Texture only has a single slot. Alternatively, you can replace a slot by dragging an image from a Data Resource into the preview window.

Remove slot
Removes the current slot, but only if there are 2 or more slots.

Reload slot
Reloads the current slot. This is useful if the slot has been modified by building block since loading.

Save slot - S
Saves the current slot to an image file.

Resize Slot
Change the size of the texture (Warning : this change the size of all the slots). It may be useful to use this feature if the size of the texture is not a power of 2.

Invert Slot
Invert the color of each pixel of the current slot.

HeightMap => Normal Map
Computes a normal later stored in RGB for each pixel according to its neighbours. A Dotproduct3 effect needs a bump texture stored in this format to work.

HeightMap => Bump Map
Computes the Du & DV offset for each pixel according to its neighbours. A bump effect needs a bump texture stored in this format to work.

Zoom In/Out - +/-
Changes the zoom factor. Mininum zoom is 7%, maximum is 5000%.

Zoom 1:1 - /
Changes the zoom factor so that the slot is displayed at it's real size, pixel for pixel.

Zoom Best Fit
Changes the zoom factor so that the entire slot is visible in the preview window.

Interactive zoom
Hold the right mouse button over the sprite and move the mouse around. You can scroll a zoomed image by holding and moving the left mouse button.

Alpha Channel Preview Window

Replace alpha
Opens a dialog box so that you can browse to a folder and choose an image file to load, replacing the current Alpha. Alternatively, you can replace a slot by dragging an image from a Data Resource into the Alpha Channel preview window. The color channels of the image are mixed together to produce a transparency mask (Alpha Channel). You can also select the channel (red, green or blue) you want by holding SHIFT or CTRL while dragging the image from the Data Resource.

Set alpha to opaque/translucent/transparent
Changes the Alpha Channel value to 255, 128 or 0 repectively.

Invert alpha
Inverts the Alpha Channel value: new value = 255 - old value.

Save Alpha Channel
Opens a dialog box allowing you to save the Alpha Channel image to file.

Interactive zoom
Hold the right mouse button over the sprite and move the mouse around. You can scroll a zoomed image by holding and moving the left mouse button.


Duplicate Names Found

Overview

The Duplicate Names Found window pops up whenever you add new elements to your composition and duplicate file names are found in the Level Manager, for example when you merge compositions, import files, or drag and drop already existing elements into your scene from a data resource.

Each duplicate element is presented in an expandable list, and has four possible action values available in the contextual menu (right click). Changing the object category's action value will assign that value to all elements contained in the category.

Ignore

  • Adds to Level Manager with the same name.

Rename

  • Rename by adding an incremental number and adds to the Level Manager.

Use Current

  • Use the existing element in the Level Manager. (No element is added)

Replace

  • Replace the existing elements in the Level Manager with the one being added.

Notes

The first two options add new elements to the Level Manager, while the combined use of Use Current and Replace allow you to selectively replace certain elements like meshes.

Make sure when replacing characters that the hierarchy remains the same and that body parts and animations all keep the same name.


Behavioral Objects

For Scripts and Behaviors to be useful, they must be applied to Behavioral Objects. This section describes the behavioral objects you will come into contact with in the Virtools Dev interface, and is organized as follows:
  • Name (CKClassName), optional subclass
    The name of the element, with the CKClassName as it appears in the Virtools SDK.

  • Class Hierarchy
    Position of the element in behavioral object branch of the Virtools class hierarchy.

  • Setup
    A link to the setup for that element, instances of that element and element subclasses.

  • Initial Conditions
    The information that is saved when you set Initial Conditions for elements of that class.

  • Remarks
    Important information about that element.

The base class from which all behavioral objects derive is CKBeObject.

For these pages of this section to make sense, make sure you have first read the Concepts section, in particular the pages on:

  • Elements, Classes, and Object Oriented Design

  • The Elements of a Composition


2D Entity (CK2dEntity)

Class Hierarchy

Behavioral Object > Render Object > 2D Entity

Setups

2D Frame

Initial Conditions

2D Entity: Position, Screen size, Z_order.

General Remarks

The CK2dEntity class provides the basic methods used to manipulate 2D Frames and 2D Sprites (CKSprite and CKSpriteText): Position, Size, Visibility.

Two modes, Homogenous and Absolute, are available for describing or setting the position and size of a 2D Entity. With Homogeneous coordinates, the 2D Entity's position and size are given in a normalized range (0..1) where 0 is the left corner of the screen and 1 is the right corner. This mode ensures that whatever the render context size, a 2D Entity will always have the same proportional position and size. The other mode, Absolute (or screen) coordinates specifies size and position in actual pixels.

Z order and Rendering

The destination and source rectangles define what part of a 2D Entity can display; the Z order value for a 2D Entity defines if the 2D Entity should display, wholly, partially or not at all. The source rectangle is the part of the Texture to display. If Cropping or UVMapping is not activated, then the source rectangle is the entire Texture. The destination rectangle is the position of the 2D Entity onscreen, expressed in absolute (pixels) or homogenous (percent) coordinates. In addition to setting these parameters in the 2D Frame or 2D Sprite setups, you can also set either parameter at run-time via the Set Rectangles BB.

2D Entities are drawn according to their Z order value (lowest Z order drawn first, highest Z order drawn last). The Z order is only used to sort 2D Entities themselves, and is not used to determine if a 2D Entity should be drawn before or after a 3D Entity. In fact 2D Entities are always drawn after 3D Entities unless the Background Sprite parameter is selected, in which case the 2D Entity is drawn before any 3D Entities.

Note that even if a 2D Entity is hidden, the 2D Entity remains active and so behavioral processing for that element (i.e. processing scripts) still continues.

Cropping (UVMapping)

Cropping sets the source rectangle and can be used to display only a subpart of a 2D Entity. For example in a 32x32 sprite setting a cropping rectangle of (0,0) - (16,16) will only display the top left corner of the sprite. Note that in the setup for 2D Sprites (a 2D Sprite derives from a 2D Entity) this parameter is called UVMapping and the rectangle is given in normalized coordinates and not pixels.

Hierarchy

Several options are available if the 2D Entity is parent to other 2D Entities or is a child element itself. You can choose to clip a 2D Entity to its parent.

You can also choose how the entity will stick to its parent when this parent will be resized. You can choose to stick to the left, to the right, to the top and to the bottom. All these flags are cumulative: you can stick top/left, but you can also stick left/right, which means be centered.

2D Frame

A 2D Frame an instance of the class 2D Entity. A 2D Frame is a 2D entity drawn on the screen to which a Material (and so a Texture) can be attached. Note that 2D Frames share the same setup as 2D Sprites, with some buttons disabled or hidden. The Sprite/Memory Format information is not available for 2D Frames, this is accessed through the Material Setup instead.

2D Frame v. 2D Sprite

You are recommended to use 2D Frames instead of 2D Sprites wherever possible. This is because:

  • 2D Frames are drawn slightly more quickly than 2D Sprites of a similar size and with less processing.
  • 2D Frames offer more functionality through Materials and Textures.

A Material can be associated to a 2D Frame, so you can manage the Material freely. This is not possible with the image associated with a 2D Sprite (a 2D Sprite has neither a Texture, nor a Material). The only advantage of using 2D Sprites instead of 2D Frames is that the image associated with the 2D Sprite can have a a length or width that is not to the power of 2 (e.g. a 553 x 46 pixel image can only be rendered as a 2D Sprite).

To create a 2D Frame, click the Create 2D Frame icon of the 3D Layout creation tools.


2D Sprite (CKSprite) and Sprite Text (CKSpriteText)

Class Hierarchy

Behavioral Object > Render Object > 2D Entity > 2D Sprite > Sprite Text

Setups

2D Sprite

Initial Conditions

2D Sprite: All Bitmap slots, Color Key, Current Slot, Save Options.

Remarks

2D Sprite

A 2D Sprite is a 2D Entity that can display images that are not to the power of 2. A 2D Sprite has neither a Material nor a Texture. For this reason, you are recommended to use 2D Frames instead of 2D Sprites wherever possible. This is because:

  • 2D Frames are drawn slightly more quickly than 2D Sprites of a similar size and with less processing.
  • 2D Frames offer more functionality through the possibility of controlling a Material and/or a Texture.

However 2D Sprites have one important advantage in that the image associated with the 2D Sprite can have a length or width that is not to the power of 2 (e.g. a 553 x 46 pixel image can only be rendered as a 2D Sprite). Note however that a 2D Sprite will take up the equivalent memory space of the next squared power, i.e. a 2D sprite of 65 pixels will take up the memory space of an 128 pixel image.

Note that although an AVI (movie) file can be added to a CMO as a 2D Sprite (where each frame of the file considered a slot), you are recommended to add AVI files to your CMO as Textures and instead use 2D Frames (that use the AVI Texture) instead. Note also that AVI playback is defendant on the target machine having the appropriate codec correctly installed.

To create a 2D Sprite, either drag a file from a 2D Sprites folder of a data resource, or drag a file from the Textures folder of a data resource holding down the CTRL key.

Sprite Text

The Sprite Text class derives from the 2D Sprite class and can be used to draw text on screen. Behaviors and SDK methods allow you access to the font, color, background color and transparency settings as well as text alignment. Note that this class is provided more for debugging than for real usage, as updating text at every frame is a slow operation. Much faster display of text that changes often can be achieved using bitmap fonts and Textures (see the BitmapTextDisplay BB for example).


3D Entity (CK3dEntity)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity

Setups

3D Frame
Portal

Initial Conditions

3D Entity: Mesh List, Current Mesh, Animation List, Owner Place, Z order, World Matrix (Position, Orientation, Scale), Parent Entity; Skin Data if available.

Remarks

3D Entity

The CK3dEntity class is the base class for all 3D behavioral objects. The 3D Entity class provides methods for specifying the position, orientation and scale of an element and also allows access to that element's local and world matrix. The 3D Entity class also provides management for a set of potential Meshes and animations.

For elements that derive from 3D Entity, these parameters are usually accessible in the 3D Properties section at the top of the Setup for that element. These parameters can usually be changed at run-time using the appropriate BB.

A 3D Entity can be 'pickable' i.e. a 3D Entity is identified as being 'picked' if the mouse pointer is over it or the user clicks the element for example. If a 3D Entity does not have the 'pickable' parameter selected, any picking attempt results in the 3D Entity being ignored, instead any 3D Entity behind this one will be picked instead (as long as it does have the 'pickable' parameter).

Note that even if a 3D Entity is hidden, the 3D Entity remains active and so behavioral processing for that element (i.e. processing scripts) still continues.

3D Frame

A 3D Frame is a simple instance of 3D Entity that does not have a Mesh. 3D Frames are represented as a cross in the 3D Layout. They are used as helpers, or to track other objects, and are similar to dummies in 3D modeling packages. 3D Frames are also commonly used in Particle Systems.

Portal

A Portal is again a simple instance of a 3D Entity that does not have a Mesh. Portals are represented by transparent blue boxes in the 3D Layout. They are used as connectors between two places (CKPlace). See Place (CKPlace) and Portal (CKPortal) for more information.


3D Object (CK3dObject) and Body Part (CKBodyPart)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > 3D Object > Body Part

Setups

3D Object
Body Part

Initial Conditions

3D Object: N/A (no other data in addition to parameters saved for 3D Entity).
Body Part: IK information, Character to which the body part belongs.

Remarks

3D Object

A 3D Object simply derives from the 3D Entity class, which gives this class its 3D Properties (Position Orientation Scale etc.).

A 3D Object is displayed using a Mesh, called the Current Mesh. A 3D Object also maintains a set of alternate Meshes, these alternate Meshes can be used for example to store the representation of the 3D Entity at different resolutions (LOD) or in different states. The Current Mesh is not necessarily part of this set. This current mesh can be changed at any time.

Body Part

The CKBodyPart class is designed specifically for Character parts and has access to a couple of additional parameters. The setup is the same as for 3D Objects, except for a link to the Body Part's Character.


Behavioral Object (CKBeObject)

Class Hierarchy

The Behavioral Object (often written as BeObject) class is at the top of the behavioral branch of the Virtools Class Hierarchy. See the SDK for more information on the entire Virtools class hierarchy.

Setups

There is no particular Setup for BeObjects.

Initial Conditions

Attributes (if an element has new Attributes since setting ICs, the Attributes are not removed when you restore ICs).

Remarks

CKBeObject is the base or parent class for all elements that can have scripts and attributes (BeObjects).

Instances of BeObjects can have a set of scripts attached to them. The object owns the scripts. The scripts are the behaviors that are activated when the object is installed in the current scene. They are the main starting points of the composition. They declare what the object does at the “beginning”.

BeObjects can send and receive messages. Note there is a one frame delay between sending and receiving a message.

BeObjects can be active or inactive in any scene they belong to. When they are active all their active scripts are processed during the process loop. By default, a BeObject is activated at start.

BeObjects can have “Attributes” attached to them, each attribute has a specific type (or name) and a type of parameter that is associated to. For example you could create a new attribute type called “Health Point” with an associated parameter type “float” and attach it to any behavioral object using the Dev interface or behaviors at run-time.

BeObjects may be grouped together using Groups.


Camera (CKCamera) and Target Camera (CKTargetCamera)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > Camera > Target Camera

Setups

Camera

Initial Conditions

All Data (as shown in the Camera Setup).

Remarks

Camera

A Camera in Virtools is just like a real camera, it represents a viewpoint. Many Parameters found in the real world are also available for Cameras in Virtools, such as the front plane, back plane, field of view, roll, projection type, zoom type, and aspect ratio.

Note that the Field of View (FOV), which controls how much of a Scene is visible, is an angle measured in radians. The Dev interface gives access to the notion of focal length used in photography. For a standard 35 mm camera the conversion formula between field of view and focal length is Field Of View = 2 x ArcTan( (35/2) / Focal Length).

Target Camera

A Target Camera derives from a standard CKCamera, and has a target (a 3D Frame): it always points to its target. When the target is undefined, the Camera behaves like a standard Camera.


Character (CKCharacter)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > Character

Setups

Character

Initial Conditions

All body part data (List + IC for all bodypart), Active Animation, FloorRef and Root.

Remarks

Unique Root, Parent to Body Parts

A Character is a special type of 3D Entity. A Character is defined as a hierarchical set of Body Parts that are all children to a unique root object that gives the Character's position and orientation (optional for orientation). Note that a Character must have a unique root object, otherwise you will experience problems.

FloorRef

A Character normally has an object that acts as a 'floor reference' (FloorRef) - the FloorRef object is used by several BBs to make the Character detect and react to floors, so that a Character actually walks on a surface you have defined as a floor and does not float above it or sink below. The FloorRef must be a child of the root (or be the root object itself) and contain one of three special keywords to be automatically recognized: "FloorRef", "Floor" or "Pas". These keywords are case sensitive and should not be used to name other body parts. Note that it is possible to define a floor ref manually using the Set Floor Reference Object BB.

When creating animations, you should be very careful what you do with the FloorRef. When walking or running, the character should stay at a constant height from the FloorRef object. When jumping, the Character should increase it's distance from the FloorRef object to give the appearance of translation away from the floor. Characters should ALSO have a "stationary root" that only moves relative to the floor reference (e.g. for walking, jumping etc.) but that does not move constantly (i.e. in an idle animation the root should not move). This is very important if you wish to use your Characters with the Virtools Mulituser Pack, or the dead reckoning algorithm used for predicting distributed objects will not work correctly. In short:

  • Make sure the (stationary) root element does not move at all when the character is in its default ('wait' or 'idle' animation).
  • For other animations make sure the root moves a minimum; in a walk animation along the Z axis for example, make sure that the root moves along the Z axis only - there should be no movement on the X or Y axes.

Animations

A Character nearly always has animations (primary and secondary) attached to it. The processing of Character animations always occurs at the start of a frame, before processing behaviors (it is 'pre-process' - see The Virtools Dev Process Loop for more information). Note that the Unlimited Controller BB allows you define 'warping', that is define how one animation transitions into another (e.g. smoothly, at the start of the next animation, break, etc...). In addition to the active primary animation, secondary animations can be played concurrently. If there are body parts that are used by both animations, then the secondary animations take priority over the primary animation (i.e. the appropriate body parts will play the secondary animation and not the primary one).

Note that animations can be shared between Characters. However the two (or more) Characters sharing the animations should have identical or very similar meshes, otherwise the animations may play strangely for the Character for which the animation was not created.


Curve (CKCurve) and Curve Point (CKCurvePoint)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > Curve
Behavioral Object > Render Object > 3D Entity > Curve Point

Setups

Curve

Initial Conditions

List of Curvepoints (+ IC for all curve points), Fit coefficient, Curve steps, Open/closed curve.

Remarks

Curve

Curves are a collection of segments attached by Curve Points to make a single curved line. Curves can be opened or closed. Curves are 3D Entities, and can be made visible in player mode. The Curve Setup allows you to add, insert, edit or delete Curve Points, as well as change properties of the Curve or an individual Curve Point.

Curve Point

Control Points control the shape of a Curve. Each Control Point defines where the curve should pass and how it acts at that point (incoming and outgoing tangents or TCB - Tension, Continuity, Bias - parameters).


Array (CKDataArray)

Class Hierarchy

Behavioral Object > Array

Setups

Array

Initial Conditions

Array Data, Key column information.

Remarks

An Array is a simple structure that holds tabular data in cells formed by rows and columns. Columns define the types of data stored in the Array and the rows contain values. Each cell contains a distinct data element. The data types supported by Arrays include:

  • Integer
  • Float
  • String
  • CKObject (name of the object only is stored)
  • Parameters

You should try to keep to the first four types if possible, as parameters take up around ten times as much space in the system memory as the others. However, shortcuts are only possible with parameters. Parameter shortcuts, copied from Schematic and pasted into an array cell, or copied from an array and pasted into a script, are used to update a value automatically without having to use a building block.

When you create an array, the first column created is by default the key column. A key column, which is a darker color than other columns, may only contain unique entries, which provides an easy way to identify a certain row.

Data contained in an array can be exported to and imported from tab delimited text files via BB. When importing or exporting data to or from arrays, you must take care with the file path. Dev first checks to see if a file location is absolute. If not, Dev then checks whether the path is relative to the executable file (e.g. player.exe), then whether it is relative to the .CMO, and finally relative to a data path defined in the Path Manager. File names must not be more than 64 characters in length and should use underscores instead of spaces in the file name. The path and file name must not exceed 256 characters in total, and if there is a space in the path you should include the whole thing in quotes (for example “c:\my documents\data_file.txt”).

Currently you cannot read or save to a URL, even with an absolute path.


Grid (CKGrid)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > Grid

Setups

Grid

Initial Conditions

Size, Content of each layer.

Remarks

A grid is a 3D Entity made up of squares and layers that store information. As grids are 3D Entities, all properties common to grids and 3D Entities are editable in the 3D Object Setup (e.g. for changing the position, orientation and notably scale of a grid, such as along the X axis).

Grids are used principally for path finding and for triggering events based on a square's value. See the BBs in Grids for more information.


Group (CKGroup)

Class Hierarchy

Behavioral Object > Group

Setups

Group

Initial Conditions

Objects list.

Remarks

Behavioral Objects can be grouped together because they share common attributes or for better understanding of a Scene. A group is simply a list of elements, these elements can be removed or added easily using the Dev interface or BBs at run-time. A Group can contain other Groups.

Note that when you place elements into a group, you are actually only placing a reference of the element and not a copy. So if you delete a group, the objects themselves remain available. Similarly, if you add an Attribute to a Group, it is the group itself that has the Attribute and not the members of the Group.

In addition to grouping elements, Groups are often used at run-time for batch operations (Group Iterator BB) and for simple logic operations (Is In Group BB, Get Nearest in Group BB etc). See the BBs in Level/Groups for more information.


Level (CKLevel)

Class Hierarchy

Behavioral Object > Level

Setups

Level/Scene (shared Setup)

Initial Conditions

Fog, Background Color / Texture, Starting Camera

Remarks

A Level contains all Scenes in a composition (.CMO), with their Places and objects. There is only one Level in a composition, called the default Level. The default Level can be considered as special type of Scene and will be the only scene in a composition unless you specifically create others. As a Level acts as a global container, holding everything that is in a composition, any Place or object present in a Scene is also contained in the default Level.

However, a Scene just references elements from the default Level. E.g. if you delete or change an element in a Scene, the element still exists in the Level as it might be used in a different Scene or in the default Level Scene itself. However, if you delete or change an element in the Level, the element automatically disappears from all Scenes.

Only one scene can be active at a time. However, whenever you create a new Scene, any scripts attached to the Level are automatically copied to the new Scene. This allows you to script a way to change from one Scene to another at run-time.

The Level setup allows you set several render options for the Level (e.g. background color, fog options or starting camera) that can be made active immediately or just when the Level becomes active.


Light (CKLight) and Target Light (CKTargetLight)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > Light > Target Light

Setups

Light

Initial Conditions

All Data (as shown in the Light Setup)

Remarks

Light

A CKLight can be one of three types: spot, directional or point. You can specify a range outside of which objects will not receive any light. Spot lights are controlled by three additional parameters which are the angle of the inner cone, outer cone and a factor that controls the decrease of intensity between the inner and outer cone limits.

Target Light

A Target Light derives from a standard CKLight, and has a target (a 3D Frame): it always points to its target. When the target is undefined, the Light behaves like a standard Light.


Material (CKMaterial)

Class Hierarchy

Behavioral Object > Material

Setups

Material

Initial Conditions

All Data (as shown in Material Setup).

Remarks

A Material holds the surface description for 3D Sprites, 2D Frames and for the faces of a Mesh. A Material most often uses a Texture. Materials can be shared by multiple faces, 3D Sprites or 2D Frames.

As well as describing the surface description, a Material has several parameters that control advanced features such as fill and shade modes, transparency, blending modes, the Texture to use and the filter modes, and so on.

Diffuse and Specular Parameters

On the left image, you can see the effect of varying the emissive and diffuse color parameters. The diffuse color varies vertically from black to red and the emissive color varies horizontally from black to blue.

The right picture shows the effect of the specular color and specular power. The specular color varies vertically from black to white and the specular power varies horizontally from 4 to 40.


Mesh (CKMesh) and Patch Mesh (CKPatchMesh)

Class Hierarchy

Behavioral Object > Mesh > Patch Mesh

Setups

Mesh/Patch Mesh

Initial Conditions

Mesh:Texture Wrap, Lit Mode, Mesh Topology (to complete), Channels (to complete - every column/line?), Materials Used.
Patch Mesh: All Patch and Control Vertex Data (= Patch Mesh Info data?), Tessellation Factor.

General Remarks

A Mesh is the physical structure of a 3D Object, it describes the geometrical representation of the object. Note that Meshes are very often shared by multiple 3D Objects or instances of 3D Objects to reduce file size and memory use.

Texture Wrap

The Texture Wrap parameter sets the wrapping mode for any Textures the Mesh uses. Is interpolated between two Texture coordinates. For example, given a starting coordinate 0.7 and a destination coordinate 0.1, the render engine will behave as following:

    • If set, it will draw the pixels starting at 0.7 and cycling when reaching 1. (0.7, 0.8, 0.9, 0, 0.1)
    • If not set, it will draw the Texture going backwards to 0.1 (0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1)

The available options are U (only horizontal axis), V (only vertical axis), Both (both axis) and None (no cycling).

Channels

A Mesh can have up to 8 additional Material Channels. A Channel is a Material that is blended with the main Material or other Channels. Each Channel is associated with one Material for the faces, and one set of Texture coordinates. For example, in addition to the standard materials (up to one by face) for a Mesh, the Mesh could have a Channel of environment mapping, and a Channel of shadows, etc. Channels are rendered in the order they are added to a Material.

Each mesh can have several Texture layers (due to the limitations of current graphics cards, you are advised not to use more than 8). The list describes the materials for each layer and the method used to blend the layers over the mesh. The Pass column states how many rendering passes are needed to render the additional channel. 1 means the 3D graphics card can perform the rendering very quickly, 2 means the 3D card that rendering is twice as slow.

Mesh

A Mesh consists of Faces or Lines. Faces are made up of edges, which are themselves made up of vertices. At rendering time, the mesh vertices are transformed by the world matrix of the 3D Object, in order to position/rotate/scale it. Then, vertices are lit and faces are drawn using their attached material.

Progressive Meshes

Progressive Meshes is a LOD (Level of Detail) technique that reduces calculation time by using simpler versions of a Mesh as the 3D Entity using it gets farther from the Camera. When you activate Progressive Mesh, an optimized Mesh structure is built and associated with the Mesh. This Mesh structure is used by the render engine to automatically reduce the face and vertex count of a mesh. Note that 'popping' can occur when switching from one Progressive Mesh to another - that is the change from from one model to another is noticeable.

You must add the LOD Object Attribute to the 3D Entity that uses the Mesh for this parameter to have any effect.

Geomorphic Transition

Geomorphic Transition is an refinement to Progressive Meshes. Geomorphic Transition overcomes the problem of popping with a smooth transition from one Mesh to another. This is achieved by collapsing edges, and then moving vertices of one Mesh to the other (simpler) Mesh, instead of simply switching from one Mesh to another. Note that Geomorphic Transition can only be used for edge-collapsed Meshes.

The default value for Geomorphic Transition is 0 which results in dichotomic decimation, e.g. a 500 vertex Mesh morphs from 500 vertices to 250, then from 250 to 125, and so on; you can however set your own level.

Patch Mesh

A Patch Mesh is made up of an array of bezier patches (triangular or quadrangular) which can be tessellated given an iteration count to construct a standard mesh made up of triangles. It generates a list of strip primitives per material for maximum performances. The advantage of a patch mesh is that it allows more detailed meshes while at the same time using less memory on disk. Note that currently only uniform tessellation is supported.


Place (CKPlace) and Portal (CKPortal)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > Place

Setups

Place
Portal

Initial Conditions

Place: Default Camera for the Place, Portals List.
Portal: to confirm [just 3D Entity with 'portal' flag, therefore Owner Place, World Matrix (Position, Orientation, Scale) Parent Entity].

Remarks

Place

A Place (CKPlace) is a way to organize space segmentation in a composition, just as Scenes are a way to organize time segmentation. A CMO can contain zero or several Places. A Place can contain other Places. There is no specific link between Scenes and Places.

A Place is a 3D Entity and is the parent of all elements that it contains; whenever you add an element to a Place that element's child objects are also added to the Place. Note that a Place 'really' contains the elements that belong to it, the elements are not referenced as is the case for Scenes. Therefore a 3D Entity can only belong to a single Place - if an element is required in several Places, then you should make that element 'global' so that is part of the Level and not any particular Place.

In addition to being a good organizational tool, Places allow you to take advantage of Portal Culling. Portal culling is a rendering optimization that calculates whether a Place can be seen from another Place.

Portal

A Portal is a simple instance of a 3D Entity that acts as a connector between two Places. A Portal acts as a window or door between two Places and is represented by a transparent blue box in the 3D Layout. A single Portal can only link two Places, but a two or more Places can have several Portals that link them together. Note that a Portal must penetrate both Places for the Portal Manager to take it into account. For Portal culling to work, you must activate the Portal Manager, e.g. with the Portal Management BB.

Portal culling is an optimization of the rendering phase by removing unseen hierarchies of objects from the list of potential objects to render. The decision of what to display is done through the active camera. When the Portal system is active, the rule is the following:

  1. Before each rendering phase, the list of Places spatially containing the active Camera is calculated (including the view frustrum), using the Places' bounding boxes. These Places and all the Places that have a portal to these Places (and this recursively) are considered to be potentially visible, and are processed by the render engine (CK2_3D).

  2. If an element is in one of these Places, the element will not be seen: the element is therefore immediately considered "out-of-view" (even if it is active and its behaviors are executed), and so is not processed by the render engine.

If the Portal Manager is not active, portal culling does not take place and this optimization step does not happen. Instead, every 3D entity is considered potentially visible and only hierarchical culling is performed. Even if you do not initially use portal culling, Places are still very useful for organizing 3D entities hierarchically for other purposes.

Using Portals

Using Portals became a lot easier with the Automatic Portal feature.


Automatic Portals New Feature

Process

The task of creating a Portals system in a composition to optimize the frame rate can be divided into 3 steps:

Step 1: create Places from in your world
Step 2: create a Portal for each pair of connected Places
Step 3: set the position, orientation and scale of each Portal to make it coincide with the gate linking Place1 and Place2

Step 1 can often be accomplished directly in your modeling application (e.g. within 3ds max you can detach and group objects together, and select the check box "convert groups to places" in the Virtools exporter for 3ds max).

Previously, Step 2 and Step 3 often required a lot of time of effort. However Dev 2.1 introduced Automatic Portal Creation, allowing you to create portals and set their correct position, orientation and scale in just a few seconds.

There are three different ways to use this feature:

- use Automatic Portals button in the 3D Layout
- use the context menu in the Place Setup
- use the Set Portal BB

For those who want to know, the algorithm finds the common vertices between two places (i.e. vertices sharing the same position). Once those points are found, it generates the best fitting bounding box wrapping all the points (i.e. the minimal free orientated bounding box).

Note that once the Portals have been positioned using one of these methods, you can still change Portal's position, orientation and scale using standard tools if it doesn't match your expectations.

Automatically create all the Portals from the 3D Layout

You can ask Virtools to create automatically all the Portals of your world by simply clicking on the "Automatic Portals" button. This button can be accessed by moving the mouse over the Create Portal icon on the 3D Layout.

Starting places without portal connection:
 Automatic creation of portals:

When you decide to create Portals automatically, Virtools looks for all the contiguous Places, and determines if they share some vertices (i.e. if some vertices of Place01 are very close to the vertices of Place02). If a pair of Places share some vertices, then a new portal named "Portal Place01-Place02" is created so that it includes all the shared vertices.

Automatically create a Portal from the Place Setup

You can also decide to create just one Portal between two given Places. In this case just go Setup for one of the Places, right-click and select "Automatic Portal".

A portal will be created wrapping the shared points between the two portals.

Automatically create (or just position) a Portal with the Set Portal BB

Finally it can be very useful to wrap shared points between two Places at run-time. To do this, a Settings check box has been added the the Set Portal BB.

Apply the Set Portal BB to an already created Portal (or another object that can be considered as the Portal between the two Places), and select the Auto Fit check box.

Note: unlike the two methods presented first, this method neither creates a Portal, nor renames it.


Render Object (CKRenderObject)

Class Hierarchy

Behavioral Object > Render Object

Setups

N/A

Initial Conditions

N/A

Remarks

A Render Object is simply an element that can be rendered, that is seen on screen at run-time. Note that even if a RenderObject is hidden, the RenderObject remains active and so behavioral processing for that element (i.e. processing scripts) still continues.


Scene (CKScene)

Class Hierarchy

Behavioral Object > Scene

Setups

Level/Scene (shared Setup)

Initial Conditions

Fog, Background Color / Texture, Starting Camera

Remarks

A Level in Virtools can include several Scenes or no Scenes at all (in which case the Level is the default Scene). A Scene is temporal device used to describe what elements are present at a certain moment, and how they should act (which behaviors should be active).

Only one scene can be active at a time. However, whenever you create a new Scene, any scripts attached to the Level are automatically copied to the new Scene. This way you can attach a script to the Level that manages changing from one Scene to another at run-time and whenever you create a new Scene, this script is automatically copied to the new Scene.

Note that a Scene only references elements, e.g. if you delete or change an element in a Scene, the element still exists in the Level as it might be used in a different Scene or in the default Level Scene itself. However, if you delete or change an element in the Level, the element automatically disappears from all Scenes.

The Scene setup allows you set several render options for the Scene (e.g. background color, fog options or starting camera) that can be made active immediately or just when the Scene becomes active.


Sound (CKSound), Midi Sound (CKMidiSound) and Wave Sound (CKWaveSound)

Class Hierarchy

Behavioral Object > Sound > Midi Sound
Behavioral Object > Sound > Wave Sound

Setups

Sound (for Wave Sounds only)

Initial Conditions

All Data (as shown in Sound Setup).

General Remarks

Sound

The class CKSound only provides a common method for the save options of sound files, as such there is no Setup for this class.

Midi Sound

CKMidiSound provides the basic methods for playing a midi sound file. No Setup exists for Midi sounds.

Wave Sound

CKWaveSound provides methods for playing a wave sound file (.MP3, .WAV, .WMA (and the sound component of other Windows Media file formats such as .ASF)). A sound is either played as a background (2D) or point (3D) sound.

Normally sound files are 'streamed' - an initial buffer of two seconds is loaded into memory, and subsequent parts of the sound file are read from disk as and when needed by a separate thread. Note that as from version 2.0 you can decide to include sound files in the CMO or to keep sound files external. Also as from 2.0 the Virtools Web Player supports sound.

Spatial effects that suggest 3D are possible with point sounds due to the notion that the sound has a specific origin in 3D space (a point) and a listener who does the hearing (the current camera by default). You can attach a sound to an object, so that if the object moves, the sound moves as well. When you atatch a sound to an object, you can decide how close the sound is to the attached object (e.g. the same place, or several metres away) and the orientation of the sound. You can only set the listener via the Set Listener BB.

Remarks for Point Sounds (3D)

As noted above, point sounds enable spatial effects through the notion of a sound source and a listener. Linked to this are the concepts of sound projection cones and min/max perception distances.

Sound Projection Cones

If a sound source, such as a speaker, points directly toward you, the sound seems is lot louder than if the speaker is pointing directly or slightly away. Sound cones describe how loud a sound should be according to the listener's position and the sound's orientation.

Sound cones are made up of an inside and an outside cone. Witihin the inner cone the volume of the sound is as it would be if no cone existed. Beyond the outside cone, the sound is attenuated (made quieter) as the sound is no longer pointing towards the listener. Between the inner and outer cones is a zone of transition from the inside volume to the outside volume. The volume decreases as the angle increases.

The following example will make things clearer: a sound source is positioned in the center of a room. The sound points toward an open door of a hallway. The inside cone is set so that it extends to the width of the doorway, with the outside cone a bit wider. The Outside Gain parameter for beyond the outside cone is set to zero (meaning that nothing can be heard if the listener is not within the sound cone). The result is that a listener moving along the hallway will begin to hear the sound only when near the doorway, and the sound will be loudest as the listener passes directly in front of the open door.

Min and Max Perception Distances

Normally the closer a listener is to a sound source, the louder that sound appears, and, after a certain distance, a listener can no longer hear a sound. The Min and Max Perception Distance parameters allow you to change this behavior however.

The Min Perception Distance parameter is used primarily to compensate absolute volume levels. For example, although a motorbike is quieter than an airplane, both sounds are recorded at similar absolute volumes. To ensure real-world sound levels, Min Perception Distance is set at 100 meters for the airplane and 10 meters for the motorbike. This way the airplane sound is at half volume when the listener is 200 meters away, but the bee sound is at half volume when the listener is 20 meters away.

The Max Perception Distance parameter is used to ensure a sound can always be heard. For example, if Min Perception Distance for a sound is set at 100 meters, that sound might become inaudible at 1,000 meters or less. By setting Max Perception Distance to 800 meters, the sound will always be heard at one-eighth of its maximum volume at least, regardless of the distance.


3D Sprite (CKSprite3D)

Class Hierarchy

Behavioral Object > Render Object > 3D Entity > 3D Sprite

Setups

3D Sprite

Initial Conditions

Type, Size, Offset, Mapping, Current Material.

Remarks

A 3D Sprite is a 2D image that has a position and orientation, therefore giving the illusion that the object exists in 3D. A 3D Sprite is made up of a Material that specifies the Texture used and other render settings. A 3D Sprite's orientation can be free or constrained (billboard or axis specific) so that the image always faces the camera in a certain way.

To create a 3D Sprite, either drag a file from a 3D Sprites folder of a data resource, or drag a file from the Textures folder of a data resource holding down the SHIFT key.


Texture (CKTexture)

Class Hierarchy

Behavioral Object > Texture

Setups

Texture

Initial Conditions

All Bitmap slots, Color Key, Current Slot, Save Options, Desired Video Format.

Remarks

CKTexture is the class used for the various supported file formats supported by Dev for Textures. A Texture can contain more than one image - in this case each image is a slot, with slots starting at zero (0). In fact AVI files can be imported as Textures, with each frame occupying a slot. You could use a 2D Frame to hold the Texture played back via the Movie Player BB. Note that AVI playback is dependant on the target machine having the appropriate codec correctly installed.

A Texture surface information is stored in a buffer in system memory and loaded into video memory when needed. The Virtools internal format is 32 bit, 8:8:8:8 (red, green, blue, alpha). Although the Virtools internal format has 8 bits for the alpha channel, only two formats (TGA 32 bits and PNG 24 bit + alpha) can save this information.

You are recommended to use square Textures wherever possible for optimization; note that some old graphics cards only support square Textures. You should also ensure that Texture sizes are to the power of two, i.e. that the width or length of a Texture is 2, 4, 16, 32, 64, 128, or 256 pixels, again for optimization. Note that some graphics cards can only support Textures up to a certain size, e.g. 256x256 pixels. Check the specifications of the graphics card of your target platform. Lastly, consider using Textures that are supported on a wide range of platforms (PC/Mac and/or game console) or are easily converted.

To summarize:

  • Textures should be square (not all graphics cards support non-square textures).
  • The size should be a power of two (16, 32, 64, 128, 256, …).
  • The Virtools internal format is 32 bit, 8:8:8:8 (RGBA).
  • Formats supported: BMP/DIB, PCX, PNG, TGA, TIFF, JPG, AVI. See Importing Media for more information.
  • A Texture may have several slots, with each slot containing a specific image.
  • Textures can have an alpha channel (transparency mask) of 8 bits, but only TGA 32 bits and PNG 24 bit + alpha can save the alpha channel.
  • For AVI files, the target machine must have the appropriate codec to play the file.


Script

What is a Script?

A script is the visual representation of a behavior, applied to an element, as represented in the Schematic. A Script is composed of two parts - a header and a body. The header displays the name and owner of the Script, and optionally a small snapshot. The Script body is composed of the Start (the starting point) and one or more BBs, BGs, paramOps, Parameters, bLinks, pLinks, comments, etc.

Mathematically, a Script is a graph whose nodes represent operations (BBs or paramOps) and whose edges represent possible paths of data flow (pLinks) and program flow (bLinks). A Script is processed by following the bLinks as directed by the BBs contained within the Script.

Behaviors contained in a script are executed following the flow of bLinks, as follows:

  • The starting point of the script (Start) is activated
  • All bLinks emanating from the starting point are activated and transmit the event flow to behavior inputs.
  • Behaviors receiving the flow become active: behaviors are executed
  • The outputs of behaviors transmit the event flow to links
  • Repeat from the step 3 until there are no links connected to an active output of a behavior

For more information on the execution of scripts in the Virtools behavior engine, please refer to Virtools Execution Loop or Frame.

Creating Scripts

Dragging a behavior from a resource database to an entity in the 3D Layout:
A script is automatically created in Schematic and attached to the element. If you are new to Virtools, this method is well illustrated in the Virtools Users' Guide.

Using the create script icon [image] in Level Manager:
Selecting an element in Level Manager and then clicking on the create script icon will create a script in the Schematic. Double click the newly created script in Level Manager to switch to the Schematic. You can then drag behaviors directly into the Schematic, add links etc.

Re-sizing Scripts

Re-sizing a script (Schematic only):
Move the mouse near a top or bottom boundary and the cursor will change allowing you to move the boundary increasing or decreasing the size of the script.

Moving within the schematic:
To scroll the schematic use exactly the same keys as for any traditional document. Left, Right, Up, Down arrows to scroll in corresponding direction, and End/Home key to go to the top/bottom of the scripts.

Selections and Multiselections

To perform a multiselection, Click and drag while pressing the CTRL key. Multiselections can be saved as Virtools Script Files (.NMS) by selecting Save Selection from the context menu. Multiselections can also be copied and pasted in the same or in another script. Another way to copy selections is to press the SHIFT key and to drag the selection into another script. The parameters contained in a multiselection can be pasted as shortcuts. Selections can be deleted by pressing the DEL key or via the shortcut menu.

Debugging your scripts

Two tools exist to help you debugging: Trace Mode and Script Debugger.

Using Scripts

Via the shortcut menu on script body you can:

  • Draw a Behavior Graph
  • Add Building Block:
    By choosing a BB in the sub menu. BB are sorted by categories, and the last used BBs are also available. You can also call the categories sub menu by clicking the middle button in the schematic and the last BBs used menu by using Shift+Right Click. Another way is to drag BBs from the Building Blocks View and drop them in the Schematic View.
    A quick way to add BBs is the shortcut: Ctrl+Double Click in a script or a BG. It opens a combo box that with a sorted list of all BBs that begin with the string typed in the edit field of the combo. To select a BB, either use the mouse, or the keyboard with the return key to select and the escape key to cancel. When only 1 building block is in the list of the combo box, it does not have to be highlighted in the list, just press return to select it.

  • Add Local Parameter
  • Add <This> Parameter
  • Add Parameter Operation
  • Add Comment
  • Rename Script
  • Save the script as a nms file
  • Copy script, which can be paste in the level manager using Ctrl+V
  • Delete script
  • Import Behavior Graph, which means loading a nms file.


Script Header

Overview

The script header shows:

Pierre Script - the script name (to the right of the arrow)
Pierre - the script owner (the behavioral object to which the script applies)
(a small picture) - the script snapshot
IC - Initial Conditions, if set
Priority = 0 - script priority, if Show Priority is activated for the Schematic

- Double-click the script name to open/close the script.
- Press F2 to rename the script.
- Double-click the script name to switch to the Level Manager with focus on that element.
- Drag a snapshot from the Snapshot Buffer to the script header to change the current bitmap associated with the script (or just add a bitmap).
- Use color to differentiate your scripts
- Use the context menu for the many other functions, detailed below.

Moving scripts

Script's order can be changed by drag & drop with the header (once at a time)

Script Header Shortcut Menu (Keyboard Shortcut)

Execute Script(s) (Alt+X)
Execute selected scripts, by activating the script's start. It works in Author mode as well as in Player mode. This function cannot be debugged with trace mode. This is as if the Step button is pressed only for selected scripts after a reset, so behaviors and graphes that are to be executed after frame 0 will not be activated.
Set Initial Conditions (Shift+Q)
Sets initial conditions for selected scripts.

Remove Initial Conditions (Ctrl+Q)
Removes initial conditions for selected scripts in the current scene.

Restore Initial Conditions (Alt+Q)
Restores initial conditions for selected scripts in the current scene.
Show Object in Level Manager (double click on object name)
Shows the script owner in the Level Manager.

Show Script in Level Manager
Shows the script in the Level Manager.

Setup
Opens the Setup for the script owner.
Load Snapshot for Script
Opens a dialog box allowing you to select a file to load as the snapshot for the script.

Edit Priority
Edits the script's priority.
Sort By Name
Organizes scripts alphanumerically, numbers first then letters A-Z.

Sort By Owner
Groups together scripts that have the same script owner.

Sort By Color
Groups together scripts that have the same color.

Sort By Class ID
Organizes scripts by CKID, so that similar elements (e.g. Characters, 3D Frames) are grouped together.

Invert Order
Reverses the order of scripts, but does not change the sort method.
Set Color
Opens the Color Box, allowing you to set or edit an existing color for one or several script headers.

Remove Color
Removes color from one or several script headers.
Rename (F2)
Allows you to rename a script.

Save As... (Alt+S)
Opens the Save Selection dialog box, allowing you to save one or several scripts in a Virtools Script file (NMS).

Copy
Copies one or several scripts to the clipboard. To paste a script, you must go to the Level Manager and press CTRL+V
Delete
Deletes one or several scripts; you are prompted to confirm before the scipts are actually deleted.


Script Body

  • Script
  • Behavior Building Blocks (BB)
    • Behavior Input (bIn)
    • Behavior Output (bOut)
    • Parameter Input (pIn)
    • Parameter Output (pOut)
  • Link
    • Behavior Link (bLink)
    • Parameter Link (pLink)

  • Parameter - Attribute
    • Local Parameter
    • This Parameter

    • Parameter Shortcut
  • Behavior Graph (BG)
  • Parameter Operation (paramOp)
  • Comment


Attribute Parameter

An attribute parameter is a data value associated with a BeObject. An attribute has a Name and may also have a Category.
An attribute typically consists of one or more Author-editable parameters. However, some attributes, such as Sound Obstacle, can not be edited by the Author.

For example, an element with the Floor attribute is identified to the Behavior Engine as an element that should be treated as a floor so that characters walk on the element and not through the element. Virtools includes numerous predefined Attributes. Authors can also define their own Attributes.

Attributes are very much like local parameters in that they store information, with the difference being that attributes belong to an object instead of belonging to a script. An example of an attribute is 'obstacle', which would be applied to objects (such as cars) so to as to help in detecting for collisions.

An attribute can be created by accessing the 3D Object Setup. To create an attribute, use the create attribute button on the left tool bar. A predefined category can be used or a new one can be created.

The Attribute Manager gives a global view of all attributes defined at any one moment and the Entities that have them.

See also Attribute Mode on Setups.

To create an attribute shortcut:

  1. Open the attribute setup
  2. Click the attribute to select it
  3. Choose Copy parameter in the contextual menu.
  4. Choose Paste Shortcut in the contextual menu in the behavior you want to use the reference to the attribute.


Behavior Building Block (BB)

Overview

A Behavior Building Block (BB) is the fundamental element within Virtools, BBs encapsulate a specific task.
BBs are a visual representation of a software element known as a function.

BBs can be categorized as:

  • Single Action: the BB completes processing within the current frame. A Single Action BB can stand alone or be part of a behavior loop. Example: Set Fog.

  • Internally Looped: the BB is turned On and the BB is activated every frame until the BB is turned Off. Example: Keyboard Controller. Note that for internally looped BBs you must pay attention to priorities for activation flow.

  • Externally Looped: the BB completes one step in the BB's process loop within the current frame.
    If the Author wants the BB to operate in the typical manner, an external activation feedback loop is required.
    Note: An externally looped BB does not require that an external activation feedback loop be present. It is possible to construct a Script in a manner such that the external activation feedback loop is not required. Example: Bezier Progression.

The following terms are used when describing how BBs are processed:

  • Activate denotes the first time a BB is executed in a frame.
  • Deactivate denotes that an internally looped BB is no longer active.
  • Trigger denotes that a BB is activated by the external loop feedback path.
  • Receive denotes that some BBs can be activated on more than one bIn per frame; we say that the BB receives activations on the relevant pIns.
    Example: Parameter Selector and Wait For All.
  • Store denotes that some BBs keep a record of received activations; we say that the BB stores activations.
    The BB then processes the record of received activations and generates new activations according to the rules of that BB. Example: LIFO and FIFO.
  • Generate denotes that some BBs generate more activations than the BB receives. Example: All But One.

To obtain help on a specific Building Block, select it and press F1.
You can also look at the Building Blocks Documentation sorted by categories or in alphabetic order.

Behavior IOs and Pins

A behavior activates other behaviors by activating behavior links through IOs (bIns and bOuts). A behavior passes data to another behavior through parameter links (formed between pIns and pOuts). Behaviors can also send messages.

  • Behavior Input (bIn)
  • Behavior Output (bOut)
  • Parameter Input (pIn)
  • Parameter Output (pOut)

S, V and C

You will soon notice that some building blocks have an S, V or C in the bottom left corner.
S means that the building block has internal settings, V means that the building block has variable number of pins, and C means the building block has a custom dialog box.

S - Settings

An 'S' appearing on the bottom left corner of a BB means that the behavior has internal settings that can be edited, through its context menu (shortcut 'S'). Settings can be just as important as inputs and outputs. They can sometimes save you scripting time, by offering you the possibility to change their signification or behavior.
An example is the behavior Proximity.

V - Variable

A 'V' appearing on the bottom left corner of a BB means that the BB can have a variable number of pins, that is that you can add new pins or IOs to it.
The BB Sequencer is such BB: you can add additional outputs to it.

V can also signify that the building block's Parameter Inputs may be of a different type than the one proposed by default. However not all parameter types are selected for all behaviors.

For example, the building block Calculator can accept Parameter Inputs of FLOAT or VECTOR type only, whereas the building block Identity can accept any type of parameter. You should check with the behavior's indivual documentation.
To add inputs/outputs, right click the behavior and choose Construct in the menu. Then choose Add Input or Add Output, Add Parameter Input or Add Parameter Output.

To edit a parameter type, right-click it and choose Edit in the menu. In the dialog box that appears you can edit the type. If you modify an Parameter Input's type, the linked local parameter's type will be updated if this one is linked only once.

C - Custom Dialog Box:

A 'C' appearing on the bottom left corner of a behavior means that the behavior has a special dialog box, central to controlling how it works.
Unlimited Controller and Keyboard Mapper are examples of such behaviors.

Messages

Some BBs have the ability to send or receive messages.

  • Denoted by a Sender icon [image] in the lower left corner of the BB.
  • Denoted by a Receiver icon [image] in the lower left corner of the BB.

Targetable Building Block

Certain BBs apply to a target and have special management options. See Targetable BB documentation for more details.

Editing BB

  • To select a BB click it with the main mouse button.
  • To move the BB in a script, simply drag it to the new desired location (it is not possible to drag a BB to a different script).
  • To delete a BB, select it and either press DELETE, or choose Delete Selection from the right-click menu.
  • To edit a parameter's value, double click its value if this one is displayed, or use Edit Parameter from the right click menu (Shortcut is E).
  • To edit all the parameters of the BB, select the BB and use Edit Parameter from the right click menu (Shortcut is E).
  • To edit priority of a BB, use Edit Priority in the shortcut menu (Note: priority of all selected behaviors will be modified). See also Priority.

Run VSL Building Blocks

  • Run VSL building blocks are brighter than other BBs in order to distinguish them.
  • They can be renamed.
  • To edit their script, right click on a Run VSL BB, then choose Edit VSL Script. The VSL Script Manager will appear (if not already present), with the Run VSL script ready to be edited. The keyboard shortcut is 'V'.


Behavior Graph

Behavior Graph (BG)

Overview

A Behavior Graph is composed of one or more of the following elements: BBs, parameter operations, parameters, behavior links, parameter links, comments, shortcuts, other BGs, etc.. In other words, a BG is a visual representation of a Behavior.

At first glance, a BG can look almost exactly like a Script. However, a BG is distinct from a Script because the Author of the BG deliberately encapsulated the behavior. The Author gave the BG a unique name so that the BG can be saved and reused.

Virtools treats a BG exactly the same as a BB. A BG can be attached to an element and applied to an element in the same manner as a BB. A BG can be considered an Author defined BB that, to an Author, works in exactly the same way as a BB - a BG has pIns, pOuts, bIns and bOuts.

A BG can be constructed by encapsulating a portion of a Script or all of a Script. A BG can also be constructed as an empty BG and elements added until the desired functionality is achieved.

A BG can be expanded to show the elements that make up the BG or collapsed to hide the elements that make up the BG. An expanded BG is recognized by the surrounding bounding box and the three diagonal lines in the bottom right corner of the bounding box. A collapsed BG looks like a BB with the following exceptions: the BG label is in Bold face and the type is Dark Gray in color.

Encapsulation

There are 4 encapsulated behavior graphs here. The font used and border color change according to the position of the graph in the hierarchy. The name of all graphs that include "B", directly or not, is not shown.

Creating and Editing Behavior Graphs

Creating a Behavior Graphs:

  • click the workspace of the Schematic with the right mouse button.
  • Choose Draw Behavior Graph in the contextual menu.
  • The keyboard shortcut for this is 'G'.
  • Point to the upper-left corner of the zone you want to place you new Behavior Graph.
  • Drag the pointer until the rectangular zone either includes all desired sub-Behaviors or reaches the desired sized.
  • All Behaviors included in the rectangular zone are considered to belong to the new Behavior Graph.
  • You can also create an empty BG

Opening and closing a Behavior Graph:
Double-click the name of the Behavior Graph. If the graph is protected, double-click will edit it.

Selecting, re-sizing, moving, renaming and deleting Behavior Graphs

  • To select a Behavior Graph click it with the main mouse button.
  • To Re-size an opened Behavior Graph, click and drag the bottom right triangle
  • To move a closed Behavior Graph in a script, simply drag it to the new desired location (it is not possible to drag a Behavior Graph to a different script).
  • To rename a Behavior Graph, select it and press F2 , or choose Rename from the right-click menu. Then edit directly the name in the edit box.
  • To delete a Behavior Graph, select it and either press DELETE, or choose Delete from the right-click menu.
  • To Delete a BG but keeping its contents choose Delete but Keep Contents in the BG shortcut menu or pressing Shift+Del.

Adding Behavior Inputs/Outputs or Parameter Inputs/Outputs , and editing them:

  • To add Behavior Inputs/Outputs, right click the Behavior Graph and choose Construct in the menu. Then choose Add Input or Add Output, Add Parameter Input or Add Parameter Output.
  • To edit a parameter type, right-click it and choose Edit in the menu. In the dialog box that appears you can edit the type. If you modify an Parameter Input's type, the linked local parameter's type will be updated if this one is linked only once.
  • To edit a parameter's value, double click its value if this one is displayed, or use Edit Parameter from the right click menu.
  • To edit all BG Parameters select it and choose Edit Parameters in the shortcut menu.
  • To edit a BG Priority choose Edit Priority in the shortcut menu. See also Priority
  • To export a bIn/bOut: Drag a bOut or bIn on to the border of the BG.
  • To export a pIn/pOut: Drag a linked Local/This/Shortcut Parameter or a pIn/pOut onto the border of the BG.
    You can reverse this action by dragging the one of those elements inside the BG.
    An exported parameter remains a copy of its source - its value will always be the same as the local parameter.

Saving and loading Behavior Graphs:

  • To load a Behavior Graph that which is not in a resource database, right click in the script where you want the Behavior Graph to be and choose Import Behavior Graph in the menu.
  • To save a Behavior Graph, select it, right-click it and choose Save as in the menu.
    You have the possibility of hiding its graphical representation, by selecting Hide script representation in Schematic, and so protecting your work.
    The dialog Box appearing let you add a short description of the BG and its version and sign it.


Behavior Input (bIn)

A behavior input (bIn) is located on the left side of a BB/BG. Some part of the code within a BB is executed when a bIn is activated, deactivated, or triggered.
Some BBs (particularly Logics/Streaming) can also receive and store activations. For example, the Parameter Selector BB and the Wait For All BB can receive N activations per frame but both can only generate one activation per frame.

  • To rename a bIn, select it and choose Rename in the shortcut menu or press F2.
  • To delete a bIn, select it and choose Delete in the shortcut menu or press Del.
  • To add a bIn to a BG or to a Variable BB, select the BB/BG and choose construct/add behavior input in the shortcut menu.


Behavior Link (bLink)

For general information on using links see Links Documentation.

Behavior Links (bLinks) propagate activation flow from one BB (or BG) to the next, and allow sequential execution of behaviors. A bLink also connects the script Start to the first BB to activate. A bLink connects bOuts to bIns.

Unlike parameter links (pLinks), a bLink always has an associated delay, where the Link Delay is measured in behavioral frames (process loops). The Link Delay can be:

  • 0 - propagate the activation within the current frame
  • 1 - propagate the activation in the next frame
  • n - propagate the activation in the nth frame after the current frame

You can edit the default link delay value by clicking on the Behavior Link Properties button in the Schematic toolbar.

The Links page desvribes the various methods of creating, editing, moving and deleting links (bLinks and pLinks).

To edit a link delay
Select link and choose Edit Link Delay in the shortcut menu or press E

To show/hide link delays
Click the top toolbar's Show/Hide Link Delay icon.


Behavior Output (bOut)

A behavior output (bOut) is located on the right side of a BB/BG.
Generally, a bOut activates when the processing to be performed by a BB in the current frame (process loop) is complete.
Some BBs (particularly Logics/Streaming) can also generate activations at their behavior outputs. For example, the Keep Activate BB and the All But One BB both generate activations (activate more bOuts than bIns).
See Behavior Loop for further description of the processing done by a BB in a given frame.

  • To rename a bOut, select it and choose Rename in the shortcut menu or press F2.
  • To delete a bOut, select it and choose Delete in the shortcut menu or press DEL.
  • To add a bOut on a BG or on a Variable BB, select the BB/BG and choose construct/add behavior output in the shortcut menu.


Comment

You can place comments wherever you want in the script body to describe the working of a script.

To add a comment
Right-click in the script where you want your comment to appear, and choose Add Comment from the menu.

To select a comment
Click with the main mouse button.

To Resize a comment
Drag its boundaries with the mouse cursor.

To turn a comment into an Icon
Use the Contextual Menu or Spacebar.

To move a comment in a script
Simply drag it to the new desired location.

To edit a comment

  • Double-click it, or
  • Select it and press F2, or
  • Choose the Rename in the right-click menu.

    To delete a comment
    Select it and either

  • Press DELETE, or
  • Choose Delete Selection from the right-click menu.

    To Close a comment
    Select it and either

  • Press the spacebar, or
  • choose Iconify Comment from the right-click menu.
    Note that an iconified comment generate a tooltip with its text when the mouse is over it.

    To Open a comment
    Select it and either press spacebar, or choose Open Comment from the right-click menu.


Link

Overview

There are two main types of link in Virtools - behavior links (bLinks) that connect BBs and BGs together, and parameter links (pLinks) that transfer data (parameters) to BBs, BGs and paramOps. This page explains the various methods of creating links. There are several ways to create links - there is bound to be a way that suits your working methods.

Linking

To connect entities with a link, click mode:

  1. Click the Link button in the toolbar. The keyboard shortcut for this is 'L'.
  2. Click with the left mouse button on the visual representation of the input or output of the source entity.
  3. Click in the workspace where you want to put an intermediate point for the cable that represents the link graphically.
  4. Avoid other components in order to have a better visualization of the graph.
  5. Repeat the step 2) as many times you required.
  6. click the visual representation of the input or output of the destination entity.
  7. The connection can be made from the output to the input or from the input to the output.
  8. For parameter link, if source and destination are not compatible, but there is one or more parameter operation that can convert source type to destination type, then the interface offer to create a Parameter Operation Link.

You can automate linking by choosing Automatic Link in the Schematic Preferences.

  • Works on a multiselection

Benefits : tooltips are available in that mode

drawback : you have to push a button.

To connect entities with a link, drag and drop mode:

  1. Drag any input / output / pIn / pOut and drop when mouse is over a compatible destination. Default color for a valid link is green. Note that dragging a parameter local will move it and not start a link.
  2. if you release the mouse button not on a compatible destination, a control point will be added and the click mode is reactivated.
  3. Note that you cannot start a link from a parameter local that way, since the parameter will be moved instead.
  • Works on a multiselection

Benefits : contextual action

drawback : tooltip are not available when mouse button is down.

Link from a multiselection

Note : multi link creation works with any kind of link, not only the instances used below, but they cannot be started from a selection of local parameters with the drag & drop mode, since selected local parameters will only be moved - use the [image] button when starting from a selection of local parameters.

  • Multi event link creation:

  1. Select outputs with the multiselection tool (Ctrl+Left mouse button+drag)
  2. Drag & drop one of the outputs to its destination (here the 2nd) (works with the Link button too)
  3. When the left mouse button is released, all allowed links are created
  4. if the alt key is down when the left mouse button is released, all sources are linked to the selected destination only

  • Multi parameter link creation:

  1. Select pOuts with the multiselection tool (Ctrl+Left mouse button+drag)
  2. Drag & drop one of the parameter to its destination (works with the Link button too)
  3. When the left mouse button is released, all allowed links are created
  • Multi link with automatic creation of IOs/parameters

For IO links, select a group of outputs, and drag & drop one of them on a destination building block or closed graph. When the mouse is released, inputs are automatically created and linked with the selected outputs.

Note that if the destination is a building block, it must allow the creation of inputs/outputs depending on what kind of IO was selected at the start.

For Parameter links, it works the same way: select a group of pOuts, drag & drop one of them on a destination building block or closed graph to automatically create linked pIns.

Note that if the destination is a building block, it must allow the creation of pIns/pOuts depending on what kind of parameter was selected at the start.

This works when starting from a selection of local parameters too, but then the [image] button must be used, since dragging local parameters do not start the link contextual action.

To export Inputs, Outputs, pIns, pOuts outside a behavior graph

  • Shift + Drag and Drop outside the owner building block or behavior graphe and beyond. This create an exported parameter link.
  • an exported parameter is shared : an exported parameter and its source are the same instance, meaning the parametric flow between them takes no time.
  • re-importing pIns and pOuts is possible the same way, but it is not available for inputs and outputs.
  • Works on a multiselection

Here is a example of how to export and re-import 3 pIns:

A) Export

  • A.1) Add pIns in selection.
  • A.2) Put the mouse cursor over one of the Pins, here the one designed by the red arrow.
  • A.3) Keep the shift key down and drag the one of the pIns outside the behavior graphes.
  • A.4) Release left mouse button : pIns are exported. Works the same way for pOuts. Note that only the exported pIns are selected now.

B) Re-Import

  • B.1) Select the pIns. In our case, they should be already selected. With the shift key down, drag one of the pIns following the red arrow, so that they match the pIns of the Identity building block.
  • B.2) Release mouse button : the pIns are re-imported.

To export Parameter Local outside a behavior graph

  • Works only on Parameter Locals linked to a pIn.
  • Drag and Drop Parameter Local outside owner behavior graph and beyond in the up direction only.
  • Un-export Parameter Local is possible the same way.
  • Works on multiselection of Parameter Local in the same behavior graph.

Here is a sample of how to export and re-import a local parameter:

A)Export

  • A.1) Select the parameter local designed by the red arrow.
  • A.2) Drag it outside the behavior graphes.
  • A.3) Release mouse button : the parameter local has been exported. In fact, the parameter local has a new owner, and the initial pIn connected to the parametter has been exported. Note that the exported parameter local is selected now.

B)Re-import

  • B.1) Select the parameter local and drag it inside behavior graphes.
  • B.2) When the mouse button is released, the parameter local has been re-imported.

To change the source or the destination of a Event Links without changing opposite extremity

  • Select the source or the destination of an event link.
  • Keep the Alt key down
  • and Drag and Drop the input or output to another destination.

Here is a sample

  1. Select input pointed out by the red arrow
  2. Drag it with mouse button down toward the 3rd identity building block, with the Alt key down.
  3. Until the mouse cursor is over the input of the 3rd identity building block
  4. Release mouse button. The link has been updated

To change pIn and pOut position on a behavior graph

  • Shift + Drag and Drop Parameter to another position on the graph.
  • The position must be on the top of the graph where Parameters Input are usually placed, or on the bottom of the graph where Parameters Output are usually placed.
  • Parameter position can be different whether the behavior graph is closed or opened.
  • Does not work on building blocks

Link Options: (Schematic Preferences)

  • When Search Best Path while Linking preference is activated, created links take the best path, so that the user do not have to create it control point by control point.
    It also makes all link connected to a moving selection to be updated with the best path if preference is activated.
    The Alt key revert the preference: press it while creating a link or moving the selection.
  • When Automatic Link preference is activated, you just have to click inputs/outputs/parameters without having to select link mode.
    The drawback of this preference is, it may be difficult to just select an input/output/parameter because by doing that, you will launch the construction of a link.
    Tip : use Control key to select an input/output/pIn this mode.

Get best path / get direct path for a link:

Pressing the P modifies all links connected to selection: that is, all selected links, and all links connected to selected behaviors and selected parameter operations.
It makes the links search for the best path, or destroy all of their control points, depending on whether they have control.

Link Type List

  • Behavior Link (bLink): a link from any kind of input/output to any kind of input/output. Default color is black.
  • Parameter Link (pLink) : a link from any kind of parameter (shortcut, local, pIn, pOut) to any kind of parameter. Default color is blue.
  • Exported Parameter Link : a link between a pIn and an exported pIn, or between a pOut and an exported pOut. Default color is turquoise blue. Exported parameter are all shared with their source, that is, they are all the same instance. The benefits from that is there it takes no time to transfer value, whereas for normal parameter link it takes a small amount of time.
  • Parameter Operation Link (paramOp Link) : a link from a parameter local, ouput or shortcut to an incompatible pIn. This link contains a parameter operation to convert source type to destination type. When creating the link, the interface will automatically create a parameter operation if there is only one possible parameter operation, otherwise the interface will ask the user to choose with available parameter operations. Default color is green.

On this picture you can see all possible types of link :

  1. bLink, from Start to a bIn
  2. bLink, from input to input of a child behavior graph / building block
  3. bLink, from output to input of 2 siblings behavior graphes / building blocks
  4. bLink, from output to output of a parent behavior graph
  5. bLink, loop link from output to input of the same behavior graph / building block
  6. pLink, from pIn to pIn of a child behavior graph / building block
  7. pLink, from pOut to pOut of a parent behavior graph
  8. pLink, from pOut to pIn of 2 siblings behavior graphes / building blocks, or of the same behavior graph / building block
  9. pLink, from pIn to pIn (same instance of parameter shared by 2 behavior graphes / building block)
  10. pLink, from parameter ou to pOut (same instance of parameter shared by 2 behavior graphes / building block)
  11. paramOp Link, from parameter local / pOut / shortcut to pIn
  12. pLink, from parameter local to pIn
  13. pLink, from pOut to parameter local
  14. pLink, from shortcut to pIn
  15. pLink, from pOut to shortcut


Local Parameter

A local parameter is a parameter contained within a Script, represented by a small rectangle. Local Parameters are either above Parameter Inputs (pIns) (the small triangles on top of a BB/BG/paramOp) or situated by themselves within a Script. Local Parameters are connected to pIns by Parameter Links.

Note: Two unique local parameters are allowed to have the same name. However, this practice is not recommended due to the potential for confusion. For instance, when you copy and paste a local parameter, you copy the parameter's name, the parameter's type and the parameter's value to a new local parameter: these two parameters are different, even though they have the same name (due to the copy and paste operation). The Author is encouraged to use unique names for each parameter that they create. Virtools maintains a unique identifier for each local parameter. To view a local parameter's identifier (called the CK_ID), select 'CK Properties' in the local parameter's context menu.

Local Parameters are used to store information. A local parameter is a parameter attached to an entity's script. A local parameter has a name, and contains a value expressed in a given type (such as integer, string, vector, etc.). A local parameter can provide its value to a behavior or to a parameter operation that requires it through a parameter link.

Using Local Parameters

To add a local parameter

  1. right-click in a script or in a BG.
  2. Choose Add local parameter in the contextual menu.

To edit a local parameter:

  1. click the parameter with the right mouse button.
  2. Choose Edit in the contextual menu, or select the local parameter and press E key.
  3. A dialog box appears and allows you to edit properties of the parameter: name, type, value.
  4. You can also double click a parameter value if it is displayed.

To change a local parameter's display and current value:

  1. To change a local parameter's display, right-click the parameter and choose change display.
    Alternatively, you can successively double-click the parameter to achieve the display you want. If you wish to display the type and value for several parameters of the same behavior, you can drag the parameter boxes so that the text does not run into each other.
  2. To change a local parameter's current value, double-click it and enter the new value in the dialog box which opens.

You can create references or shortcuts to local parameters and use their values in other behaviors or parameter operations, even in another scripts.
You can also copy parameter values and paste them into the Parameter Debugger editor, the Attributes Manager, and into Arrays.

To display Parameter CK Properties:

  • To display CK information about the parameter: its id, its owner and its destination parameters, select a shortcut and choose CK Properties in the shortcut menu.

To create a parameter shortcut

  1. Select the local parameter whose value you wish to copy by clicking on it.
  2. Copy your selection with the contextual menu or by pressing CTRL+C.
  3. Choose Paste Shortcut in the contextual menu or CTRL+Shift+V to place the shortcut in the script where you wish it to be.
  4. You can select and shortcut more than one parameter at a time.

Setting a local parameter as source of multiple shortcuts (Convert to Shortcut Source menu command)

You can set one local parameter as the source of all other local parameters in the composition or script that have the exact same name, type and value. This can make you scripts easier to understand and maintain, and also has an optimizing benefit as shortcuts occupy far less memory than parameters themselves.

Note: this optimization is not noticeable in the Virtools Dev interface, but only Virtools Players.

Turn all local parameters with the same name, type and value into shortcuts

  1. Choose the source, Right click on it and select Convert to Shortcut Source command
  2. All local parameters with same name, type and value in all scripts are turned into shortcuts of this local parameter.

In some specific scripts, turn all local parameters with the same name, type and value into shortcuts

  1. select the scripts where local parameters must be turned into shortcuts
  2. -do not select the local parameter source, but keep Ctrl key down and right click on the source,
  3. then select the Convert to Shortcut Source command from the right click menu
    all local parameters with same name, type and value in all scripts are turned into shortcuts of this local parameter in the selected scripts.


Parameter

A parameter is used to transfer data values between behaviors and to add information to BeObjects (through Attributes).
Many behaviors use the values of their pIns to control their processing. A parameter has a name and contains a value expressed in a given type (such as integer, string, vector, etc.).
A parameter can be static (the value is fixed, such as a value entered by the Author) or dynamic (the value can change, based upon other factors).
The value of a parameter is provided to a behavior or to a parameter operation via a parameter link or via a shortcut.

See also Attribute Parameter, Local Parameter, This Parameter, Parameter Shortcut, pIn, pOut, Parameter Operation.


Parameter Input (pIn)

A parameter input is just a connecting point made to receive a value from a paramOp or from another behavior, and communicate it inside the behavior. pIns have a source.
pIns are represented by the small triangles on top of a BB/BG/paramOp.
In traditional programming terms, Parameter Inputs are the arguments to the function encapsulated by a BB.
Parameter Inputs can have their name and type modified, if the owner behavior allows it.


Parameter Link (pLink)

For general information on using links (including how to create, edit and delete links), see Links Documentation.

A pLink is a link that propagates a parameter value either from a pOut or from a Local Parameter to a pIn. Unlike bLinks, pLinks do not have propagation delays: when a behavior requires a parameter for performing its task, it queries the pIn for a value, which is instantly retrieved through the connected pLink. This also means paramOps are evaluated each time the pOut is requested (even if Dev is in Author and not Play mode).

Note: When a BB is added to a Script, the links between the default Local Parameters and the corresponding pIns of the BB are not visible due to the scale of the image. However, the link is immediately visible if the Local Parameter is moved from the default location. A linked parameter is always drawn in a dark gray color, while a non-linked parameter is drawn in a lighter gray color.

Parameter Operation Links

A parameter operation link is a simple operation, automatically performed, on a single parameter when a pOut is connected to a pIn of incompatible type and at least one paramOp exists that converts between the type of the pOut and the type of the pIn. A Parameter Operation Link is a pLink that performs a type conversion. The type conversion occurs automatically and the default paramOp icon is not displayed. Instead, a Parameter Operation Link is identified by the name of the paramOp displayed along the link. By default, a Parameter Operation Link is displayed in a different color than a pLink (see Schematic Preferences colors).

To edit a Parameter Operation Link select link and choose Edit Parameter Operation Link in the shortcut menu or press E.


Parameter Operation (paramOp)

Overview

You can also consult Parameter Operations Lists .

A parameter operation is a simple operation performed on a single parameter or performed between a pair of parameters. A paramOp is only evaluated when the result is requested by another paramOp or a BB. Many calculations and data retrieval operations (Get Value) are implemented as paramOps. paramOp are also evaluated (during Author mode or Player mode) each time something (or someone) ask to retrieve the value of its pOut. Parameter Operations can be just as useful as building blocks when creating scripts in the Schematic. Certain operations, especially some requests, can only be done by performing a Parameter Operation.

Parameter Operations enable you:

  • to perform binary equations (C=A*B, C=sin(A), V3 = Angle(V1, V2), V2=f*V1 ... etc.)
  • to convert one type of parameter to another (Float "SetValue" Integer, or for example 3D Entity "SetValue" 3D Object). However, such conversions are now automate by green parameter links.
  • to collect information on an object (Float "GetRadius" 3D Object, Float "Magnitude" Vector, Vector "GetPosition" 3D Entity 3D Entity, or even CharacterBodyPart "GetBodyPart" Character String).

Example:
This parameter operation:

Input1 | Input2 | Operation | Output
Float | Vector | Multiply | Vector

equals a "Multiply" Operation which produces an output of result type Vector with inputs being Float and Vector types.

Differences between Parameter Operations and Behaviors

Parameter Operations differ from behaviors in the following ways:

  • Unlike building blocks, Parameter Operations cannot be activated sequentially one after the other. They do not have an IO structure, that is sequential inputs and outputs. The only way to activate sequentially a pseudo paramOp is by using the 'Op' building block (this building block perform any operation registered as a paramOp, but do it sequentially.
  • Parameter Operations are only calculated when needed, that is when a building block calls for a parameter Out value. Sequential parameter values can be generated by using the building block 'Op' or 'Identity'. See Calculating a value at a specific moment below.
  • Parameter Operations may have a maximum of only two inputs, and a sole output.
  • Parameter Operations do not have any settings.
  • Parameter Operations may be applied to any script of any type of object, Class Hierarchy does not apply.

Creating Parameter Operations

To create a parameter operation:

  • Click anywhere in a script or on an opened Behavior Graph with the right mouse button.
  • Choose Add Parameter Operation <Alt+P> in the contextual menu, the following dialog appears:

  • At first you can choose any parameter type you want in parameter combo-boxes, and any parameter operation.
  • Then you have lockers ( [image]) to lock an entry: All possible parameter operations are filtered through the locked entries, and the combo-boxes are update in consequence. For Instance, Addition is locked, and other combo-boxes contains parameters that can be used with an addition.
  • Choose the type of result, Output Type, you are looking for.
  • Select the type of inputs that the Parameter Operation will receive.
  • Choose the Operation Type, from the list of available valid operations (if there is nothing in the Operation Type drop down list, then the Parameter Operation is not possible - you should change one of the things above).
  • Click OK to confirm your choices.

On closing the dialog box, a Parameter Operation box will appear (Addition for example, as in the image below). Two inputs are created, as below, unless NullParam or NONE is specified as one of them, in which case it will be one. An output is always created.

WARNING: A parameter operation is computed only when its Parameter Outputs are requested by an active behavior.

Advanced Information

To modify a Parameter Operation:
 Press M or select it and choose Modify Parameter Operation in the shortcut menu.

Order of inputs:
There is no specific order for inputs, that is

  • Float "Multiply" Float Int
    is equivalent to
  • Float "Multiply" Int Float

Using Parameter Shortcuts:
 Sometimes it can be inconvenient or even impossible to link outputs to building blocks or other Parameter Operations. In this case, you can create Parameter Shortcuts, using CTRL+Cto copy the shortcut and then CTRL+SHIFT+V. Shortcuts are represented by a arrows, as shown above. With Shortcuts, the Parameter Operation can even be in another script, but will still function correctly as the result is only calculated when the output is requested. The output can be requested by:

  • a building block or another Parameter Operation itself called by the building block,
  • in the editor Parameter Debugger,
  • in the schematic editor
  • or in Debug mode.

Warning: if you decide to select the option of displaying the Parameter Operation's output value, this will be calculated at that moment, even if you are not in Play mode.

Calculating a value at a specific moment:
 If you wish to calculate a Parameter Operation at a specific moment in a script, you can either:

  • Use the building block Identity, to refresh the output value

    • The advantage in using Identity is the possibility of calculating several values at the same time for different variables.

  • or by using the building block Op, selecting the Operation Type in Settings, as shown below. This building block will perform a Parameter Operation when sequentially called by another building block. You can edit parameter operation by pressing S or by choosing Settings in the shortcut menu.

    • Parameter Types ANGLE, FLOAT and PERCENTAGE:
    Very often a Parameter Operation will involve a PERCENTAGE or ANGLE as type of input or output. It is necessary to understand these type of values are actually considered as FLOAT types, with the representation being customized to reflect an ANGLE type, (number of turns and degrees) or as a PERCENTAGE type.

    Therefore even if an ANGLE has a value of 0:180, the value used for calculations will in fact be equal to 3.141592... In the same way, a PERCENTAGE of 50%, will have the value of 0.5 for calculations. So wherever the you have a FLOAT input or output, you can change this to ANGLE or PERCENTAGE, and vice versa for your convenience.

    For example, if you create a Parameter Operation Float "Multiply" Percentage Float, and as values to be multiplied you have 50% and 2.0, the result will be 1.0, and not 100. For such an operation, it would be better to specify the Output Type as a Percentage for ease of comprehension.


Parameter Output (pOut)

Parameter outputs are data values generated by a paramOp or by a BB.
pOuts have a destination. pOuts are represented by the little triangles on the bottom of a BB/BG/paramOp.
In traditional programming terms, pOuts are the values returned by the function encapsulated by a BB.
Parameter Outputs can have their name and value modified, type if the owner behavior allows it.


Parameter Shortcut

Before using parameter shortcuts, ensure you have understood the Parameter and Local Parameter sections.

A Parameter Shortcut is similar to the desktop shortcuts used in Windows. A Parameter Shortcut is composed of a destination and a source, each identified by arrow icons. A Parameter Shortcut is the only type of shortcut available in Virtools and is usually referred to as a Shortcut. A Shortcut is actually another instance of a particular Parameter. Therefore, the CK_ID of the destination has the same CK_ID as the source. A Shortcut is dynamically updated and is often used to make a Parameter available across Script boundaries (the source is in one Script and the destination is in another Script) or used to make a Parameter available within a Script without using a pLink. A Shortcut can also be used to make a Parameter available to multiple locations without requiring a pLink between the source and each destination.

Using Parameter Shortcuts

To create a parameter shortcut:

  1. Select a local parameter or a parameter output whose value you wish to copy by clicking on it
  2. Copy your selection with the contextual menu or by pressing CTRL+C
  3. Choose Paste Shortcut in the contextual menu or CTRL+Shift+V to place the shortcut in the script where you wish it to be
  4. You can select and shortcut more than one parameter at a time.

To create selections of parameters shortcuts:
When Parameter Outputs or Local Parameters are in the selection, you can paste them as shortcut through the right-click menu or the CTRL+SHIFT+V keyboard shortcut or through Paste Shortcut contextual menu.

To create an attribute shortcut:
You can create references to attributes to use in other behaviors, even in other scripts.

  1. Open the Attribute Setup
  2. click the attribute to select it
  3. Choose Copy parameter in the contextual menu.
  4. Choose Paste Shortcut in the contextual menu in the behavior you want to use the reference to the attribute.

To Analyze Shortcut Source:
Select the Shortcut source and choose Analyze Shortcut Source in the shortcut menu. A dialog box which lists the shortcuts connected to this source appears. This list allows to focus a specific shortcut in the schematic. Double click on a shortcut , or select it and press Goto button to focus it in the schematic.

To focus a Shortcut source from a shortcut:
Select a shortcut and choose Show Shortcut Source in the shortcut menu.

To change the source of a group of shortcuts
Right click a shortcut, choose Set Shortcut Source in contextual menu, the Set Shortcut Source dialog opens.

  • Shortcut: shortcut name button: click to focus on the shortcut linked with the dialog in the schematic
  • Pick button : click here then pick a parameter in schematic. The text below will show if the mouse cursor is over a compatible new source or not.

When a new source has been picked, press Ok. All shortcuts sharing the same source will have their source changed to the picked parameter.

To move a shortcut source
Shortcut sources can be moved anywhere through the cut-paste commands.

  1. Cut the shortcut source with CTRL+X or contextual menu Cut.
  2. Paste the shortcut to a new destination with CTRL+V or contextual menu Paste.

Shortcutize, or turning local parameters with same type, name and value into shortcuts of one parameter.


Replacing BBs and BGs

Replacing Building Blocks or Behavior Graphs

Overview

Building blocks can be replaced by other building blocks, and behavior graphs by other behavior graphs. This feature is usefull when a composition needs updating. See the topics on Testing Building Blocks, TestBBs.exe and Obsolete/Invalid BB Explorer to know when to replace building blocks. When a behavior is replaced, the interface offers to replace all other behaviors with the same name.

Replace a Building Block

There are several way to replace a BB:

  • Drag and drop another BB from Building Block resources on the BB to be replaced.
  • Using special Popup menu, Shift+Middle mouse button, on the BB in schematic; this menu propose all building blocks.
  • Using special Popup menu, Shift+Right mouse button, on the BB in schematic; this menu propose the recently used building blocks.

The following dialog will appear:

  • Yes : replace only the target Building Block
  • Apply to All : replace all Building Block with the same name

A Building Block can be replaced by the same Building Block to update it to its latest version; however, it can be replaced by another Building Block too.

The interface tries to keep all parameters and event links; a parameter link will not be deleted if the parameter input type in the original building block is compatible with a parameter input [of the same name] in the new building block. If a parameter link connected to a local parameter is deleted, the local parameter will be deleted too; in that case, and if you choose "Apply to All", local parameters will be linked to free input parameters with default values of the building block.

If you are unsure about link conservation when replacing a building block, you should replace one at a time, and check links after.

Replace a Behavior Graph

A Behavior Graph can be replaced by another existing Behavior Graph in the compostion, or by a graph contained in an .nms file.

  • Using Popup menu Replace with existing Graph on a Behavior Graph. The following dialog will appear:

    You must then choose the replacing Graph, and check the Replace All check box if you want to replace all behavior graphs named as the target Behavior Graph.

  • Using Popup menu Replace with File Graph on a Behavior Graph.

  • Drag and drop a .nms file from Data Resources on a Behavior Graph.

The interface tries to keep all parameter and event link; a parameter link will not be deleted if the parameter input type in the replaced behavior graph is compatible with a parameter input type in the new behavior graph. If a parameter link connected to a local parameter is deleted, the local parameter will be deleted too; in that case, and if you choose "Apply to All" or checked "Replace All", local parameters will be linked to free input parameters with a null value.

If you are unsure about link conservation when replacing a behavior graph, you should replace one at a time, and check links after.

See also

  • Building Block Version Test from Options pulldown menu.
  • Obsolete/Invalid BB Explorer from the Schematic Toolbar.


Start

The left most icon within the body of a Script, the point at which a Script begins.


Targetable Building Block

A target parameter is a special type of pIn used to explicitly identify the element affected by the Behavior.
When a Behavior is attached to an element, that element becomes the owner of the Behavior. Typically, a Behavior attached to an element is implicitly targeted at the Script owner. For example, the BB Translate would normally modify the position of its' owner.
However, an Author may want a Behavior to affect a different element than the owner. In this case, the Behavior must be explicitly targeted by the Author at a different element.

Alternatively, an Author may attach a Behavior to an element of a different type than the type supported by the Behavior (for example, an Author can attach a Rotate behavior to a texture).

A Target Parameter is automatically generated by Virtools in the case of an incompatible class.

If a Target Parameter does not already exist on a behavior, a Target Parameter can be added by selecting "Add Target Parameter" from the context menu.

A new pIn is created as the leftmost pIn. A Target Parameter input is identified by a pair of small squares (rather than the usual single small triangle for a regular pIn). A BB is only targetable if there is a "T" in the targetable column (between the "Apply to" and "Description" columns) within the Building Blocks window.


This Parameter

This is a special local parameter, that refers to its owner: when you create a This parameter in a script, it automatically sets its value to be the entity to which the script is attached.

To create a This parameter, right click in a script, in the Schematic, and select 'Create This Parameter' in the context menu. It can be a good idea to create a This parameter when saving BG you create as they will automatically have the Entity on to which they were dropped as Target.


Behavior Building Blocks

  • Building Block Categories

  • Building Blocks Listed A-Z

  • New Building Blocks in Dev

  • Obsolete Building Blocks


Building Blocks A to Z

2 . 3 . A . B . C . D . E . F . G . H . I . J . K . L . M . N . O . P . Q . R . S . T . U . V . W . X . Y . Z

2

2D Curve Layout: Organize a set of 2D belong a 3D curve in space

2D Flow Layout: Organize a set of 2D entities horizontaly or verticaly

2D Grid Layout: Organize as a grid a set of 2D entities into a 2D Frame

2D Picking: Returns the 3D Entity, the normal and the exact position of the 2d mouse picking

2D Text: Display a text on a 2D Frame, using a texture font

3

3D Curve Layout: Organize a set of 3D belong a 3D curve in space

3D Entity Fill: Fill a grid's layer using the bounding box of a 3D Entity

3D Flow Layout: Organize a set of 3D entities belong a direction in space

3D Grid Layout: Organize a set of 3D entities into a 3D Grid

3D Text: Display a text on the plane XY of a 3D Frame, using a texture font

A

Activate Channel: Activates or Deactivates a specific Channel of the Mesh.

Activate Global State: Enters the system in the given global state.

Activate Link: Activates or deactivates a link between two nodes of a Nodal Path.

Activate Node: Activates or deactivates a node in a Nodal Path.

Activate Object: Activates all the scripts of an object, either in the state they were before deactivation or once reset.

Activate Script: Activates a script, either in the state it was before deactivation or once reset.

Add Animation: Add an animation to a character.

Add Channel: Adds a Channel Material to the 3D Entity.

Add Child: Adds a child to the 3D Entity's hierarchy

Add Control Point: Allows to extend a curve with a new control point

Add Mesh: Adds a mesh to the selected 3d Entity.

Add Object To Scene: Add an object to a specified scene.

Add Row: Adds a new row to the array.

Add To Group: Adds the object to a Group.

Additional View: Allows additional views to be displayed on screen simultaneously.

Align 2D: Aligns a 2D Entity on a model.

Align 3D: Aligns 3D Entities on a model.

All But One: Activates all the Outputs but not the one corresponding to the activated input.

Animation Recorder: Records the Position+Orientation+Scale as an animation.

Animation Synchronizer: Provides a way to send messages at a specific moment during a character animation.

Array Load: Loads elements into an array from a formatted file.

Array Save: Writes elements from an array to a text file.

Attach Script: Attach a script on an entity.

B

Back: Performs a back in the Web Browser

Bend: Bends a mesh uniformly along an axis with an angle and a direction of bending.

Bezier Progression: Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of milliseconds.

Bezier Transform: Transform a float value into another float value according to a 2d bezier curve shape, and given boundaries.

Billboard: Makes a 3dEntity act like a billboard sprite (with possible constant texture ratio for a face).

Binary Memory: Memorizes in a 'State Memory' whether the behavior was triggered by 'In 0' or 'In 1'.

Binary Switch: Activates the appropriate output, according to a Boolean condition.

BitmapText Display: Displays a Bitmap Text on top of the 3D environment

Blend Textures: Blends 2 textures.

Blink: Blinks the 3D Entity (alternates between show and hide).

Bool Event: Detects a boolean value change.

Box Box Intersection: Detects the collision between two 3D entities at the box level.

Box Face Intersection: Detects the collision between the first entity's bounding box and each faces of the second entity.

Broadcast Message: Sends a Message to every objects waiting for it.

BrowserScript: Executes a script in the Web Browser

Build Tangent Space: Ask the mesh to build (or remove) tangent space (used for bump mapping for example).

C

Calculator: Calculates the value of an arithmetic expression; 'a' stand for the first parameter, 'b' for the second, ...etc.

Call Script: Calls immediatly a script.

Camera Color Filter: Adds a color filter to the Camera.

Camera Orbit: Makes a Camera orbit round a 3D Entity.

CD Player: Plays soundtracks from an audio CD (v2).

Change Referential: Change the referential of a specified object, with another object referential.

Change Sprite Slot: Changes the current slot of the Sprite.

Change Texture Size: Change the size of the texture.

Change Texture Video Format: Changes the desired video memory format of the texture applied to

Change Value If: Get elements from an array, using the input parameter key and then replace it by the 4th input parameter's value.

Character Controller: Simple control of a character with 4 animations by joystick or keyboard.

Character Curve Follow: Makes a character follow a 3D Curved.

Character Go To: Make the character walk to a given object.

Character Go To Node: Makes the target character walk to the selected node, by taking the shortest path possible.

Character Grid Path Follow: Allow to a character to follow a path generated by the GridPathSolver

Character Keep On Floor: Forces a character to stay on previously defined floors.

Check For Message: Check the message manager to see if a specific message has been received by the object.

Chrono: Chronometer (ON=Start, OFF=Stop).

Clear Array: Removes all the rows of the array.

Cloth System: Creates a cloth system (spring & mass system).

Clouds Around: Creates a cloud and fog effect in a scene using a 6 textured cube, colors and a blending mode.

Collection Iterator: Retrieves each element of a Collection.

Collision Detection: Detects the collision between the 3D object and other 3D object declared as obstacles.

Column Operation: Performs an operation between two columns and put the result in a third one.

Column Product: Performs the multiplication of all the elements of a column.

Column Sum: Calculates the sum of all the elements of a column.

Column Transform: Performs an operation between one column value and a operand and store the result in the column.

Combine RT Views: Renders the scene into a RenderTarget View

Combine Texture: Combine two Textures into one

Copy Buffer to Texture: Copy a part of the frame buffer to a texture.

Copy Mapping: Copies the texture coordinates from a mesh to another mesh,

Counter: Exits 'MaxCount' times by the 'Looping' output and when finished, exits by 'Out' output.

Create Blended Animation 2: Creates a new animation by merging two exsiting animations.

Create Decal: Create a decal (object+mesh) on the targeted object.

Create Font: Creates a font from a provided texture.

Create Group From Array: Create a group with entities elements matching the given value.

Create Nodal Path: Creates a Nodal Path out of a group of frames.

Create String: Creates a string by concatenating elements, separating them by an optionnal delimiter.

Create System Font: Create a font from a system font name

CubicParticleSystem: Emits particles from inside a cube

Curve Follow: Moves a 3D Entity along a path.

CurveParticleSystem: Emits particles from a curve

Cylindrical Mapping: Maps an Object according to the Cylindrical.

CylindricalParticleSystem: Emits particles from a cylinder

D

Deactivate Global State: Exit the system from the given global state.

Deactivate Object: De-activates all the scripts of an object in the current scene.

Deactivate Script: Deactivates a Script.

Declare Floors: Identifies floor objects by their name

Declare Obstacles: Identifies obstacle objects by their name

Delayer: Waits for a given time to elapse using internal looping.

Delete Dynamic Objects: Deletes all the dynamic objects in memory

Delete Font: Delete a font (created by CreateFont or CreateSystemFont)

DiscParticleSystem: Emits particles from a disc

Display Progression Bar: Displays a progression bar.

Dolly: Keeps the projection plane at the same position while translating the camera on its Z local axis.

Drag and Drop: Enables you to drag and drop a 2D Entity.

Draw Rectangle: Draws a rectangle and a border at a specified position.

DX8 Dependency: Add this BB to your Virtools composition to retrieve the DirectX8 rasterizer in the Virtools Web Player.

DX9 Dependency: Add this BB to your Virtools composition to retrieve the DirectX9 rasterizer in the Virtools Web Player.

E

Edit 2D Entity: Changes the 2d entity parameters.

Enhanced Character Curve Follow: Makes a charcter follow all or a specified part of a curve performing a specified animation.

Enhanced Character Keep On Floor: Forces a character to stay on a declared floor (so it will not hover above it).

Enter Critical Section: Makes the object enter a critical section.

Entity Find Nodal Path: Finds the shortest path to a specified destination for a 3D Entity.

Environment Mapping: Sets a 3D Entity to be rendered with 'pseudo' Environment Mapping.

Exclude From Animation: Excludes the selected 3D Entity from all taking part in any animation that uses it.

Execute Script: Executes a script.

Explode: Makes an object appear to explode by spreading out its faces from the barycenter of the object.

F

Face Face Intersection: Detects the collision between two 3D entities at the face level.

FIFO: First In First Out

Fill Group By Class: Add all objects of a given type to the group.

Fill Layer: Fills a specific layer type with some value.

Filter Texture: Apply a filter matrix to the texture.

Find Curved Nodal Path: Retrieves a curve to follow between a starting point and a destination point.

Find Path: Returns a group of nodes to go by to reach a goal from a starting point.

Fire Virtools Event: Performs a Fire Event in the Web Browser

Floor Manager Setup: Configure the Floor Manager.

Floor Slider: Constrain an object to the floor boundaries, with a given radius.

Forward: Performs a Forward in the Web Browser

Frustum Object Intersection: Detects the collision between a camera frustum and an object.

G

Gauge: Displays a progression bar.

Generic Camera Orbit: Makes a Camera orbit round a 3D Entity using input activation.

Get Cell: Gets the cell of a chosen row and column.

Get Column Name: Gets the name of a column.

Get Component: Extracts the components of a COLOR, VECTOR or 2dVECTOR.

Get Control Point Properties: Allows to get parameter values of a control point

Get Current Camera: States the current camera in the active scene.

Get Current Scene: Returns the scene that is currently being played.

Get Curve Properties: Allows to get parameter values of curve

Get Delta Time: Returns the elapsed time between the previous and the current Behavioral Process.

Get Highest: Gets the element of an array, which value in the given column is the highest.

Get Host Platform: Gets the host platform

Get Key Row: Gets elements from an array, using the key column as a search criterion on the given key value.

Get LOD Attribute: Get the LOD Attribute parameters applied to an object.

Get Lowest: Gets the element of an array, which value in the given column is the lowest.

Get Message Data: Reads the data bound with the selected message.

Get Mouse Displacement: Gets the mouse relative movement.

Get Mouse Position: Gets the position of the mouse.

Get Nearest: Gets the element of an array, which value in the given column is the nearest from the reference value.

Get Nearest Floors: Retrieves the nearest 'floors' from given position

Get Nearest In Group: Get the nearest object in the selected group from the given position.

Get Nearest Object: Finds out which object in a group is closest to a character.

Get Nearest Vertex: Get the nearest vertex of a face of a given position.

Get Pos From Value: Gets the position of all the layer squares confirm test.

Get Proportional Screen Pos: Converts a given 2d position on the screen to a proportional position.

Get Row: Gets the elements of a chosen row.

Get Screen Proportional Pos: Converts a position from a 2d proportional position to the screen.

Get Shader Capabilities: Get shader capabilities of hardware

Get Square From 3D Pos: Gets the value of a square

Get SubString: Gets a sub string from an initial string.

Get Texture Info: Gets informations (filename and priority) about a texture.

GetUrl: Gets the current URL

Global Blur: Apply a global blur on all the objects rendered.

Go To Web Page: Performs a Navigate in the Web Browser

Grid Path Init: Initialize the grid graph for grid path finding

Grid Path Solver: Solve a new path finding problem.

Group Clear: Remove all the elements of a group.

Group Iterator: Retrieves each element of a group.

Group Operator: Makes combination of groups and objects wearing attributes.

H

Hardware Level: Activates output depending on the hardware acceleration level of the current driver

Has Attribute: Gets the parameter of an attribute (if it exists) on the object.

Hide: Hides a 2D/3D Entity, a Mesh or a Group

Hide Hierarchy: Hides hierarchically an entity

Hierarchy Parser: Iterate recursively on an object and all its children.

Home: Performs a Home in the Web Browser

Home on Entity: Leads a 3D Entity towards its target, avoiding obstacles.

I

IBCQ: Incremental Bezier Curve Query: Interpolates a float according to a 2D Bezier curve in the [0,1] range.

Identity: Outputs the Input Parameter(s) when activated.

IK Position: Sets a body part's position using Inverse Kinematics.

Input String: Captures text entered by user.

Insert Column: Inserts a column in the array.

Interpolator: Performs an interpolation between 2 parameters

Interpolator Object Orientation: Performs an interpolation between orientations of two given 3D Entity.

Invert Winding: Inverse the orientation of the faces of a mesh.

Is Global State Active: Checks to see if the system is in a specified global state.

Is In Group: Check if the object is in a specific group.

Is In View Frustum: Tests if the object is in the viewing frustrum of the active camera.

Iterator: Iterate on each row of an array and return the values of the current row.

Iterator If: Iterates on each row matching a value and return the values of them.

J

Joystick Camera Orbit: Makes a Camera orbit round a 3D Entity using Joystick.

Joystick Controller: Sends standard joystick messages to the building block owner.

Joystick Mapper: Binds specific messages to joystick commands.

Joystick Waiter: Activates different outputs according to Joystick commands.

K

Keep Active: Keeps streaming activated even if inputs has been activate only once.

Keep At Constant Distance: Selected object will follow another object wherever it goes, keeping the same distance between them.

Key Event: Activates one output when a specific key is pressed and a different output when the released.

Key Waiter: Waits for a key to be pressed.

Keyboard Camera Orbit: Makes a Camera orbit round a 3D Entity using keyboard with limited angles.

Keyboard Controller: Emulates joystick messages using the keyboard.

Keyboard Mapper: Binds specific messages to keyboard keys.

L

Launch Scene: Launches a specified scene.

Layer Slider: Impede the 3d object to enter into no-null squares of a specific layers.

Leave Critical Section: Makes the attached object leave the critical section.

Lens Flare: Renders the Light with a specific 'Light Texture'.

LIFO: Last In First Out

Light Sprite: Renders the Light with a specific 'Light Texture'.

Lightmap: Calculates lightmaps (textures containing lighting and shadows) for a set of objects with a set of lights.

Linear Progression: Increments from 'Start Value' to 'End Value' in 'Number of Steps' steps.

LinearParticleSystem: Emits particles from a line

Load String: Loads a string from a file.

LOD Character Animation: Sets the level of detail for character animations.

LOD Manager Options: Set and Get information about the LOD Manager.

Look At: Makes a 3D Entity's local Z axis point to a given position.

M

Make Rows Unique: Assures the uniqueness of the elements of a column.

Make Transparent: Makes a Render Object (3D or 2D Entity) Transparent.

Mark System: Creates marks (single or continuous) on surfaces.

Merge Mesh: Merge the owner mesh with the mesh of the given entity.

Mesh Morpher: Makes a mesh out of two (that must have the same number of vertices).

Midi Event: Gets a Midi event ON/OFF.

Midi Player: Plays/Stops a MIDI sound.

Mimic: Makes a 3D Entity copy the motion of another one.

Mini Calculator: Processes a simple operation (+,-,*,/) between 'a' and 'b'

Modify Component: Modify a vector

Motion Blur: Performs a Motion Blur when the 3D Entity is moving.

Mouse Camera Orbit: Makes a Camera orbit round a 3D Entity using Mouse.

Mouse Cursor: Display a texture instead of the standard cursor.

Mouse Cursor System: Change the system mouse cursor pointer.

Mouse Waiter: Activates different outputs according to mouse actions.

Move Column: Moves a column of the array.

Move Row: Moves a row of the array.

Move To: Makes a 3D Entity move to a specified position.

Movie Load: Loads a movie file into a texture or a Sprite.

Movie Player: Plays a Movie (avi)

Multi Collision Detection: Detects the collision between any 3D objects declared as obstacles.

Multi Mesh Morpher: Transforms the current mesh so it matches the interpolation of other meshes (ie there vertice)

N

Navigate: Performs a Navigate in the Web Browser

Noise: Displaces the vertices of the mesh with a random vector.

Noise Progression: Interpolates a float according to a Perlin noise function in the [Min,Max] range, in a given number of milliseconds (or frames).

Nop: Join several links and dispatch the stream to all the outputs.

O

Object Between: Tests if there is an object between the two given entities

Object Copy: Duplicates objects

Object Create: Creates an object

Object Delete: Deletes an object

Object Keep On Floor: Forces an object stay on a declared floor (so it will not hover above it).

Object Keep On Floor V2: Forces an object to stay on a declared floor (so it will not hover above it).

Object Load: Loads a local file, containing one or more objects

Object Rename: Renames an object

Object Slider: Object Ball Slider ; Impede the 3d object from penetrating a 3dobject in the specified group.

ObjectParticleSystem: Emits particles from an object surface

Objects With Attribute Iterator: Retrieves each element of a group with a particular attribute

One At A Time: When reseted, this building block activates a Output corresponding to the last activated Input.

Op: Process any existing Parameter Operation (go to settings).

Open File: Opens the file

Orthographic Zoom: Emulates a zoom when the viewing mode is orthographic.

Output To Console: Displays a string in the Dev console.

P

Panning Control: Sets the panning for a sound, regardless of whether it is playing or not.

Parameter Selector: According to the Input activated, routes the corresponding Input Parameter to the Output Parameter.

Per Second: Calculates a progression (Y) according to a given speed (X) : Y=X*Elapsed Time During One Frame. X can be either an Angle, a Float, a Percentage, Vector or a 2dVector.

Pitch Control: Sets the pitch frequency for a sound, regardless of whether it is playing or not.

Pixel Value: Return the color of a given texture's pixel.

Planar Filter: Sets an filter color and an additionnal color to recover all the scene.

Planar Mapping: Maps an Object according to the Planar.

Planar Reflection: Creates a reflection on a plane of objects in a group.

Planar Shadow: Display planars shadows of selected objects projected from a light.

PlanarParticleSystem: Emits particles from a plan

Play Animation 3D Entity: Makes a 3D Entity perform an animation.

Play Global Animation: Makes several 3D Entities perform a global animation.

Play Sound Instance: Plays the totality of a sound once, optionally attaching it to an object.

Point Particle System: Emits particles from a point

Portal Management: Automatically hide places which can't be see through visible portals.

Position On Curve: Places a 3D Entity at a specific position on a 3D Curve.

Position Sound: Attaches a sound to an object.

Precompute Lighting: Precompute the lighting of an object.

Prevent Collision: Prevents the 3DEntity from colliding obstacles.

Priority: Sets priorities between several signals (Inputs Activation).

Proximity: Compares the distance between two 3D Entities with a given threshold distance.

PushButton: Transforms a 2D Frame into a push button.

R

Random: Retrieves a Random Variable between 'Min' an 'Max'.

Random Switch: Switches the sequential stream to a randomly chosen ouput according to each coef.

Ray Box Intersection: Returns the nearest object intersected by the ray, the position of the intersection point and the normal at this point.

Ray Intersection: Returns the nearest object intersected by the ray, the position of the intersection point and the normal at this point.

Read Config: Read Data in a user specific storage place.

Read Midi: Reads a Midi signal.

Read State: Read an object state.

Remove Attribute: Removes an attribute from the object.

Remove Channel: Removes a channel material from the 3D Entity.

Remove Column: Removes a column of the array.

Remove Control Point: Allows to shoot a control point of the curve

Remove From Group: Removes the object from a Group.

Remove Key Row: Remove elements from an array.

Remove Mesh: Removes a mesh from the selected 3d Entity.

Remove Object From Scene: Remove an object from a specified scene.

Remove Row: Remove a row of the array.

Remove Row If: Remove rows matching a value from an array.

Render Curve: Renders the curve with a specific material.

Render Scene: Renders the scene into a RenderTarget View

Render Scene With Material: Renders the scene into a RenderTarget View with all meshes using a single material.

Render Scene With Pass: Renders the scene into a RenderTarget View; does processing on materials.

Rendezvous: Waits for a group of objects/characters expected to be at the rendez-vous to all be present in order to allow them to pass through. You need to choose a Meeting Name and a Number of participants.

Replace Rendering: Replace the rendering of a mesh's material just before it's rendering.

Resize View: Allows main view to be resized.

Restore IC: Restores an object's Initial Condition for the scene being played.

Reverse Order: Reverse the rows order of the array.

Reverse String: Reverse the given string.

Rotate: Rotates the 3D Entity.

Rotate Around: Rotates a 3D Entity around another object.

Row Search: Get the first row index found in an array, where the value in the chosen column match the comparison with the reference value given.

Run VSL: Run a VSL script

S

Save State: Saves an object state.

Scale: Scales the 3D Entity (relatively to its current size or not).

Scan String: Retrieves values (float, vector or anything else) from a string.

Screen Mapping: Maps an Object according to the screen.

Search: Performs a Search in the Web Browser

Select Mesh: Selects which mesh should be used to represent the 3D entity.

Send Message: Sends a Message to a 3D Entity.

Send Message To Group: Sends a Message to each Object of a Group.

Sequencer: When 'In' is activated for the nth time, exits by the nth output.

Set 2D Material: Sets the material of a 2D Entity.

Set 2D Parent: Sets the Parent of a 2D Entity.

Set 2D Position: Set the position of a 2D Entity

Set 3DSprite Mode: Sets the orientation mode of the 3D Sprite.

Set Alpha Test: Setups the Alpha Test of a Material.

Set Ambient: Sets the Ambient Color of a Material.

Set Ambient Light Color: Sets the ambient light color.

Set Animation Frame: Places the character in a specified frame of an animation cycle.

Set Animation Step: Places the character in a specified frame of an animation cycle.

Set Animation Step Entity: Sets the advancement in percentage of the character's animation.

Set As Active Camera: Tells the camera to be the active one.

Set Attribute: Gives an attribute to the object, and/or sets the value of this attribute.

Set Background Color: Sets a background color.

Set Background Image: Places a background image.

Set Background Material: Sets the Background Material

Set Blend Modes: Sets the blend modes of a Material.

Set Blended Animation Factor: Sets the coefficient of interpolation of a blended animation

Set Bodypart Animation Frame: Places a character's body part in a specified frame of an animation cycle.

Set Both Sided: Sets the Material to be rendered even if the face normals doesn't faces the camera.

Set Camera Target: Makes a 3D Entity be the target of a camera.

Set Caret Position: Insert a caret into a string.

Set Cell: Sets the element of a chosen row and column.

Set Channel Dest Blend: Sets the dest mode when Blending the Material of a specific channel.

Set Channel Material: Sets the Material of a Channel applied to the 3D Entity.

Set Channel Src Blend: Sets the Source mode when Blending the Material of a specific channel.

Set Clipping Planes: Sets the near and the far clipping plane of a camera.

Set Color Key: Sets the transparent color key of the selected texture.

Set Color Key 2D: Sets the transparent transparence color key for a sprite.

Set Component: Composes a COLOR, VECTOR or 2dVECTOR, by specifying each components.

Set Control Point Properties: Allows to set parameter values of a control point

Set Current Slot: Changes the current slot of the texture.

Set Curve Properties: Allows to set parameter values of curve

Set Diffuse: Sets the Diffuse Color of a Material

Set Emissive: Sets the Emissive Color of a Material

Set Euler Orientation: Sets the orientation of a 3D Entity with Euler angles.

Set Face Count: Set the number of faces of a mesh.

Set Face Properties: Set the properties of a Face.

Set Fill Mode: Sets the fill mode of a Material : 1 = Point, 2 = WireFrame, 3 = Solid.

Set Floor Reference Object: Sets the bodypart used to represent floor reference for the Character

Set Fog: Sets the Atmospheric Fog.

Set Font Properties: Sets the visual appearance of a font.

Set FOV: Sets the Field Of View of the camera

Set Global Animation Step: Sets the advancement in percentage of the global animation.

Set Grid Priority: Sets the grid's priority

Set IC: Saves an object's Initial Condition in the scene being played.

Set Key Row: Sets the elements of a row, using the key column as a search criterion.

Set Light Attenuation: Sets the Constant, Linear and Quadratic Attenuation of a light.

Set Light Color: Sets the Color of a Light.

Set Light Range: Sets the range of the light.

Set Light Target: Makes a 3D Entity become the target of a light.

Set Light Type: Sets the type of a Light.

Set Lighting Mode: Sets the Lit mode of a mesh (lighting / no lighting).

Set Listener: Sets the listener of the sound.

Set Listener Properties: Controls the listener properties.

Set Local Matrix: Sets the Local Matrix of the 3D Entity.

Set LOD Attribute: Set the LOD Attribute on an object.

Set Material: Sets the material of the 3D Entity (or replace an existing one).

Set Material Effect: Enables a special effect on a material.

Set Material Z Buffer: Sets the Z buffer rendering options of the material.

Set Midi Input Port: Sets the Midi Input Port (usally 0).

Set MipMap Level: Set the MipMap level of the texture.

Set MipMap Texture: Set the 'Full Size Texture' to contain the given mipmap textures.

Set Orientation: Sets the orientation of a 3D Entity.

Set Parent: Sets the Parent of a 3D Entity.

Set PatchMesh Steps: Sets number of steps used to render a PatchMesh.

Set Pickable: Sets the pickable state of a 3D Entity

Set Portal: Defines a 3D Entity as a portal between 2 places.

Set Position: Sets the Position of a 3D Entity.

Set Prelit Color: Sets the color of a Prelit 3D Entity ( and Prelit the 3D Entity if it wasn't )

Set Progressive Mesh Options: Sets the options of the progressive mesh.

Set Projection: Sets the Projection Type of the Camera.

Set Quaternion Orientation: Sets the orientation of a 3D Entity with a quaternion.

Set Rectangles: Set the destination and/or source rectangles of a 2DEntity

Set Render Options: Set the flags of the render context.

Set Render Order: Tells the object to be displayed FIRST, LAST, or in a normal way.

Set Row: Set the elements value of a row of an array.

Set Shade Mode: Sets the Shade Mode of a Material

Set Shader Parameters: Sets one or more parameters of the material's shader.

Set Shader Technique: Sets shader material's technique.

Set Sound Cone Values: Control the cone shape of the 3D sound.

Set Sound Range: Control the range of the 3D sound.

Set Sound Type: Tells if a sound is to be render in background or in 3d space.

Set Specular: Sets the Specular Color of a Material

Set Specular Flag: Tells whether a light should be specular or not.

Set Square From 3D Pos: Sets the value of a square

Set Texture: Sets the Texture of a Material.

Set Texture Mag: Sets the Material Filtering Mode when it is magnified.

Set Texture Min: Sets the Material Filtering Mode when it is minimized.

Set Transparent: Puts the Transparent flag to a Mesh (Allow Transparency to be applied with no ZBuffer problems)

Set Vertex Count: Set the number of Vertexs of a mesh.

Set Vertex Properties: Set the properties of a vertex.

Set World Matrix: Sets the World Matrix of a 3D Entity.

Set Wrap Mode: Sets the way the texture applied to the mesh will be tiled.

Set Z Buffer: Change the way the object read and write into the ZBuffer.

Set Zoom: Sets the Zoom (or Lens) of a perspective camera (millimeter).

ShadowCaster: Projects a shadow of the target object.

ShadowStencil: Use the stencil buffer to create a shadow volume that cast on objects using the ShadowStencil attribute.

Share Character Animation Keys: Share animations keys of with all characters in a group.

Show: Shows a 2D/3D Entity, a Mesh or a Group

Show Mouse Cursor: Show/Hide the mouse cursor.

Show Object Information: Shows the bounding box and the normals of a 3D Entity.

Shuffle Order: Shuffle the rows order of the array

Simple Shadow: Display a little soft shadow on floors beneath the object.

Sine Deform: Applies a time-dependent sinusoidal deformation to each vertice of the mesh.

Skin Join: Deforms a join so it sticks on the objects it's joined.

Sky Around: Simulates a Sky Effect on the Scene using 6 textures in a cube; This behavior doesn't need loop.

Sky Around(CubeMap): Simulates a Sky Effect on the Scene using a cube map texture on a cube; This behavior doesn't need loop.

Solid Trail: Create a Solid Trail following the 3D Entity when it's moving.

Sort Rows: Sorts the rows of an array, according to the values of a given column.

Sound Load: Loads a sound file into a sound object

Specific Bool Event: Detects a boolean value change. Same as 'BoolEvent', but with specific outputs.

Sphere Slider: Impede the 3D object from penetrating a 3dobject considered as a sphere of a specified radius in the specified group.

Sphere Sphere Intersection: Detects the collision between two 3D entities at the bounding sphere level.

Spherical Mapping: Maps an Object according to the Spherical.

SphericalParticleSystem: Emits particles from a sphere

Spot Light Properties: Sets the properties of a spotlight (internal and external diameter of the light cone).

Sprite Load: Loads a sprite file into a sprite or a ABPosFinder.

Sprite Movie Player: Plays a movie in a 2d Sprite (avi)

Sprite Multi Angle: Replaces the 3D Entity by a 3D sprite.

Static Lightmap: Generates objects with lightmaps (textures containing lighting and shadows).

Statistics: Returns the needed statistics about the system.

Stop & Go: Activates the output only when the input stops being active.

Streaming Event: Activates outputs on the input activation change.

Stretch: Stretches an object, equivalent to scaling it with a stretch factor along the selected axis and with the opposite factor along the two other axes.

Swap Rows: Swaps two rows of an array.

Switch If Square: Switch streaming if the value on the specified layer on the specified position isn't NULL.

Switch On Key: Activates the appropriate output when receiving a Key.

Switch On Message: Activates the appropriate output when receiving a message.

Switch On Midi: Activates the appropriate output when receiving a Midi event.

Switch On Parameter: Switches the sequential stream to the corresponding ouput, following the result of comparison between 'Test' and the others input parameters

Synchro Player: Produce streaming events that match the one recorded with 'Synchro Recorder'.

Synchro Recorder: Records some input keys events by putting them in a data array which could used with 'Synchro Player' building block.

T

Taper: Modifies the mesh by scaling one end of it and changes the amount of tapering and the curvature of the effect.

Test: Activates the appropriate output, according to the test between A and B.

Test Cell: Compare an array element (cell) with a given reference value.

Text Display: Displays a text on top of the 3D environment

Texture Displace: Displaces the vertices of the mesh, according to the luminosity of the texture mapped to this vertex.

Texture Load: Loads a texture file into a texture or a Sprite.

Texture Render: Render an image in the texture of a 3D Entity.

Texture Scroller: Scrolls the UV coords of a mesh's material (or one of its channel).

Texture Sine: Produces a sinusoidal displacement on the UV coords of a mesh's material (or one of its channel).

Threshold: Binds a variable between two limits (Min and Max), and exit by the corresponding output according to the comparison result.

Time Settings: Set All Time Settings

Timer: Waits (throw looping) for a given time to has elapsed.

Translate: Translates a 3D Entity.

Trigger Event: activates 'Activated' output when 'In' begins to be activated / activates 'Deactivated' output when 'In' stops being activated.

Twist: Twists an object around an axis. You can choose the angle of twisting and the bias, ranging from -100 to 100.

U

Unlimited Controller: Controls a character by using animations played in response to messages.

Update Nodal Path: Reevaluates the nodes distance of the given nodal path.

Use Z information: Hides the object but uses its Z information during rendering

V

Value Count: Returns the number of elements in a column matching the given value.

Variation: Computes the difference between old and new value of X.

Vertex Render: Renders the object with a specific sprite at the vertices positions.

Vertex Translate: Translates one or more vertices of the current mesh.

Vertigo: Creates a 'Vertigo' effect on the Camera.

Volume Control: Controls the volume of a sound, either it is playing or not.

Volumetric Fog: Volumetric Fog.

W

Wait For All: Waits until all behavior Inputs have been activated to activate the output

Wait Message: Waits the receipt of a Message.

Water Texture: Apply a water matrix to the texture.

Wave Player: Plays a Wave Sound File, with possible fade in and/or fade out; the fades values are done in seconds;

Web Download: Download a file from a webserver.

Web Get Data: Gets data associated with an URL.

While: Loops while 'Condition' is TRUE.

Write Config: Write Data in a user specific storage place.

Write In Texture: Write a colored pixel in the texture.


Building Block Categories

Behavior Building Block Categories

3D Transformations contains behaviors to make both simple and complex changes to entities.
Cameras includes behaviors that control camera parameters, positions and special effects.
Characters assembles behaviors that control characters and allow you to make specific changes.
Collisions contains behaviors that define, test and manage collisions between the boundaries of various objects.
Controllers contains behaviors that process messages sent from the mouse, keyboard and joystick, used to trigger changes or events in a scene.
Grids allow you to manage an events generating grid.
Interface contains behaviors that create and manage interface components displayed in a composition (text, buttons, etc.).
Lights groups together behaviors that control light parameters and special effects.
Logics includes low-level behaviors that establish logical interactivity, such as testers, event synchronizers, algorithms, counters, mappers, message handlers, interpolators, and group/hierarchy.
Materials-Textures contains behaviors that modify material properties and textures.
Mesh Modifications contains behaviors that modifies the meshes of 3D Entities.
Narratives groups behaviors that effect the narrative flow of a composition, in order to launch a new scene or exit the game for example.
Optimizations contains behaviors used to optimize compositions such as the level of detail.
Particles contains behaviors that produce particles for special effects.
Shaders contains behaviors that control shaders.
Sounds contains behaviors that attribute, play and control sounds.
Visuals contains behaviors to create and control visual effects in scenes.
VSL contains the Run VSL BB that allows you to execute VSL (Virtools Scripting Language) scripts.
Web contains behaviors for web browser interaction.
World Environments contains behaviors that control and change background properties, including special effects.


Obsolete Building Blocks

Add Object To Group: Adds the Object to a Group.

Add Obstacle: Adds the 3D Entity to the list of the Collision Manager.

Avoid Obstacles: Modifies the 'Direction' input parameter to avoid obstacles.

Bezier Interpolator: Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of steps.

Character Keep On Floor Limits: Forces a character to keep to a floor's limits, simulating a collision with a wall if the character tries to venture outside.

Character Prevent From Collision: Prevents the character from colliding obstacles.

Create Blended Animation: Creates a new animation by merging two exsiting animations.

Display Score: Displays a score in 2d

Enhanced Character Controller: Controls a character by using 7 animations reacting to a joystick or keyboard.

Fade In: Fades in sound(s).

Fade Out: Fades out sound(s).

FPS: Writes in the output the FPS (Frames Per Second).

Get Euler Orientation: Gets the orientation of a 3D Entity with Euler angles.

Has Attribute Obsolete: Gets the parameter of an attribute (if it exists) on the given object.

Hide 2D Entity: Hides a 2D Entity

Interpolator Color: Performs a linear interpolation between 2 colors.

Interpolator Float: Performs a linear interpolation between 2 floats.

Interpolator HSV Color: Interpolates a color Using HSV color Model

Interpolator Int: Performs an interpolation between 2 integers.

Interpolator Matrix: Performs a linear interpolation between matrices.

Interpolator Vector: Performs a linear interpolation between 2 vectors.

Level Of Detail: Chooses the mesh with the appropriate level of detail according to the distance of the camera to the object.

Light Color Progression: Makes a Light progressively change from one color to another.

Look At Pos: OBSOLETE - please see 'Look At' instead.

Object Rename: Renames an object

Pause & AntiAlias: AntiAlias current scene and pause rendering.

Remove Attribute Obsolete: Removes an attribute from an object.

Remove Object From Group: Removes the object from a Group.

Set Attribute Obsolete: Gives an attribute to an object, and/or sets the value of this attribute.

Set Dest Blend: Sets the Destination Mode when Blending is used on the material of the 3D entity.

Set Linear Attenuation: Sets the value of the 'Linear Attenuation' of a Light

Set Material 3DSprite: Sets the material of the 3D Sprite.

Set Priority: Controls the Priority of a sound, either it is playing or not.

Set Quadratic Attenuation: Sets the value of the 'Quadratic Attenuation' of a Light.

Set Scale: Sets the Scale of a 3D Entity.

Set Specular Power: Sets the Power value of the Material (specular shape of the reflected light).

Set Src Blend: Sets the Source mode when Blending the Material.

Show 2D Entity: Shows a 2D Entity

Sound Manager Setup: Controls the listener properties.

Test Bounding Box Y Overlapping: Tests the Y Relative Position of the bounding boxes of two 3D Entities, in the world coordinate system.

Time Bezier Interpolator: Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of milliseconds.


3D Transformations

Animation

Animation Recorder: Records the Position+Orientation+Scale as an animation.

Play Animation 3D Entity: Makes a 3D Entity perform an animation.

Play Global Animation: Makes several 3D Entities perform a global animation.

Set Animation Step Entity: Sets the advancement in percentage of the character's animation.

Set Global Animation Step: Sets the advancement in percentage of the global animation.

Basic

Add Child: Adds a child to the 3D Entity's hierarchy

Rotate: Rotates the 3D Entity.

Rotate Around: Rotates a 3D Entity around another object.

Scale: Scales the 3D Entity (relatively to its current size or not).

Set Euler Orientation: Sets the orientation of a 3D Entity with Euler angles.

Set Local Matrix: Sets the Local Matrix of the 3D Entity.

Set Orientation: Sets the orientation of a 3D Entity.

Set Parent: Sets the Parent of a 3D Entity.

Set Position: Sets the Position of a 3D Entity.

Set Quaternion Orientation: Sets the orientation of a 3D Entity with a quaternion.

Set World Matrix: Sets the World Matrix of a 3D Entity.

Translate: Translates a 3D Entity.

Constraint

Billboard: Makes a 3dEntity act like a billboard sprite (with possible constant texture ratio for a face).

Keep At Constant Distance: Selected object will follow another object wherever it goes, keeping the same distance between them.

Look At: Makes a 3D Entity's local Z axis point to a given position.

Mimic: Makes a 3D Entity copy the motion of another one.

Object Keep On Floor: Forces an object stay on a declared floor (so it will not hover above it).

Object Keep On Floor V2: Forces an object to stay on a declared floor (so it will not hover above it).

Curve

Add Control Point: Allows to extend a curve with a new control point

Curve Follow: Moves a 3D Entity along a path.

Get Control Point Properties: Allows to get parameter values of a control point

Get Curve Properties: Allows to get parameter values of curve

Position On Curve: Places a 3D Entity at a specific position on a 3D Curve.

Remove Control Point: Allows to shoot a control point of the curve

Set Control Point Properties: Allows to set parameter values of a control point

Set Curve Properties: Allows to set parameter values of curve

Movement

Move To: Makes a 3D Entity move to a specified position.

Nodal Path

Activate Link: Activates or deactivates a link between two nodes of a Nodal Path.

Activate Node: Activates or deactivates a node in a Nodal Path.

Character Go To Node: Makes the target character walk to the selected node, by taking the shortest path possible.

Create Nodal Path: Creates a Nodal Path out of a group of frames.

Entity Find Nodal Path: Finds the shortest path to a specified destination for a 3D Entity.

Find Curved Nodal Path: Retrieves a curve to follow between a starting point and a destination point.

Find Path: Returns a group of nodes to go by to reach a goal from a starting point.

Update Nodal Path: Reevaluates the nodes distance of the given nodal path.


Activate Link BB

 Activate Link
Version 1.00 - Virtools
Categorized in 3D Transformations/Nodal Path

Description

Apply to a BEOBJECT.
Activates or deactivates a link between two nodes of a Nodal Path.
Activate Link.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Nodal Path: nodal path to which the link belongs.
Start Node: link's starting point (node).
End Node: link's ending point (node).
Activate: link will be activated if TRUE, otherwise link will be deactivated.
TwoWay: building block will be applied to both directions if TRUE and if link is two way.

More information on Nodal Paths.
See also: other Nodal related building blocks in the Nodal Path folder of 3D Transformations.

Warning

- If the two nodes aren't directly linked together, the "Activate Link" building block won't activate all the links that lead from one to another.


Activate Node BB

 Activate Node
Categorized in 3D Transformations/Nodal Path

Description

Apply to a BEOBJECT.
Activates or deactivates a node in a Nodal Path.
Activate Node.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Nodal Path: nodal path to which the node belongs.
Node: object representing the node to activate or deactivate.
Activate: node will be activated if TRUE, otherwise node will be deactivated.

If a node is deactivated, then all links leading to or from the node will also be deactivated.
More information on Nodal Paths.
See also: other Nodal related building blocks in the Nodal Path folder of 3D Transformations.


Add Child BB

 Add Child
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Adds a child to the 3D Entity's hierarchy
Add Child-Set Parent.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Child: 3D Entity to be attached as child.

Adds a Child to the 3D Entity's hierarchy.
See also: Set Parent.

Warning

- This building block sets a state on the object. Which means, once it is activated, the state will be kept as it is until a 'SetParent' is called on the child (this can also occur when reseting IC).
Therefore, if you want initial hierarchy to be reseted as it was before activating this building block, you'll need to put Initial Conditions (IC) on the child.


Add Control Point BB

 Add Control Point
Categorized in 3D Transformations/Curve

Description

Apply to a CURVE.
Allows to extend a curve with a new control point
Add Control Point.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Position: position expressed in a given referential.
Referential: object used as point of reference for the position of new point.
Prior Point Index: index of the point which comes after the new one. -1 means the new point will be inserted after all the other ones.

Curve Point: created curve point.
Percentage: position percentage on the curve (0%=begining, 100%=finnish) (updated only if the second setting is TRUE).

Dynamic: if TRUE, the curve point will be dynamic.
Update Percentage: if TRUE, the position percentage will be updated. FALSE by default, because it is time consuming.
This behavior adds a new control point to a curve.


Animation Recorder BB

 Animation Recorder
Categorized in 3D Transformations/Animation

Description

Apply to a BEOBJECT.
Records the animation of an object or Group of objects by storing Position+Orientation+Scale keys every n frames.
Animation Recorder-Play Animation 3D Entity.cmo

Technical Information

On: starts recording.
Off: stops recording.

Out On: activates when recording starts.
Out Off: activates when recording stops.

Object(s): object(s) whose motion is to record.
Animation Name: name of the animation to create.
Frame Step: the sampling rate; i.e. record animation keys every n frames. The lower the Frame Step, the greater the number of keys recorded resulting in a higher quality animation but also a greater file size.

Animation: the animation recorded/created.

Use Grouped Animation: if unselected, Animation Recorder records the motion of a single object - Object(s) is set to 3D Entity, and the Animation created is an Object Animation. If selected, Animation Recorder records the motion of all objects in a Group - Object(s) is set to Group, and the Animation created is a (Global) Animation.

Warning

Do not modify any pIns while recording.
If you use the name of an animation that already exists, the animation is replacd with the animation created by Animation Recorder BB.

See Also: Play Animation 3DEntity BB, Play Global Animation BB, Set Animation Step on 3D entity BB.


Billboard BB

 Billboard
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
Makes a 3dEntity act like a billboard sprite (with possible constant texture ratio for a face).
Billboard.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Face Index: index of the face which orientation should be toward. If you provide a negative number, the building block will only take the Local Direction and the Local Up axis into concideration to orientate the object.
Local Dir: if you do not specify any face index (nothing or -1), this vector will represent the vector in your object referential which is to be bound to the Z world axis.
Local Up: if you do not specify any face index (nothing or -1), this vector will represent the vector in your object referential which is to be bound to the Y world axis.
Texture Factor: if TRUE, the object will be positioned so that the texture on the specified face will have exactly the same size that if it were seen in 2d (just like its representation in the texture setup).
Apply Transformation: if TRUE, the object world matrix will be bound to the calculate one. Otherwise, the object won't move, and the world matrix will only be put in the output parameter.
Scale Instead Of Move: if TRUE, the object will be scale instead of moving to match the texture scale.(only implemented on 3D Sprites for now.)

This building block is useful to make the texture of an object allways have a constant aspect ratio.
Suppose you have a cube with 6 texts written on each faces. If you want the text to be seen exactly as it has been writen (not stretched, but exactly the same aspect), you would use this building block, with a "Face Index"=index of your face, and a "Texture 1/1"=TRUE.

Warning

- if you specify a "Face Index" (other than a negative number), the Local Direction and Local Up won't be taken into concideration.


Character Go To Node BB

 Character Go To Node
Categorized in 3D Transformations/Nodal Path

Description

Apply to a CHARACTER.
Makes the target character walk to the selected node, by taking the shortest path possible.
Character Go To Node.cmo

Technical Information

In: triggers the process.
Loop In: triggers the next step in the process loop.
Stop: deactivates the building block and free the links the character was currently occupying.

Arrived: is activated when the distance between the character and the "Goal Node" is lower than the "Guard Distance" input parameter.
Can't Go: is activated if the character is unable to get to the selected node.
Loop Out: is activated when the process needs to loop.

Nodal Path: nodal path to go through.
Goal Node: destination to reach.
Guard Distance: distance just before destination node where character should stop.
Character Direction: defines the character's frontal direction.
Limit Angle: limits the angle between character's direction and destination node. Value should not be less than 20 degrees.
Mark Occupation: if TRUE, node or link character currently occupied is marked as occupied, and no other character can use it.

Turn With Messages: character will respond to messages from a character controller (e.g. Joystick) if this checkbox is crossed.
Rotation Speed: speed at which character turns, if this is not handled by messages. Range is between 1 = slow, and 100 = instantaneous.


Create Nodal Path BB

 Create Nodal Path
Categorized in 3D Transformations/Nodal Path

Description

Apply to a GROUP.
Creates a Nodal Path out of a group of frames.
Find Path.cmo

Technical Information

Debug Display: check this if you want the nodal path to remain visible while in play.

This building block allows the user to create a Nodal Path (through a customized dialog box).

More information on Nodal Paths.
See also: other Nodal related building blocks in the Nodal Path folder of 3D Transformations.


Curve Follow BB

 Curve Follow
Categorized in 3D Transformations/Curve

Description

Apply to a 3DENTITY.
Moves a 3D Entity along a path.
Curve Follow-Position On Curve.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Curve to cover: 3D Curve to follow.
Duration: how long the whole process should last.
Progression Curve: 2D Curve representing the progression of the 3D Entity along its movement.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolates at the same time (in the same loop) a color value, a vector, a orientation or something like this.
Value: current Bezier-interpolated value.

Time Based: If checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.

See Also: 'Position On Curve'.

Warning

- If your not in Time Based mode, changing the Velocity during loop will have no effect.
- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.
- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.
(for the 'Progression' output parameter)


Entity Find Nodal Path BB

 Entity Find Nodal Path
Categorized in 3D Transformations/Nodal Path

Description

Apply to a 3DENTITY.
Finds the shortest path to a specified destination for a 3D Entity.
Entity Find Nodal Path.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Nodal Path: group of nodal paths to search in.
Goal Object: destination to reach.

Group: list of nodes passed though on way to destination. List will be empty if no path is found.

The building block will search the node closest to its owner first, finding the shortest path to the destination node.
More information on Nodal Paths.
See also: other Nodal related building blocks in the Nodal Path folder of 3D Transformations.


Find Curved Nodal Path BB

 Find Curved Nodal Path
Categorized in 3D Transformations/Nodal Path

Description

Apply to a BEOBJECT.
Retrieves a curve to follow between a starting point and a destination point.
Find Curved Nodal Path.cmo

Technical Information

In: triggers the process.

Path Found: is activated when the process is completed.
No Path Found: is activated if no curved path can be found.

Nodal Path: group of nodal paths to search in.
Start Object: starting point.
Goal Object: destination to reach.
Fitting Coef: percentage value [0% to 100%] which will soften the curve produced.

Curve: 3D Curve to follow to reach the goal. Path Follow or Set Curve Step can be used to go through the 3D Curve.

More information on Nodal Paths.
See also: other Nodal related building blocks in the Nodal Path folder of 3D Transformations.


Find Path BB

 Find Path
Categorized in 3D Transformations/Nodal Path

Description

Apply to a BEOBJECT.
Returns a group of nodes to go by to reach a goal from a starting point.
Find Path.cmo

Technical Information

In: triggers the process.

Path Found: is activated if a path is found.
No Path Found: is activated if no path is found.

Nodal Path: group of nodal paths to search in.
Start Object: starting point.
Goal Object: destination to reach.

Object List: list of nodes passed though on way to destination. List will be empty if no path is found.

More information on Nodal Paths.
See also : other Nodal related building blocks in the Nodal Path folder of 3D Transformations.


Get Control Point Properties BB

 Get Control Point Properties
Categorized in 3D Transformations/Curve

Description

Apply to a CURVEPOINT.
Allows to get parameter values of a control point
Get Control Point Properties.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Bias: inflex of the tangent of curve at the control point.
Tension: absolute value of the tangent vector.
Continuity: angle between right tangent vector and left one.
Linear: if TRUE, then curve at this point is not splined.

This behavior got all specified parameters of a curvepoint.


Get Curve Properties BB

 Get Curve Properties
Categorized in 3D Transformations/Curve

Description

Apply to a CURVE.
Allows to get parameter values of curve
Get Curve Properties.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Open: if TRUE, then the curve is not closed.
Number Of Steps: number of segments which compose the curve.
Fitting Coef: correlation of curvepoints.
Length: length of curve.

This behavior got all specified parameters of a curve.


Get Euler Orientation BB

 Get Euler Orientation
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
OBSOLETE - use the combination on the paramOps "Get World Matrix" and "Convert" instead.

Gets the orientation of a 3D Entity with Euler angles.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

X: rotation angle around X axis.
Y: rotation angle around Y axis.
Z: rotation angle around Z axis.

Warning

This building block is obsolete and is only included for backwards compatibility.


Keep At Constant Distance BB

 Keep At Constant Distance
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
Selected object will follow another object wherever it goes, keeping the same distance between them.
Keep At Constant Distance.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Position: vector expressed in the 'Referential'.
Referential: 3D object to follow.
Distance: distance to be kept between the 2 objects.
Attenuation: delay between second object following first object. A value of 0 (zero) would mean an instant response.
Hierarchy: if selected, then this behavior will also apply to the 3D Entity's children.

Time Based: If selected, this behavior will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.

This building block should be looped if the 3D Entity is to keep a constant distance from the object all the time.

Warning

- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.
Note: if you don't use any 'Attenuation' value (ie 0), the above remark is useless (because movement is instantaneous).
- If the current distance between the two objects is smaller than 0.001 units, the distance vector between objects will be cast to [ 0, 0, 0.001 ].


Look At Pos BB

 Look At Pos
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
OBSOLETE - see Look At BB.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Position: position vector to look at.
Following Speed: how fast the 3D Entity should take to look at the given position. The higher the percentage, the faster the 3D Entity will turn to look.
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

As you can do the same and better with 'LookAt' building block, the 'LookAtPos' building block is an obsolete one. This building block needs to be looped if you want to constantly look at the target.

Warning

This building block is obsolete and is only included for backwards compatibility.


Look At BB

 Look At
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
Makes a 3D Entity's local Z axis point to a given position.
Look At.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Position: position vector to look at.
Referential: 3D Entity referential from which the position is expressed.
Following Speed: how fast the 3D Entity should take to look at the given position. The higher the percentage, the faster the 3D Entity will turn to look.
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

Time Based: If checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.
Direction: specifies which base vector is to be the looking direction.
Roll: specifies number of turns and angle for 3D Entity when performing Look At behavior.

This building block should be looped if the 3D Entity is to keep a constant distance from the object all the time.

Warning

- This behavior does not work properly with animated characters as their directional axis is not Z.
When modeled, the 3D Entity's Z axis should be set as the object's looking direction, and the Y axis as the up direction.
- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.
Note: if you don't use any 'Following Speed' value (ie 100), the above remark is useless (because movement is instantaneous).


Mimic BB

 Mimic
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
Makes a 3D Entity copy the motion of another one.
Mimic.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Object: object to copy.
Copy Position: TRUE means the object's position will be copied.
Position Speed: how fast the 3D Entity is to copy the object's position. The higher the percentage, the faster the 3D Entity will do this.
Copy Orientation: TRUE means that 3D Entity will copy the object's orientation.
Orientation Speed: how fast the 3D Entity is to copy the object's orientation. The higher the percentage, the faster the 3D Entity will do this.
Copy Scale: TRUE means that the 3D Entity will copy the object's scale.
Scale Speed: how fast the 3D Entity is to copy the object's orientation. The higher the percentage, the faster the 3D Entity will do this.
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

Time Based: If checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.

This behavior needs to be looped, if you want the object to constantly mimic the target.

Warning

- If you want no attenuation during motion, you shouldn't use the 'Time Based' setting.
- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.
Note: if you don't use any '... Speed' value (ie 100), the above remark is useless (because movement is instantaneous).


Move To BB

 Move To
Categorized in 3D Transformations/Movement

Description

Apply to a 3DENTITY.
Makes a 3D Entity move to a specified position.
Move To.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out:is activated when the process needs to loop.

Destination Point: 3D position expressed in 'Destination Referential' co-ordinate system.
Destination Referential: coordinate system in which the position is expressed.
Duration: how long the whole process should last.
Progression Curve: 2D Curve representing the progression of the 3D Entity along its movement.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolates at the same time (in the same loop) a color value, a vector, a orientation or something like this.
Value: current Bezier-interpolated value.

Time Based: If checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.
Tip: Since the 'Progression' value is given as an output parameter, you can use it in the loop to interpolate the orientation of the object at the same time (with the 'Interpolator Orientation' building block for example).

Warning

- This building block has been designed to work with 3D Entities only. See 'Character Go To' for character displacement.
- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.
- When you use the 'Time Based' version of this building block, you can move the 'Destination Referential' and the 3DEntity will follow it (it is a new functionnality; specific to the 'Time Based' version). But as the 'Not Time Based' version is older than the 'Time Based' version (and therefore has to do the same thing as before), if you don't use 'Time Based' you'll not have the ability to move the 'Destination Referential' and make the 3DEntity understand you want it to follow the 'Destination Referential'.
- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.
(for the 'Progression' output parameter)


Object Keep On Floor V2 BB

 Object Keep On Floor V2
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
Forces an object to stay on a declared floor (so it will not hover above it).
Object Keep On Floor V2.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates when the process is activated with On.
Exit Off: activates when the process is deactivated with Off.
Touched Floor Limits: activates if the 3D Entity touches a floor limit.

Follow Inclination: if TRUE, then the object will always be upright, parallel to the face of the floor, even if there is a slope for example.
Replacement Altitude: distance of the object from the floor, 0 means touching.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.
Keep In Floor Boundary: if TRUE, the object will not be able to leave the floor's boundaries.
Detection Offset: distance from the bottom of the object after which a 3D Entity will take a floor above rather than a floor below.
Orientation Attenuation: attenuates the effect of Follow Inclination, with 100% being very rough, and 1% being very smooth.

Floor: object that has been chosen as the nearest floor.
Floor Type: type of floor chosen, for example grass, ice, tarmac etc. The type of floor is represented by a whole number defined by the user in Attributes Setup.
Floor Slope: slope of the floor in relation to the object's position.
Old Floor Distance: distance of the object off the floor before the object was forced to stay on it.

Object Extents: how the object should be represented for calculation purposes: a single point or a bounding box. An object with the bounding box setting needs 4 times more computation time than the single point version.

This building block makes a 3D entity stay on the floors, by testing either the bounding box of an object or a single point in relation to a floor.
Objects representing floors must be declared as floors first, either by using the building block Declare Floors or by setting Floor Attributes to them.

Warning

This building block needs to be looped for an object to be constrained to a floor all the time.
The building block "Character Keep On Floor" should be used for characters.


Object Keep On Floor BB

 Object Keep On Floor
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
Forces an object stay on a declared floor (so it will not hover above it).
Object Keep On Floor.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Makes a 3D entity stay on the floors.
This building block should be looped. It uses the object's bounding box to test the object's position relative to the floor. Floors must be defined beforehand, either by using the building block "Declare Floors" or by giving them the "Floor" attribute.

Warning

- You must loop this building block if you need to perform this action continually.
- This building block has been designed to work with 3D Objects only. See 'Character Keep On Floor' for characters.


Play Animation 3D Entity BB

 Play Animation 3D Entity
Categorized in 3D Transformations/Animation

Description

Apply to a 3DENTITY.
Makes a 3D Entity perform an animation.
Animation Recorder-Play Animation 3D Entity.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

One Loop Played: is activated once the animation has been performed.

Animation: animation to be performed.
Duration: how long the whole process should last.
Progression Curve: 2D Curve representing the progression of the animation.
Loop: TRUE means the animation will be looped.

Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%.

See Also: 'Play Global Animation', 'Set Animation Step on 3D entity'.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.


Play Global Animation BB

 Play Global Animation
Categorized in 3D Transformations/Animation

Description

Apply to a BEOBJECT.
Makes several 3D Entities perform a global animation.
Play Global Animation.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

One Loop Played: is activated once the animation has been performed.

Animation: animation to be performed.
Duration: how long the whole process should last.
Progression Curve: 2D Curve representing the progression of the animation.
Loop: TRUE means the animation will be looped.

Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%.
This behavior can be applied to any object or group of objects as it plays a global animation. However if applied to a character, the only animations available will be those that the character is registered as possessing.

See Also: 'Play Animation 3DEntity', 'Set Animation Step on 3D entity'.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.


Position On Curve BB

 Position On Curve
Categorized in 3D Transformations/Curve

Description

Apply to a 3DENTITY.
Places a 3D Entity at a specific position on a 3D Curve.
Curve Follow-Position On Curve.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Curve: 3D curve on which the 3D Entity will be positioned.
Progression: progression in percent on the curve (0% = start / 100% = end).
Follow: if TRUE, the 3D Entity's orientation will point in the direction of the curve's tangent.
Bank: if TRUE, the 3D Entity' will bank along the curve.
Bank Amount: level of banking effect (1 is a standard banking, 2 and higher values increase the effect).
Direction: specifies which base vector is to be the following direction (if the 'Follow' parameter is set to TRUE).
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

Roll: specifies number of turns and angle for 3D Entity when performing Look At behavior.

See Also: 'Curve Follow'.


Remove Control Point BB

 Remove Control Point
Categorized in 3D Transformations/Curve

Description

Apply to a CURVE.
Allows to shoot a control point of the curve
Remove Control Point.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

CurvePoint Object: handle of the curve point to remove.

This behavior removes a control point of the curve.


Rotate Around BB

 Rotate Around
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Rotates a 3D Entity around another object.
Rotate-Rotate Around.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Axis Of Rotation: vector expressed in a given referential.
Angle Of Rotation: angle in degrees and number of turns.
Referential: object used as point of reference for the rotation.
Keep Orientation: if TRUE, the 3D entity will keep its initial orientation during rotation.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

This building block makes a 3D Entity rotate around another 3D Entity (named as the referential for the axis).

See also: Rotate.


Rotate BB

 Rotate
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Rotates the 3D Entity.
Rotate-Rotate Around.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Axis Of Rotation: vector expressed in the given referential to define the orientation axis.
Angle Of Rotation: angle in degrees and number of turns.
Referential: referential used to define the direction of the rotation axis.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

This building block makes a 3D Entity rotate around its local axis. Use Rotate Around to rotate a 3D Entity around another object.

See Also: Rotate Around.


Scale BB

 Scale
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Scales the 3D Entity (relatively to its current size or not).
Scale.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Scale Vector: vector that defines the scale multiplication on the 3D Entity's X, Y and Z local axis.
Hierarchy: if TRUE, then this building block will also applies to the 3D Entity's children.
Absolute: if TRUE, the scale won't be relative to the current object's size, but absolute in the world (like the obsolete "Set Scale" BB).

For instance, whatever the initial scale vector of the object should be, a Scaling Vector with (1,2,2) values, doubles the current size on the Y and Z local axis, but doesn't change the size along the X local axis.

See also: Set Scale.


Set Animation Step Entity BB

 Set Animation Step Entity
Categorized in 3D Transformations/Animation

Description

Apply to a 3DENTITY.
Sets the advancement in percentage of the entity's animation.
Set Animation Step Entity.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Animation: specify which animation should be used.
Step: advancement in percentage of the animation (between 0 and 100).

You should use this building block to have an accurate control on the object's animation. See Also: 'Play Animation 3DEntity', 'Play Global Animation'.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.


Set Control Point Properties BB

 Set Control Point Properties
Categorized in 3D Transformations/Curve

Description

Apply to a CURVEPOINT.
Allows to set parameter values of a control point
Set Control Point Properties.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Bias: inflexes the tangent of curve at the control point.
Tension: modifies the absolute value of the tangent vector.
Continuity: defines the angle between right tangent vector and left one.
Linear: if TRUE, then curve at this point is not splined.

This behavior set all specified parameters of a curvepoint.


Set Curve Properties BB

 Set Curve Properties
Categorized in 3D Transformations/Curve

Description

Apply to a CURVE.
Allows to set parameter values of curve
Set Curve Properties.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Open: if TRUE, then the curve is not closed.
Number Of Steps: defines the number of segments which compose the curve.
Fitting Coef: defines the correlation of curvepoints.

This behavior set all specified parameters of a curvepoint.


Set Euler Orientation BB

 Set Euler Orientation
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the orientation of a 3D Entity with Euler angles.
Set Euler Orientation.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Orientation: rotation angle around X,Y and Z axis.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.
Referential: referential in which the angles are expressed (-NULL- in most cases).

Merge Angles Params: Use Euler Angles parameter type instead of 3 angle parameters.

Remarks

The Get Euler Orientation BB is now obsolete and is replaced by the Get Euler Orientation paramOp.


Set Global Animation Step BB

 Set Global Animation Step
Categorized in 3D Transformations/Animation

Description

Apply to a BEOBJECT.
Sets the advancement in percentage of the global animation.
Set Global Animation Step.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Animation: specify which animation should be used.
Step: advancement in percentage of the animation (between 0 and 100).

You should use this building block to have an accurate control on the object's animation. See Also: 'Play Animation 3DEntity', 'Play Global Animation'.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.


Set Local Matrix BB

 Set Local Matrix
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the Local Matrix of the 3D Entity.
Set Local Matrix.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Local Matrix: 4x4 local matrix.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

An object Local Matrix determines its orientation and position with regard to its parent's basis.
Which means for example, if the parent object moves, the child's local matrix will not necessarily be afected.

Warning

- Matrix is edited as the instantaneous matrix of a selected 3d Entity (kind of snapshot of the selected object orientation when it is picked in the dialog box). - The Matrix value won't change during play mode unless you use the building block as low-level building block, where the matrix parameter is a result of other building blocks and/or parameter operations.


Set Orientation BB

 Set Orientation
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the orientation of a 3D Entity.
Set Orientation.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Dir: determines the Z local axis direction.
Up: determines the Y local axis so that the Y/Z plane is the same as Up/Dir.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.
Referential: referential in which the 'Dir' and 'Up' vector are expressed (-NULL- in most cases).
Local Dir: determines the local vector that will be considered as Z axis.
Local Up: determines the local vector that will be considered as Y axis, so that the Y/Z plane is the same as Up/Dir.

Well, your maybe not comfortable with trigonometry, and anyway orientation in 3D-Space is always a critical problem, so let's take an example:
Say you want to orientate a gun toward a target.
Calculating the direction vector 'Dir' (joining the gun and its target) is not enough to determine the orientation of the gun: even though the gun is pointing in the right direction, the handle might not be in the right position.
We still need to determine the 'Up' vector. In this case, usinf the world 'Up' axis ensures that the gun will be properly oriented.
Specifying the 'Dir' and 'Up' vector is enough to determine the orientation of a 3D model provided that this model's local axes follow the default coordinate system: 'X' --> Right ; 'Y'--> Up ; 'Z'--> Front (or Direction). Otherwise, you need to specify which local axes to consider as the 'Dir' and 'Up' axes of the object.
Picture 1: the object's Y axis is oriented along the object's 'Up' direction, and the object's Z axis is oriented along the object's aiming direction.
You don't need to change the 'Local Dir', and 'Local Up' values.

Picture 2: the object's local axes are not correctly set. You will need to specify 'Local Dir'=[0,1,0] and 'Local Up'=[0,0,1].


Set Parent BB

 Set Parent
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the Parent of a 3D Entity.
Add Child-Set Parent.cmo.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Parent: 3D Entity to be set as parent. Use NULL to 'deparent' the entity (which means parenting it to the world).

See also: Add Child.

Warning

- This building block sets a state on the object. Which means, once it is activated, the state will be kept as it is until a 'SetParent' is called on the child (this can also occur when reseting IC).
Therefore, if you want initial hierarchy to be reseted as it was before activating this building block, you'll need to put Initial Conditions (IC) on the child.


Set Position BB

 Set Position
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the Position of a 3D Entity.
Set Position.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Position: position vector expressed in a given referential.
Referential: coordinate system in which the position is expressed.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.


Set Quaternion Orientation BB

 Set Quaternion Orientation
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the orientation of a 3D Entity with a quaternion.
Set Quaternion Orientation.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Orientation: the orientation quaternion.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.
Referential: referential in which the angles are expressed (-NULL- in most cases).


Set Scale BB

 Set Scale
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
OBSOLETE.

Sets the Scale of a 3D Entity.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Scale Vector: vector that defines the scale of the 3D Entity on its X, Y and Y local axis.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

A scale vector [1, 1, 1] sets the 3D Entity to its initial unit modelling size.
You can also scale a 3D Sprite.
- If the object has been modellized and then scaled, setting its scale to [1,1,1] could reduce or enlarge it.
- The "Set Scale" BB is now obsolete as it can be replace by the "Scale" BB if you set the pIn "Absolute" of this building block to TRUE.

See Also: Add Scale.

Warning

This building block is obsolete and is only included for backwards compatibility.


Set World Matrix BB

 Set World Matrix
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Sets the World Matrix of a 3D Entity.
Set World Matrix.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

World Matrix: 4x4 matrix.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

An object World Matrix determines its orientation and position with regard to the world basis.

Warning

- Matrix is edited as the instantaneous matrix of a selected 3d Entity ( kind of snapshot of the selected object orientation when it is picked in the dialog box). - The Matrix value won't change during play mode unless you use the building block as low-level building block, where the matrix parameter is a result of other building blocks and/or parameter operations.


Test Bounding Box Y Overlapping BB

 Test Bounding Box Y Overlapping
Categorized in 3D Transformations/Constraint

Description

Apply to a 3DENTITY.
OBSOLETE.

Tests the Y Relative Position of the bounding boxes of two 3D Entities, in the world coordinate system.

Technical Information

In: triggers the process.

A above B: is activated if the bounding box of ObjectA is above that of ObjectB.
B above A: is activated if the bounding box of ObjectB is above that of ObjectA.
A above B overlapped: is activated if the bounding box of ObjectA is above that of ObjectB, but overlapping.
B above A overlapped: is activated if the bounding box of ObjectB is above that of ObjectA, but overlapping.
A and B overlapped: is activated if both bounding boxes are at the same level, overlapping.

Object A: first object to test.
Object B: second object to test.

Warning

Test Bounding Box Y Overlapping is OBSOLETE and remains only for compatability.


Translate BB

 Translate
Categorized in 3D Transformations/Basic

Description

Apply to a 3DENTITY.
Translates a 3D Entity.
Rotate-Translate.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Translate Vector: 3D Vector.
Referential: coordinate system in which the Translate Vector is expressed.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.


Update Nodal Path BB

 Update Nodal Path
Categorized in 3D Transformations/Nodal Path

Description

Apply to a BEOBJECT.
Reevaluates the nodes distance of the given nodal path.
Update Nodal Path.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Nodal Path: the nodal path.

This building block must be used if you move in real time the nodes of a nodal path, to reevaluate the distance between nodes. If you don't, you'll not be sure to always get the shortest path using the "GoToNode" building block.


Cameras

Basic

Dolly: Keeps the projection plane at the same position while translating the camera on its Z local axis.

Orthographic Zoom: Emulates a zoom when the viewing mode is orthographic.

Set Camera Target: Makes a 3D Entity be the target of a camera.

Set Clipping Planes: Sets the near and the far clipping plane of a camera.

Set FOV: Sets the Field Of View of the camera

Set Projection: Sets the Projection Type of the Camera.

Set Zoom: Sets the Zoom (or Lens) of a perspective camera (millimeter).

FX

Camera Color Filter: Adds a color filter to the Camera.

Vertigo: Creates a 'Vertigo' effect on the Camera.

Montage

Get Current Camera: States the current camera in the active scene.

Set As Active Camera: Tells the camera to be the active one.

Movement

Camera Orbit: Makes a Camera orbit round a 3D Entity.

Generic Camera Orbit: Makes a Camera orbit round a 3D Entity using input activation.

Joystick Camera Orbit: Makes a Camera orbit round a 3D Entity using Joystick.

Keyboard Camera Orbit: Makes a Camera orbit round a 3D Entity using keyboard with limited angles.

Mouse Camera Orbit: Makes a Camera orbit round a 3D Entity using Mouse.


Camera Color Filter BB

 Camera Color Filter
Categorized in Cameras/FX

Description

Apply to a CAMERA.
Adds a color filter to the Camera.
Camera Color Filter.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated when the building block has been activated by "On".
Exit Off: is activated when the building block has been activated by "Off".

Filter Color: color of the filter in RGBA.
Density: how dense the filter should be, in percent.
Hard Light: if FALSE, the filter color is added to the colors of the scene. If TRUE, the filter color is combined with the colors of the scene (resulting in greater opacity).

This building block is useful to simulate infrared glasses or fade in/fade out effects.
This building block does not need to be looped.


Camera Orbit BB

 Camera Orbit
Categorized in Cameras/Movement

Description

Apply to a 3D Entity.
Makes a Camera orbit round a 3D Entity.
Camera Orbit.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Target: 3D Entity to target.

Distance: current distance between the Camera and its target.

The following keys are used by default to move the Camera around its target:

Page Up: Zoom in.
Page Down: Zoom out.
Up and Down Arrows: Rotate around the view X axis.
Left and Right Arrows: Rotate around the view Y axis.
RIGHT SHIFT: Velocity x 2.
The arrow keys are the inverted T arrow keys and not the ones of the numeric keypad.

Key Zoom in: Key used to zoom in.
Key Zoom out: Key used to zoom in.
Key Rotate Up: Key used to rotate up.
Key Rotate Down: Key used to rotate down.
Key Rotate Left: Key used to rotate left.
Key Rotate Right: Key used to rotate right.
Key Speed x2: Key used to speed up motion by 2.


Dolly BB

 Dolly
Categorized in Cameras/Basic

Description

Apply to a TARGETCAMERA.
Keeps the projection plane at the same position while translating the camera on its Z local axis.
Dolly.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Translation Value: translation value on the Camera Z local axis.
Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.

Keeps the projection plane at the same position while translating the camera on its Z local axis.


Get Current Camera BB

 Get Current Camera
Categorized in Cameras/Montage

Description

Apply to a BEOBJECT.
States the current camera in the active scene.
Get Current Camera.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Current Camera: the camera currently used in the main viewport.

See Also: 'Set As Active Camera'.


Generic Camera Orbit BB

 Generic Camera Orbit
Categorized in Cameras/Movement

Description

Apply to a 3D Entity.
Makes a Camera orbit round a 3D Entity with limited angles using input activations.
Generic Camera Orbit.cmo

Technical Information

On: starts the behavior.
Off: stops the behavior.
Move Left: moves the camera to the left.
Move Right: moves the camera to the right.
Move Up: moves the camera up.
Move Down: moves the camera down.
Zoom In: zoom on the target.
Zoom Out: unzoom on the target.

Exit On: is activated when the behavior has been started.
Exit Off: is activated when the behavior has been stop. If in Returns mode, is activated only once the camera is back in place.

Target Position: Position we are turning around.
Target Referential: Referential where the position is defined.
Move Speed: Speed in angle per second used when the user moves the camera.
Return Speed: Speed in angle per second used when the camera returns.
Min Horizontal: Minimal angle allowed on the horizontal rotation. Must have a negative value.
Max Horizontal:Maximal angle allowed on the horizontal rotation. Must have a positive value.
Min Vertical: Minimal angle allowed on the vertical rotation. Must have a negative value.
Max Vertical: Maximal angle allowed on the vertical rotation. Must have a positive value.
Zoom Speed: Speed of the zoom in distance per second.
Zoom Min: Minimum zoom value allowed. Must have a negative value.
Zoom Max: Maximum zoom value allowed. Must have a positive value.

Limits: Is the move limited by the angles given as input parameters.
Returns: Does the camera systematically returns to its original position.


Joystick Camera Orbit BB

 Joystick Camera Orbit
Categorized in Cameras/Movement

Description

Apply to a 3D Entity.
Makes a Camera orbit round a 3D Entity with limited angles using keyboard.
Joystick Camera Orbit.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated. If in Returns mode, is activated only once the camera is back in place.

Target Position: Position we are turning around.
Target Referential: Referential where the position is defined.
Move Speed: Speed in angle per second used when the user moves the camera.
Return Speed: Speed in angle per second used when the camera returns.
Min Horizontal: Minimal angle allowed on the horizontal rotation. Must have a negative value.
Max Horizontal:Maximal angle allowed on the horizontal rotation. Must have a positive value.
Min Vertical: Minimal angle allowed on the vertical rotation. Must have a negative value.
Max Vertical: Maximal angle allowed on the vertical rotation. Must have a positive value.
Zoom Speed: Speed of the zoom in distance per second.
Zoom Min: Minimum zoom value allowed. Must have a negative value.
Zoom Max: Maximum zoom value allowed. Must have a positive value.

The following button are used by default to move the Camera around its target:

Button 1: Zoom in.
Button 2: Zoom out.

Limits: Is the move limited by the angles given as input parameters.
Returns: Does the camera systematically returns to its original position.
Joystick Number: index of the joystick triggering the BB.
Zoom In Button: button used to zoom in.
Zoom Out Button: button used to zoom out.
Inverse Up / Down: inverse the influence of the joystick on the vertical axis.
Threshold: minimum value that the joystick must reach to actually move the camera.


Keyboard Camera Orbit BB

 Keyboard Camera Orbit
Categorized in Cameras/Movement

Description

Apply to a 3D Entity.
Makes a Camera orbit round a 3D Entity with limited angles using keyboard.
Keyboard Camera Orbit.cmo

Technical Information

On: Starts the behavior.
Off: Stops the behavior.

Exit On: is activated when the behavior has been started.
Exit Off: is activated when the behavior has been stop. If in Returns mode, is activated only once the camera is back in place.

Target Position: Position we are turning around.
Target Referential: Referential where the position is defined.
Move Speed: Speed in angle per second used when the user moves the camera.
Return Speed: Speed in angle per second used when the camera returns.
Min Horizontal: Minimal angle allowed on the horizontal rotation. Must have a negative value.
Max Horizontal:Maximal angle allowed on the horizontal rotation. Must have a positive value.
Min Vertical: Minimal angle allowed on the vertical rotation. Must have a negative value.
Max Vertical: Maximal angle allowed on the vertical rotation. Must have a positive value.
Zoom Speed: Speed of the zoom in distance per second.
Zoom Min: Minimum zoom value allowed. Must have a negative value.
Zoom Max: Maximum zoom value allowed. Must have a positive value.

The following keys are used by default to move the Camera around its target:

Page Up: Zoom in.
Page Down: Zoom out.
Up and Down Arrows: Rotate vertically.
Left and Right Arrows: Rotate horizontally.
The arrow keys are the inverted T arrow keys and not the ones of the numeric keypad.

Limits: Is the move limited by the angles given as input parameters.
Returns: Does the camera systematically returns to its original position.
Key Rotate Left: Key used to rotate left.
Key Rotate Right: Key used to rotate right.
Key Rotate Up: Key used to rotate up.
Key Rotate Down: Key used to rotate down.
Key Zoom in: Key used to zoom in.
Key Zoom out: Key used to zoom in.


Mouse Camera Orbit BB

 Mouse Camera Orbit
Categorized in Cameras/Movement

Description

Apply to a 3D Entity.
Makes a Camera orbit round a 3D Entity with limited angles using keyboard.
Mouse Camera Orbit.cmo

Technical Information

On: activates the process.
Off: deactivates the process.
Resume: restarts the BB without reinitializing the camera start position. Used in Returns mode.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated. If in Returns mode, is activated only once the camera is back in place.
Exit Resume: is activated if the BB has been resumed.

Target Position: Position we are turning around.
Target Referential: Referential where the position is defined.
Move Speed: Speed in angle per second used when the user moves the camera.
Return Speed: Speed in angle per second used when the camera returns.
Min Horizontal: Minimal angle allowed on the horizontal rotation. Must have a negative value.
Max Horizontal:Maximal angle allowed on the horizontal rotation. Must have a positive value.
Min Vertical: Minimal angle allowed on the vertical rotation. Must have a negative value.
Max Vertical: Maximal angle allowed on the vertical rotation. Must have a positive value.
Zoom Speed: Speed of the zoom in distance per second.
Zoom Min: Minimum zoom value allowed. Must have a negative value.
Zoom Max: Maximum zoom value allowed. Must have a positive value.

Limits: Is the move limited by the angles given as input parameters.
Returns: Does the camera systematically returns to its original position.

Comments

The zoom is triggered by the mouse wheel.


Orthographic Zoom BB

 Orthographic Zoom
Categorized in Cameras/Basic

Description

Apply to a CAMERA.
Emulates a zoom when the viewing mode is orthographic.
Orthographic Zoom.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Zoom: zoom value. The higher the value, the greater the zooming in. Typical values are between 0 and 3.

See Also: 'Set Projection'.


Set As Active Camera BB

 Set As Active Camera
Categorized in Cameras/Montage

Description

Apply to a CAMERA.
Changes the active Camera.
Set As Active Camera.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block enables you to switch dynamically between cameras.
See Also: 'Get Current Camera'.


Set Camera Target BB

 Set Camera Target
Categorized in Cameras/Basic

Description

Apply to a TARGET CAMERA.
Specifies a 3D Frame as Camera Target.
Set Camera Target.cmo

Technical Information

In: activates the process.
Out: is activated when the process is complete.

Target: 3D Frame to target.

Remarks

This BB sets the target for a Target Camera. As a Target Camera always follows its target, you do not need to loop this behavior.

Note that 3D Frame is the only type of 3D Entity that can act as a Camera Target. Although you may be able to choose a 3D Object or other 3D Entity as target in the Edit Parameters dialog box, you should only choose a 3D Frame with this BB. You can then set the 3D Frame as child or parent to another 3D Entity if so required.

Note that if you delete the Camera, the Target is deleted as well unless you specify otherwise in the Custom Dependencies (in the Dev interface or as a pIn when deleting at run-time).


Set Clipping Planes BB

 Set Clipping Planes
Categorized in Cameras/Basic

Description

Apply to a CAMERA.
Sets the near and the far clipping plane of a camera.
Set Clipping Planes.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Near Clip: the distance from the point of view of the Near clipping plane.
Far Clip: the distance from the point of view of the Far clipping plane.

Reducing the Far Clip will speed up rendering, as objects which are too far away and so non-visible will be removed from rendering process. A fog background can be added so that objects on the perimeter edge will not be clipped.
Reducing the Near Clip will avoid clipping objects that are too close from being clipped if the camera gets too close to an object resulting in the object clipping.
Increasing the Near Clip and reducing the Far Clip will help to correct Z-Buffer inaccuracy in 3d scenes modeled with objects that are too large.


Set FOV BB

 Set FOV
Categorized in Cameras/Basic

Description

Apply to a CAMERA.
Sets the Field Of View for a Camera
Set FOV.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Angle: field of view angle, expressed in degrees.

See Also: 'Set Zoom'.


Set Projection BB

 Set Projection
Categorized in Cameras/Basic

Description

Apply to a CAMERA.
Sets the Projection Type of the Camera.
Set Projection.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Projection Type: the type of projection you want to use - orthographic or perspective.

Note: The orthographic mode is useful to render simple object when depth is not important since the vertices transformation is much simpler.

See Also: 'Orthographic Zoom'.


Set Zoom BB

 Set Zoom
Categorized in Cameras/Basic

Description

Apply to a CAMERA.
Sets the Zoom (or Lens) of a perspective camera (millimeter).
Set Zoom.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Focal Length: lens size expressed in millimeters.
See Also: 'Set FOV'.


Vertigo BB

 Vertigo
Categorized in Cameras/FX

Description

Apply to a CAMERA.
Creates a 'Vertigo' effect on the Camera.
Vertigo.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out:is activated when the process needs to loop.

Focal Point: 3D Entity that determines the constant focal plane for the camera during the effect.
Number of Frames: number of frames in which the effect will be performed.
Forward: 'True' moves the camera forward, 'False' moves it backward.
Distortion Amount: amount of distorsion expressed in percentage.
Progression Curve: progression curve along the camera Z axis.

This behavior creates a 'Vertigo' effect by moving the camera forward (or backward) along its Z axis while adjusting the field of view so that the objects in its focal plan remain the same size on the screen (while the others are deformed). Typically, this is used to produce dizziness or to increase tension before a scary event...

Note that this BB is Frame Rate based.


Characters

Animation

Add Animation: Add an animation to a character.

Animation Synchronizer: Provides a way to send messages at a specific moment during a character animation.

Create Blended Animation 2: Creates a new animation by merging two exsiting animations.

Exclude From Animation: Excludes the selected 3D Entity from all taking part in any animation that uses it.

Set Animation Frame: Places the character in a specified frame of an animation cycle.

Set Animation Step: Places the character in a specified frame of an animation cycle.

Set Blended Animation Factor: Sets the coefficient of interpolation of a blended animation

Set Bodypart Animation Frame: Places a character's body part in a specified frame of an animation cycle.

Share Character Animation Keys: Share animations keys of with all characters in a group.

Basic

Get Nearest Object: Finds out which object in a group is closest to a character.

Set Floor Reference Object: Sets the bodypart used to represent floor reference for the Character

Constraint

Character Keep On Floor: Forces a character to stay on previously defined floors.

Enhanced Character Keep On Floor: Forces a character to stay on a declared floor (so it will not hover above it).

IK

IK Position: Sets a body part's position using Inverse Kinematics.

Movement

Character Controller: Simple control of a character with 4 animations by joystick or keyboard.

Character Curve Follow: Makes a character follow a 3D Curved.

Character Go To: Make the character walk to a given object.

Enhanced Character Curve Follow: Makes a charcter follow all or a specified part of a curve performing a specified animation.

Unlimited Controller: Controls a character by using animations played in response to messages.


Add Animation BB

 Add Animation
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
Adds an animation to a character.
Add Animation.cmo

Technical Information

In : triggers the process.
Out : is activated when the process is completed.

Animation : animation to add to the character.

Adding an animation to a character removes it from its previous owner. If you want the previous owner to keep its animation, before to add it, copy it using the "Object Copy" BB with the "Character\Share Animations" flag checked to gain some memory.


Animation Synchronizer BB

 Animation Synchronizer
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
Provides a way to send messages at a specific moment during a character animation.
Animation Synchronizer.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

In the custom dialog box, the first thing to specify is the type of animation in the top left section, clicking "-Add-" to validate this choice. "Message..." will appear in the left hand column of the bottom half of the screen. Double clicking on this will reveal a drop down menu allowing selection of the appropriate message (OnClick, OnCursorOn etc). The frame when this message should be sent is selected by using the frame slider. To validate the choice of frame when the message should be sent, it is necessary to clickce on the row to the right of the message. A point will appear on the line corresponding to the desired frame. To deselect the choice of frame, it is just necessary to clickce more on the point.


Character Controller BB

 Character Controller
Categorized in Characters/Movement

Description

Apply to a CHARACTER.
Simple control of a character with 4 animations by joystick or keyboard.
Character Controller.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Stand Animation: default animation, played when no other animation is in play.
Walk Animation: walk animation played when 'Joy_Up' message is received.
Walk Backward Animation: backwards walk animation played when 'Joy_Down' message is received.
Run Animation: running animation played when 'Joy_Button1' message is received.

This building block controls a character by using animations provided in response to messages from a joystick or keyboard.

See Also: "Enhanced Character Controller".

Warning

- This building block is intended to be used in conjunction with the "Keyboard Controller" BB or "Joystick Controller" BB, as they send appropriate messages that makes the "Character Controller" BB react (but in fact any correct message sending will make the "Character Controller" BB react).

- You cannot set the priority for animations using this BB. To control the priority for animations, see the "Unlimited Controller" BB.


Character Curve Follow BB

 Character Curve Follow
Categorized in Characters/Movement

Description

Apply to a CHARACTER.
Makes a character follow a 3D Curved.
Character Curve Follow.cmo

Technical Information

In: triggers the process.
Loop In: triggers the next step in a process loop.

Out: is activated when the process is completed.
Loop Out: is activated when the process is not yet completed.

Curve To Follow: name of the curve the character will follow.
Start Percentage: where the character should start on the curve, with 0 (zero) being the beginning, 50% being midway etc.
Character Direction: defines the character's frontal direction.

Current Percentage: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolates at the same time (in the same loop) a color value, a vector, a orientation or something like this.

This behavior sends the message "Joy_Up" to the character so that it will move along the path.

See Also: "Character Path Follow 2", "Character Go To" or if you work with grids see "Character Grid Path Follow".

Warning

- The required animation, walk for example, must be linked to the message "Joy_Up" using another building block such as Character Controller or Unlimited Controller for this behavior to work.
- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.


Character Go To BB

 Character Go To
Categorized in Characters/Movement

Description

Apply to a CHARACTER.
Make the character walk to a given object.
Character Go To.cmo

Technical Information

In: triggers the process.
Loop In: triggers the next step in a process loop.

Arrived: is activated when the distance between the character and the Target Object is the same as the Distance input parameter.
No Object: is activated if the Target Object does not exist.
Loop Out: is activated when the process needs to loop.

Target Object: destination object.
Distance: distance just before destination object where the character should stop.
Character Direction: character's frontal direction.
Limit Angle: angle limit between the character's direction and the destination object.
Reverse: Make the character walk backward to the given object.

See Also: "Character Path Follow 2", "Character Path Follow" or if you work with grids see "Character Grid Path Follow".


Character Keep On Floor Limits BB

 Character Keep On Floor Limits
Categorized in Characters/Constraint

Description

Apply to a CHARACTER.
OBSOLETE.

Forces a character to keep to a floor's limits, simulating a collision with a wall if the character tries to venture outside.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block makes a character stay on floors and simulates a collision with a wall if the character attempts to go outside the floor limits.
To have a floor reference object (for example feet), the character must have an object containing ("FloorRef","Foot","Pas") in its name, and be a child of the root of the character in order to be recognized.
If this object is not present the building block uses a character's bounding box to make contact.
Objects representing floors must be declared as floors first, either by using the behavior "DeclareFloors" or giving them the Floor attribute. This building block is also a easy way to prevent characters from going outside of a floor's bounding box limits.

This building block should be looped if the character is to keep to the floor limits all the time.
The character is kept on the floor's limits by comparing its position with the limits of the floor's bounding box. This building block is useful as it avoids the need for processing big calculations, but it is very approximative and will not work well for terrrains that are not square

Warning

This building block is obsolete and is only included for backwards compatibility.


Character Keep On Floor BB

 Character Keep On Floor
Categorized in Characters/Constraint

Description

Apply to a CHARACTER.
Forces a character to stay on previously defined floors.
Character Keep On Floor.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

To have a floor reference object (for example feet), the character must have an object containing ("FloorRef","Foot","Pas") in its name, and be a child of the root of the character in order to be recognized.
If this object is not present, the building block uses a character's bounding box to make contact. Objects representing floors must be declared as floors first, either by using the behavior DeclareFloors or giving them the Floor attribute.
See also: Enhanced Character Keep On Floor

Warning

- This building block should be looped if the character is to keep to on the floor all the time.


Create Blended Animation 2 BB

 Create Blended Animation 2
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
Creates a new animation by merging two existing animations.
Blended Animations.cmo

Technical Information

Animation 0: specifies the first animation to use.
Animation 1: specifies the second animation to use.

Blended Animation: animation created.

Dynamic: if selected the animation is dynamic, meaning that the animation is deleted when the composition is reset (e.g. Restore IC in Dev).
Add to character: if selected, the animation is automatically added to the Character.

Remarks

Note that Create Blended Animation 2 BB is targetable, and that the animation is created the first time the BB is activated (this is not the case with the original Create Blended Animation BB). Once the animation has been created, you can remove the BB or the script as they are no longer needed.

The animation can be controlled with the Set Blended Animation Factor BB that allows you to specify the influence of each of the two animations for the final result.

See Also: Set Blended Animation Factor BB and Create Blended Animation BB.


Create Blended Animation BB

 Create Blended Animation
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
OBSOLETE

Creates a new animation by merging two exsiting animations.

Technical Information

Animation 0: specifies the first animation to use.
Animation 1: specifies the second animation to use.

Blended Animation: animation created.

The new animation is created the first time the behavior is edited. Its settings will only change if the input parameters are edited. Once created the animation can be controlled with the behavior "Set Blended Animation Factor" which will specify the influence of each of the two animations for the final result.

See Also: "Set Blended Animation Factor".

Warning

- Once a blended animation is created, it is attached to the owner character. The created animation is stored as any other animation on the character.
- Once triggered one time the building block can be safely removed.


Enhanced Character Controller BB

 Enhanced Character Controller
Categorized in Characters/Movement

Description

Apply to a CHARACTER.
OBSOLETE - see Unlimited Controller BB.

Controls a character by using 7 animations reacting to a joystick or keyboard.

Technical Information

On: activates the behavior.
Off: deactivates the behavior.

Stand Animation: default animation when no other is in play.
Walk Animation: walk animation played when 'Joy_Up' message is received.
Walk Backward Animation: backwards walk animation played when 'Joy_Down' message is received.
Run Animation: run animation played when 'Joy_Button1' message is received.
Creep Animation: creep animation played when 'Joy_Button2' message is received.
Jump Animation: jump animation played when 'Joy_Button3' message is received.
Dance Animation: dance animation played when 'Joy_Button4' message is received.

This behavior controls a character by using animations provided in response to messages from a joystick or keyboard.

This building block is intended to be used in conjunction with the "Keyboard Controller" BB or "Joystick Controller" BB, as they send appropriate messages that makes the "Character Controller" BB react (but in fact any correct message sending will make the "Character Controller" BB react).

You cannot set the priority for animations using this BB. To control the priority for animations, see the "Unlimited Controller" BB.

Warning

This building block is obsolete and is only included for backwards compatibility.


Enhanced Character Curve Follow BB

 Enhanced Character Curve Follow
Categorized in Characters/Movement

Description

Apply to a CHARACTER.
Makes a charcter follow all or a specified part of a curve performing a specified animation.
Enhanced Character Curve Follow.cmo

Technical Information

In: triggers the process.
Loop In: triggers the next step in a behavior's process loop.

Out: is activated when the process is completed.
Loop Out: is activated when the behavior's process is not yet completed.

Curve To Follow: name of the curve the character will follow.
Start Percentage: where the character should start on the curve, with 0 (zero) being the beginning, 50% being midway etc.
End Percentage: point on the curve at which the character should stop, with 100% being the end.
Character Direction: defines the character's frontal direction.
Animation: name of animation the character should perform while following the curve.

Current Percentage: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolates at the same time (in the same loop) a color value, a vector, a orientation or something like this.

See Also: "Character Path Follow", "Character Go To" or if you work with grids see "Character Grid Path Follow".


Enhanced Character Keep On Floor BB

 Enhanced Character Keep On Floor
Categorized in Characters/Constraint

Description

Apply to a CHARACTER.
Forces a character to stay on a declared floor (so it will not hover above it).
Enhanced Character Keep On Floor.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.
Touched Floor Limits: is activated if the charcter touches the floors' limits.

Follow Inclination: TRUE means the character will follow any curvatures in the floor. This parameter works together with "Orientation Attenuation" parameter, which sets how smooth a character's change in orientation would be.
Replacement Altitude: distance of the charcter from the floor, 0 (zero) means touching.
Keep In Floor Boundary: if TRUE, the character will not be able to venture outside the floor's boundaries.
Detection Offset: distance from the bottom of the object after which a character will take a floor above, rather than a floor below. It is also the maximum height, in the world's Y axis, that a character can climb. NB See Warning below.
Character Extents: extent of the character to take into account (showed by a little white rectangle).
Orientation Attenuation: attenuates the effect of Follow Inclination, with 100% being very rough, and 1% being very smooth.
Weight: the weight of the character, so as to simulate the effect of gravity.
Character Direction: defines the character's frontal direction.

Floor: object that has been chosen as the nearest floor.
Floor Type: type of the floor chosen, for example grass, ice, tarmac etc. The type of floor is represented by a whole number defined by the user in the attributes setup.
Floor Normal: normal of the floor in relation to the character's position.
Old Floor Distance: character's distance from the floor before being forced to stay on it.
Down Velocity: It is the character's velocity when he fall, attracted by a floor.

Show Extents: if checked, the character's extent, shown by a white rectangle will be seen.

To have a floor reference object (for example feet), the character must have an object containing ("FloorRef","Foot","Pas") in its name, and be a child of the root of the character in order to be recognized.
If this object is not present the building block uses a character's bounding box to make contact.
Objects representing floors must be declared as floors first, either by using the building block DeclareFloors or giving them the Floor attribute.

Warning

- If you want to use the pIn Detection Offset of this BB and you are using the BB Unlimited Controller, you must ensure that the pIn Keep Character on Floors for Unlimited Controller is not selected.

See also: Character Keep On Floor


Exclude From Animation BB

 Exclude From Animation
Categorized in Characters/Animation

Description

Apply to a 3DENTITY.
Excludes the selected 3D Entity from all taking part in any animation that uses it.
Exclude From Animation.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Exclude: if TRUE the 3D Entity will be excluded, if FALSE it will be re-included.
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

An example of this building block would be excluding all the body-parts of an arm during a character's walking animation. The character would still walk, only the arm subject to this behavior would not move (it would not swing as arms normally do during walking movements) at all and would simply dangle lifelessly.

Warning

This Behavior neither hides nor removes the object from the scene, it simply prevents it from taking part in animations.


Get Nearest Object BB

 Get Nearest Object
Categorized in Characters/Basic

Description

Apply to a CHARACTER.
Finds out which object in a group is closest to a character.
Get Nearest Object.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Group of Objects: name of group of objects to test.

Nearest Object: object in the group which is in fact nearest to the character.


IK Position BB

 IK Position
Categorized in Characters/IK

Description

Apply to a CHARACTER.
Sets a body part's position using Inverse Kinematics.
IK Position.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Starting Body Part: root of the IK. For an arm IK animation for example, the Starting Body Part would be the shoulder.
Ending Body Part: for an arm IK animation for example, the Ending Body Part would be the hand.
Entity To Follow: 3D Entity to which the Ending Body Part will sets its position.
Latency: indicates the number of frames taken by the body part to go to the entity's position.

This building block sets the position of the ending bodypart to the entity to follow.

Warning

- This building block should only be used with non-animated bodyparts.
- If an animated character moves its arm with IK, all of an arm's body parts should have the building block "Exclude from Animation".


Set Animation Frame BB

 Set Animation Frame
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
Places the character in a specified frame of an animation cycle.
Set Animation Frame.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Frame: frame of the animation cycle to be selected.
Animation: specify which animation should be used.

If Frame is a float value, for example 3.5, the result will be an interpolation between the existing frames of the animation (i.e. frames 3 and 4).
This behavior can be used for more accurate control of an character's animation.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.
- this BB simply animates the character without doing any translation or rotation on its referential. Therefore, by using this BB, you move the character within its own referential. To avoid this, simply use the automatic animation BB as the "Unlimited Controller".


Set Animation Step BB

 Set Animation Step
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
Places the character in a specified frame of an animation cycle.
Set Animation Step.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Step: advancement in percentage of the animation (between 0 and 100).
Animation: specify which animation should be used.

You should use this behavior to have an accurate control on the character's animation.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.
- this BB simply animates the character without doing any translation or rotation on its referential. Therefore, by using this BB, you move the character within its own referential. To avoid this, simply use the automatic animation BB as the "Unlimited Controller".


Set Blended Animation Factor BB

 Set Blended Animation Factor
Categorized in Characters/Animation

Description

Apply to a BEOBJECT.
Sets the coefficient of interpolation of a blended animation
Blended Animations.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Animation: specify the blended animation to change.
Factor: interpolation factor.

A blended animation is an interpolation of two animations. The factor passed as input parameter specifies the influence each animation.
A factor of 0 sets this animation to be equal to the first animation.
A factor of 50 sets this animations to be a fair blending of the two animations.

See Also: "Create Blended Animation".

Warning

- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.
(for the 'Progression' output parameter)


Set Bodypart Animation Frame BB

 Set Bodypart Animation Frame
Categorized in Characters/Animation

Description

Apply to a BODYPART.
Places a character's body part in a specified frame of an animation cycle.
Set Bodypart Animation Frame.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Frame: frame of the animation cycle to be selected.
Animation: specifies which animation should be used.

If Frame is a float value, for example 3.5, the result will be an interpolation between the existing frames of the animation (i.e. frames 3 and 4).
This behavior can be used for more accurate control of an animation performed by a character's body part. When setting the frame position for a body part animation, other animations may modify the body part's position or orientation. To disable a possible conflict from other animations, the ExludeFromAnimation behavior should be used before this one. The ExludeFromAnimation behavior will not prevent this building block (Set Bodypart Animation Frame) from setting a current animation frame.

Warning

- as there are no 'Hierarchy' input parameter, all the object's children will stay parented during the motion. Therefore you can't ask a object to move without moving its children.


Set Floor Reference Object BB

 Set Floor Reference Object
Categorized in Characters/Basic

Description

Apply to a CHARACTER.
Sets the bodypart used to represent floor reference for the Character
Set Floor Reference Object.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Floor Reference: entity used to represent floor reference.

The floor reference is an object which represents where the floor should be according to character position. This floor reference must be a child of the RootBodyPart. Typically for a walk animation the floor reference object position is the same as the feet. On the other hand, a jump animation will have a fixed floor reference while the RootBodyPart will have an up-down movement.


Share Character Animation Keys BB

 Share Character Animation Keys
Categorized in Characters/Animation

Description

Apply to a CHARACTER.
Share animations keys of with all characters in a group.
Share Character Animation Keys.cmo

Technical Information

Characters Group: a group of characters that will share their animations from the character animations.

Number Of Shared Animations: retrieve the number of animation that could be shared with this method.

For each animations of each characters in the group of characters, if an animation is the same than an animation of the character targeted by this building block then its data is replaced by a reference to the data of the source character animation.
Use this building block to save some memory and file size. As animations take a lot of memory and file size, you may want to share the data key informations... that's what this building block does.
To know if two animations are the same, this building block compare each animation keys... the comparison is not based on the name.


Unlimited Controller BB

 Unlimited Controller
Version 2.00 - Virtools
Categorized in Characters/Movement

Description

Apply to a CHARACTER.
Controls a character by using animations played in response to messages.
Unlimited Controller.cmo

Technical Information

The only way to parametrize this building block, is by editing it once it has been applied to the character.
You can also right click any parameter in the dialog box to create an input parameter so it can parametrized at runtime.
The 'Unlimited Controller' allows you to define animations for the whole character (Primary Animations) and specific body-part animations or exceptional animations (Secondary Animations)
For each couple (message,animation) parameters can be set to specify how animations should be played (use of motion warping for transitions,length of the warp sequence, time base for animation [frame or real time] and a priority to specify the order in which messages will be tested)

Primary Animations ...
- Order: the higher the order are, the lower its priority will be. You should therefore, put the animations like standing with a high order, while shot animations, or jump animations should have a lowest order (because when these animations are played, they must stops the others.
- Message: the waited message which start playing the associated animation.
- Animation: the character animation played when the character received the associated message.
- Warp [None/Start/Best]: specifies whether you want to have a transition animation with the next one "None" breaks the current animation and start the new one instantly, "Start" creates a transition to the start of the next animation and "Best" find the best frame to which begin the next animation (i.e next animation will not automatically be played from start).
- Warp length: duration of the warping animation part (transition part) according to the 'TimeBase' and the 'Fps'.
Say 'Warp length'=5 and 'Fps'=30.0
If 'TimeBase'=Frame, then the warping animation will take 5 frames (5 rendering process), and the 'Fps' value will not change anything.
If 'TimeBase'=Time, then the warping animation will take 5/30 seconds (independent of the frame rate).
- Stopable [Yes/No]: specifies if the animation can be stoped instantly (on request), or if the character will have to complete this animation to start an other (eg: typically a jump animation shouldn't be stopable).
- Time Base [Time/Frame]: specifies whether the base of time used to interpret duration will be proportionnal to 'Frames' or not (if not it use second [Time]). See 'Warp length'.
- Fps: number of animation frames to be played per seconds. This value will not be taken into concideration if the 'TimeBase'=Frame, because therefore, one animation frame will played for each rendering process.
- Turn [Yes/No]: specifies whether the character can be rotated (whith the 'Joy_Left' and 'Joy_Right' messages) while playing the raw-referenced animation, or not (eg: typically a jump animation shouldn't be orientable interactively).
- Orient [Yes/No]: specifies whether the animation should define a new character's orientation, or not (typically, set this values to 'Yes' if you whant the character has a Rotate Left animation, and if you want him to keep this orientation later on).
- Description: description field to define the animation.

Secondary Animations ...
- Message: the waited message which starts or stops playing the associated body-part animation.
- Action [Play/Stop]: specifies whether the message will start or stop the animation.
- Animation: the body-part animation that has to be started or stoped when the character received the associated message.
- Time Base [Time/Frame]: ref. just above.
- Fps: ref. just above.
- Loop [Yes/No]: specifies whether this animation has to be looped or not (to stop a looping animation, you'll need to send the appropriate stoping message).
- Start Frame: starting animation frame.
- Description: description field to define the animation.

Ending Parameters...
- Keep Character On Floor: if checked, the character will stand on floor, otherwise it will be in the air.
- Rotation Angle: proportionnal value to determine the speed of the character rotation (when receiving the 'Joy_Left' and 'Joy_Right' messages).

Detection Offset: offset at which the floor is detected. Allows character to climb a bridge when there is still a floor underneath.

Warning

- If you want to use the pIn Keep Character on Floors for this BB, you cannot use the pIn Detection Offset of Enhanced Character Keep On Floor.


Collisions

3D Entity

Collision Detection: Detects the collision between the 3D object and other 3D object declared as obstacles.

Multi Collision Detection: Detects the collision between any 3D objects declared as obstacles.

Object Slider: Object Ball Slider ; Impede the 3d object from penetrating a 3dobject in the specified group.

Prevent Collision: Prevents the 3DEntity from colliding obstacles.

Sphere Slider: Impede the 3D object from penetrating a 3dobject considered as a sphere of a specified radius in the specified group.

Floors

Declare Floors: Identifies floor objects by their name

Floor Manager Setup: Configure the Floor Manager.

Floor Slider: Constrain an object to the floor boundaries, with a given radius.

Get Nearest Floors: Retrieves the nearest 'floors' from given position

Influence

Home on Entity: Leads a 3D Entity towards its target, avoiding obstacles.

Intersection

Box Box Intersection: Detects the collision between two 3D entities at the box level.

Box Face Intersection: Detects the collision between the first entity's bounding box and each faces of the second entity.

Face Face Intersection: Detects the collision between two 3D entities at the face level.

Frustum Object Intersection: Detects the collision between a camera frustum and an object.

Sphere Sphere Intersection: Detects the collision between two 3D entities at the bounding sphere level.

Obstacle

Declare Obstacles: Identifies obstacle objects by their name


Add Obstacle BB

 Add Obstacle
Categorized in Collisions/Obstacle

Description

Apply to a 3DENTITY.
OBSOLETE

Adds the 3D Entity to the list of the Collision Manager.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Use this building block on 3d Objects that must be tested during collision detection. This building block is kept for compatibility but the approved method for declaring obstacle is now either to add them manually an obstacle attribute(see Attribute Setup), or to use the "Set Attribute" behavior to set them dynamically.

Warning

This building block is obsolete and is only included for backwards compatibility.


Avoid Obstacles BB

 Avoid Obstacles
Version 2.00 - Virtools
Categorized in Collisions/Influence

Description

Apply to a 3DENTITY.
OBSOLETE.

Modifies the 'Direction' input parameter to avoid obstacles.

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Loop Out: activates when the process needs to loop.

Direction: initial direction.
Referential: referential in which the direction is expressed.
Inertia: affects the variation of direction. Ranged from 0 to 1, a high inertia decreases the direction changes.
Influence Factor: determines the radius of the influence sphere of an obstacle: Radius = Influence Factor * Radius of Obstacle Bounding Sphere.
Keep On Floor: if this boolean is set to TRUE, the object will stay on the floor

New Direction: the direction modified by the proximity of obstacles.

- Each 3D entity to be considered as obstacle should be added to the collision manager's list using 'Add Obstacle'.
- This building block doesn't prevent object to intersect from each other. It acts in best to avoid collisions with influence spheres.

Warning

This building block is obsolete and is only included for backwards compatibility.


Box Box Intersection BB

 Box Box Intersection
Categorized in Collisions/Intersection

Description

Apply to a BEOBJECT.
Detects the collision between two 3D entities at the box level.
Box Box Intersection.cmo

Technical Information

In: triggers the process.

True: is activated if the 2 entities are in intersection.
False: is activated if the 2 entities are not in intersection.

Entity 0: first entity to be tested.
Entity 1: second entity to be tested.
Hierarchy 0: specify whether to concider the bounding box of the first entity and its children, or just the bounding box of the first entity.
Hierarchy 1: specify whether to concider the bounding box of the second entity and its children, or just the bounding box of the second entity.

This building block detects the collision between two entity's bounding boxes.

Warning

- This building block tells at a given time if the object 1 is touching or not the object 2.
If you need to execute this test every 5 rendering process, you should then loop this building block with a 5 frame link.
If you need to execute this test at each rendering process, you should then loop this building block with a 1 frame link.


Box Face Intersection BB

 Box Face Intersection
Categorized in Collisions/Intersection

Description

Apply to a BEOBJECT.
Detects the collision between the first entity's bounding box and each faces of the second entity.
Box Face Intersection.cmo

Technical Information

In: triggers the process.

True: is activated if the 2 entities are in intersection.
False: is activated if the 2 entities are not in intersection.

Entity 1: first entity to be tested.
Entity 2: second entity to be tested.

This building block detects the collision between the first entity's bounding box and each faces of the second entity.

Warning

- This building block tells at a given time if the object 1 is touching or not the object 2.
If you need to execute this test every 5 rendering process, you should then loop this building block with a 5 frame link.
If you need to execute this test at each rendering process, you should then loop this building block with a 1 frame link.


Character Prevent From Collision BB

 Character Prevent From Collision
Categorized in Collisions/Character

Description

Apply to a CHARACTER.
OBSOLETE - see Object Slider BB.

Prevents the character from colliding obstacles.

Technical Information

On: activates the process.
Off: deactivates the process.

Collision Occured: is activated when a collision occurs.
No Collision: is activated while no collision occurs.

Geometry Precision: you can force a geometry precision for all the obstacles or use the attributes specified precision with the 'Automatic' value.
Detection Tests: the maximum number of tests to be performed in addition to the initial one, to determine if a collision occured. The building block stops testing at the first collision it encounters, then tests for a safe position from that point.
Safe Position Tests: the maximum number of tests to be performed in addition to the initial one, to determine the nearest safe position from the collision point.

BodyPart Touched: the collided sub object (body part) of the character.
Touched Obstacle: 3D Entity touched by the body part (retrieves the parent of the obstacle if you specified the collision to be hierachical).
Touched Sub Obstacle: 3D Entity touched by the body part (retrieves the exact object on a hierachical collision).

- Unlike the "DetectCollision" building block, "Character Prevent From Collision" doesn't need to be looped if you want the collision to be tested every frame.
- The attached character will be given the "Moving Obstacle" attribute by this building block, but for each object you wish to avoid, the objects need to be assigned the "Fixed Obstacle" or "Moving Obstacle" attribute.

Warning

This building block is obsolete and is only included for backwards compatibility.


Collision Detection BB

 Collision Detection
Categorized in Collisions/3D Entity

Description

Apply to a 3DENTITY.
Detects the collision between the 3D object and other 3d object declared as obstacles.
Collision Detection.cmo

Technical Information

In: triggers the process.

True: is activated if an obstacle touched the object.
False: is activated if no obstacle touched the object.

Geometry Precision: you can force here a geometry precision for all the obstacles or use the attributes' specified precision with the 'Automatic' value.
Detection Tests: the maximum number of tests to be performed in addition to the initial one, to determine if a collision occured. The building block stops testing at the first collision it encounters, then tests for a safe position from that point.
Safe Position Tests: the maximum number of tests to be performed in addition to the initial one, to determine the nearest safe position from the collision point.

Object Part: if the object which building block is applied to, is composed of many others, 'Object Part' retrieves the collided sub object. If there's no sub object, 'Object Part' retrieves simply this object.
Touched Obstacle: 3D Entity touched by the object (retrieves the parent of the obstacle if you specified the collision to be hierarchical).
Touched Sub Obstacle: 3D Entity touched by the object (retrieves the exact object on a hierarchical collision).
Touched Vertex: nearest Vertex of the obstacle when the collision occurs.
Touched Face: nearest Face of the obstacle when the collision occurs.
Touching Vertex: nearest Vertex of the tested object when the collision occurs.
Touching Face: nearest Face of the tested object when the collision occurs.
Impact Point: the approximate impact point (based on the two nearest vertices of the two objects).
Impact Normal: the approximate impact normal based on the two nearest vertices of the two objects, not on the face normal of the obstacle).
Impact Orientation: the world matrix of the tested object before the collision occurs (the matrix of the previous frame if it can't find anything better.)

Impact Data: With these flags, you can choose which information is relevant to you.

Warning

- This building block tells at a given time if the object is touching or not an obstacle.
If you need to execute this test every 5 behavioral process, you should then loop this building block with a 5 frame link delay.
If you need to execute this test at each rendering process, you should then loop this building block with a 1 frame link delay.
- Each obstacles to be assigned the "Fixed Obstacle" or "Moving Obstacle" attribute, knowing that only the objects that doesn't move from one frame to another can be safely assigned the "Fixed Obstacle" attribute.


Declare Floors BB

 Declare Floors
Version 2.00 - Virtools
Categorized in Collisions/Floors

Description

Apply to a BEOBJECT.
Identifies floor objects by their name
Declare Floors.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Key Substring: any object in the level which name containing this string becomes a floor.

This building block can be applied to any object in the enviroment.
eg: if 'Key Name'= Quad, then all the objects of the scene containing 'Quad' in their name, will be concidered as floors.
It must be triggered once to initialize floor management.
You can declare floors also by giving the "Floor" attribute to your floors.


Declare Obstacles BB

 Declare Obstacles
Categorized in Collisions/Obstacle

Description

Apply to a BEOBJECT.
Identifies obstacle objects by their name
Declare Obstacles.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Key Substring: any object in the level which name containes this string becomes an obstacle.
Moving: whether you want the objects to be defined as moving obstacles.
Geometry: the type of geometry you want to consider in collision testing.

This building block can be applied to any object in the environment. It should be triggered only once to initialize collision management.


Face Face Intersection BB

 Face Face Intersection
Categorized in Collisions/Intersection

Description

Apply to a BEOBJECT.
Detects the collision between two 3D entities at the face level.
Face Face Intersection.cmo

Technical Information

In: triggers the process.

True: is activated if the 2 entities are in intersection.
False: is activated if the 2 entities are not in intersection.

Entity 1: first entity to be tested.
Entity 2: second entity to be tested.

This building block detects the collision between each faces of the first entity and each faces of the second entity.

Warning

- This building block tells at a given time if the object 1 is touching or not the object 2.
If you need to execute this test every 5 rendering process, you should then loop this building block with a 5 frame link.
If you need to execute this test at each rendering process, you should then loop this building block with a 1 frame link.


Floor Manager Setup BB

 Floor Manager Setup
Categorized in Collisions/Floors

Description

Apply to a BEOBJECT.
Configure the Floor Manager.
Floor Manager Setup.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Angle Limit: angle between a face normal and the world Up direction beyond which the face is no more accepted. Typically angle less than 60 degrees are used. Bigger angles won't look realistic.
Cache Size: the current number of positions kept by the cache of the FloorManager. If you have two objects keeped on floors by behaviors, you should put 2 as cache size if they are kept by Object Keep On Floor or by Object Keep On Floor V2 with point as object extents setting or 8 as cache size if they are kept by Object Keep On Floor V2 with bounding box as object extents setting.
Cache Threshold: a floating point value representing the threshold in all the 2 axis, x and z. This value is relative to the coarseness of the floor and the velocity of the objects. Values ranging from 0.1 to 1.0 should do fine generally.


Floor Slider BB

 Floor Slider
Categorized in Collisions/Floors

Description

Apply to a 3DENTITY.
Constrains an object to the floor boundaries, with a given radius.
Floor Slider.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Contact: activate each time there's a contact.
No Contact: activate each time there's no contact.

Radius: radius to impede object penetration (expressed in world absolute value).

Warning

- you can change the "radius" at run-time.
- Radius is expressed in absolute world values.
- All floors must be scaled to 1x1x1 (use Set As Unit).
- If you want to teleport your object from one place to another, you should deactivate the building block (triggers OFF, or deactivate the script).


Frustum Object Intersection BB

 Frustum Object Intersection
Categorized in Collisions/Intersection

Description

Apply to a CAMERA.
Detects a collision between an object and the Camera frustum.
Frustum Object Intersection.cmo

Technical Information

In: actrivates the process.

True: activates if the object intersects or is inside the Camera frustum.
False: activates if the object does not intersect (ie : is outside) the Camera frustum.

Object: object to test.
Local: if selected, test the local bounding box of the object.
Hierarchy: if selected, the object's children are tested as well.

This comportement works like the IsInViewFrustum BB, but allow a test on another camera than the current one.


Get Nearest Floors BB

 Get Nearest Floors
Categorized in Collisions/Floors

Description

Apply to a 3DENTITY.
Retrieves the nearest 'floors' from given position
Get Nearest Floors.cmo

Technical Information

In: triggers the process.

None: is activated when no floors are found above or below the point.
Lower: is activated when the lower floor is the nearest (or the only) floor from the point.
Upper: is activated when the upper floor is the nearest (or the only) floor from the point.

Position: position vector expressed in a given referential.
Referential: coordinate system in which the position is expressed.

Outputs: all the properties of the down and up floors.

You need to declare objects as "floors" first, either by using the "DeclareFloors" building block or by setting the "Floor" attributes to them.


Home on Entity BB

 Home on Entity
Categorized in Collisions/Influence

Description

Apply to a 3DENTITY.
Leads a 3D Entity towards its target, avoiding obstacles.
Home on Entity.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Target Reach: is activated when the missile reaches the target.
Obstacle Reach: is activated when the missile touches an obstacle.
Loop Out: activates when the process needs to loop.

Destination: the object which is supposed to be destroyed.
Initial Velocity: magnitude of the Initial Velocity Vector. The initial direction of this vector corresponds to the local Z axis of the missile.
Inertia: this factor allows you to calibrate the inertia of the missile. If this factor is near zero, the missile will rotate very fastly to reach his target. On another hand, if it is near one, the missile will make large circles (because of its own velocity) around the target before reach it.
Obstacle Influence factor: the radius of the influence zone of each obstacle (the place where the obstacles repulse the missile) is equal to: Influence Factor * Radius of the Bounding sphere.

Object Hit: object hit by the missile.

Warning

- Each obstacle has to be add to the 'collision manager' with the 'Add Obstacle' building block. - This building block doesn't prevent object to intersect from each other. It best acts to avoid collisions with influence spheres.


Multi Collision Detection BB

 Multi Collision Detection
Categorized in Collisions/3D Entity

Description

Apply to a 3DENTITY.
Detects the collision between any 3D Entities declared as Obstacles.
Multi Collision Detection.cmo

Technical Information

On: triggers the process.
Off: Stops the process
Loop In: must be activated to retrieve the next collision.

Exit On: is activated when the process is trigerred.
Exit Off: is activated when the process is stopped.
Loop Out: is activated for each contact detected.
All Collisions parsed: is activated when all collisions in the same frame have been parsed using the Loop In/Loop Out parsing.

Geometry Precision: forces specific geometry precision for all the obstacles; or 'Automatic' to use the the precision specified by the Collision Attributes.

Index: index of the collisions found.
Object 1: first object of the contact pair.
Object 2: second object of the contact pair.
Object 1 Part: if the first object which building block is applied to, is composed of many others, 'Object Part' retrieves the collided sub object. If there's no sub object, 'Object Part' retrieves simply this object.
Object 2 Part: same definition for the second object.
Object 1 Face: nearest Face of the first object when the collision occurs.
Object 2 Face: same definition for the second object.
Object 1 Vertex: nearest Vertex of the first object when the collision occurs.
Object 2 Vertex: same definition for the second object.
Impact Point: the approximate impact point (based on the two nearest vertices of the two objects).
Impact Normal: the approximate impact normal based on the two nearest vertices of the two objects, not on the face normal of the obstacle).

Impact Data: allows you to select which information is calculated; a pOut is created for every check box you select.

Remarks

You must assign either the "Fixed Obstacle" or "Moving Obstacle" attribute to all Obstacle 3D Entities; ensure you use "Fixed Obstacle" for 3D Entities that do not move from one frame to another for general optimization. However at least one 3D Entity must be declared as a "Moving Obstacle" or this BB will not work.

Remember that every check box you select in Impact Data creates more work for the Behavioral Engine, so calculate only the information you need to optimize performance.

Warning

Remember at least one obstacle must be declared as a "Moving Obstacle" or this BB will not work!


Object Slider BB

 Object Slider
Categorized in Collisions/3D Entity

Description

Apply to a 3DENTITY.
Object Ball Slider; Impedes the 3D Object from penetrating a 3D Object in the specified group.
Object Slider.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Contact: activate each time there's a contact.
No Contact: activate each time there's no contact.

Radius: radius to impede object penetration (expressed in world absolute value).
Group: group in which other objects are to be considered (the object [ball] will not penetrate those objects).

Reaction Vector: 3d vector response (not normalized).

Accuracy: maximum accuracy for object collision.
Touched Objects Group: group filled with all the touched objects when a contact occurs.
Place Optimization: if TRUE, the process will be optimized for levels designed with Places. Instead of parsing all the objects of the group, and then performing a bounding box collision test for each of them, we parse instead all the places and perform a hierarchical bounding box collision test with those places. If the test is TRUE, then we parse the place hierarchy in a recursive way, and for each child of the place, we perform again a hierarchical bounding box collision test ... and so on.
This method is very efficient if your level is split into places, and if each place contains - on average - more than one collision object defined in the input group. Because that way, just a few objects from the group will be tested.

Warning

- the "Touched Objects Group" (in settings), is cleared and filled again at each contact events. It isn't clear if no collision occurred. Therefore you can use this group to retrieve all the touched object, even if the collision occurred 5 or 10 frames ago.
- you can change the "radius" and the "group" at run-time.
- you can use the 'Reaction' output parameter to get information about the normal of the collision (don't forget to normalize if you need a normalized vector), or to get the point of collision on the sphere [ contact_point = -Radius * Normalize( Reaction ) ]. - unlike the 'Layer Slider' building block, the radius isn't proportional to the object's bounding sphere. Radius is expressed in absolute world values.
- all object in group must be 3D Objects ( no Groups, no Places no Data Arrays ... etc, only 3d Objects or derivative types).
- all object in group must be 1x1x1 scaled (use Set as Unit).
- If you want to teleport your object from place to an other, you should deactivate the building block (triggers OFF, or deactivate the script ).
- Do not check "Place Optimization" setting if you have more places in your level than objects in the group (it would result in a slower process).


Prevent Collision BB

 Prevent Collision
Categorized in Collisions/3D Entity

Description

Apply to a 3DENTITY.
Prevents the 3DEntity from colliding obstacles.
Prevent Collision.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Collision Occured: is activated when a collision occurs.
No Collision: is activated while no collision occurs.

Geometry Precision: you can force a geometry precision for all the obstacles or use the attributes specified precision with the 'Automatic' value.
Detection Tests: the maximum number of tests to be performed in addition to the initial one, to determine if a collision occured. The building block stops testing at the first collision it encounters, then tests for a safe position from that point.
Safe Position Tests: the maximum number of tests to be performed in addition to the initial one, to determine the nearest safe position from the collision point.

Warning

- The attached 3d entity will be given the "Moving Obstacle" attribute by this building block, but for each object you wish to avoid, the objects need to be assigned the "Fixed Obstacle" or "Moving Obstacle" attribute.


Sphere Slider BB

 Sphere Slider
Categorized in Collisions/3D Entity

Description

Apply to a 3DENTITY.
Impedes the 3D Object from penetrating a 3D Object that is considered a sphere of a specified radius in the specified group.
Sphere Slider.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Collide: activate each time there's a contact.
Not Colliding: activate each time there's no contact.

Radius: radius to impede object penetration (expressed in world absolute value).
Entities: group in which other objects are to be considered (the object [ball] will not penetrate these objects).
Entities Radii: radius of the objects to be considered.

Warning

- you can change the "radius" and the "group" at run-time.
- unlike the 'Layer Slider' building block, the radius isn't proportional to the object's bounding sphere. Radius is expressed in absolute world values.
- all object in group must be 3D Objects (no Groups, no Places no Data Arrays ... etc, only 3d Objects or derived types ).
- If you want to teleport your object from place to an other, you should deactivate the building block (triggers OFF, or deactivate the script ).


Sphere Sphere Intersection BB

 Sphere Sphere Intersection
Categorized in Collisions/Intersection

Description

Apply to a BEOBJECT.
Detects the collision between two 3D entities at the bounding sphere level.
Sphere Sphere Intersection.cmo

Technical Information

In: triggers the process.

True: is activated if the 2 entities are in intersection.
False: is activated if the 2 entities are not in intersection.

Entity 0: first entity to be tested.
Entity 1: second entity to be tested.
Hierarchy 0: specify whether to concider the bounding sphere of the first entity and its children, or just the bounding sphere of the first entity.
Hierarchy 1: specify whether to concider the bounding sphere of the second entity and its children, or just the bounding sphere of the second entity.

This building block detects the collision between two entity's bounding spheres.


Test Bounding Box Y Overlapping BB

 Test Bounding Box Y Overlapping
Categorized in Collisions/3D Entity

Description

Apply to a 3DENTITY.
OBSOLETE.

Tests the Y Relative Position of the bounding boxes of two 3D Entities, in the world coordinate system.

Technical Information

In: triggers the process.

A above B : is activated if the bounding box of ObjectA is above that of ObjectB.
B above A : is activated if the bounding box of ObjectB is above that of ObjectA.
A above B overlapped : is activated if the bounding box of ObjectA is above that of ObjectB, but overlapping.
B above A overlapped : is activated if the bounding box of ObjectB is above that of ObjectA, but overlapping.
A and B overlapped: is activated if both bounding boxes are at the same level, overlapping.

Object A: first entity to be tested.
Object B: second entity to be tested.

Warning

This building block is obsolete and is only included for backwards compatibility.


Controllers

Joystick

Joystick Controller: Sends standard joystick messages to the building block owner.

Joystick Mapper: Binds specific messages to joystick commands.

Joystick Waiter: Activates different outputs according to Joystick commands.

Keyboard

Input String: Captures text entered by user.

Key Event: Activates one output when a specific key is pressed and a different output when the released.

Key Waiter: Waits for a key to be pressed.

Keyboard Controller: Emulates joystick messages using the keyboard.

Keyboard Mapper: Binds specific messages to keyboard keys.

Switch On Key: Activates the appropriate output when receiving a Key.

Midi

Midi Event: Gets a Midi event ON/OFF.

Read Midi: Reads a Midi signal.

Set Midi Input Port: Sets the Midi Input Port (usally 0).

Switch On Midi: Activates the appropriate output when receiving a Midi event.

Mouse

Get Mouse Displacement: Gets the mouse relative movement.

Get Mouse Position: Gets the position of the mouse.

Mouse Waiter: Activates different outputs according to mouse actions.


Get Mouse Displacement BB

 Get Mouse Displacement
Categorized in Controllers/Mouse

Description

Apply to a BEOBJECT.
Gets the mouse relative movement.
Get Mouse Displacement.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

X: number of pixels the mouse has moved along the X axis of the screen.
Y: number of pixels the mouse has moved along the Y axis of the screen.
Displacement Vector: number of pixels the mouse has been moved along the screen in a 2D Vector.

The movement returned is the number of pixel the mouse moved since the previous frame. Positive X movement is from left to right. Positive Y movement is from top to bottom.


Get Mouse Position BB

 Get Mouse Position
Categorized in Controllers/Mouse

Description

Apply to a BEOBJECT.
Gets the position of the mouse.
Get Mouse Position.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

X: position of the mouse cursor on the X axis of the screen.
Y: position of the mouse cursor on the Y axis of the screen.
Position: position of the mouse cursor as a 2D Vector.

Relative To Window: if checked, returns the position of the mouse relative to the 3d view window.


Input String BB

 Input String
Categorized in Controllers/Keyboard

Description

Apply to a BEOBJECT.
Captures text entered by user.
Input String.cmo

Technical Information

On: Activates the process. The ouput string is initialized with the reset string.
Off: deactivates the process.

On: Activates if the user press 'Enter' or when the input 'On' or when the 'End Key' is activated, it depends on the 'Multiline' setting..
Off: Activates when the input 'Off' is activated.
Updated String: Activates if the string or the caret have changed.

Reset String: String to be used when reset.
End Key: Key to be used to stop the edition when multiline is activated. When multiline is activated 'Return' is used to add a new line, else it is used to stop the edition. This parameter exists only if 'Multiline' is TRUE.

String: Current string.
Key: Current key.

Max Size: Maximum size of the entered string (number of characters).
Keyboard Repetition: Should keyboard repertition be activated ?.
Multiline: Should multiline be activated. If you set it to TRUE you should use 2D Text or 3D Text. Text Display isn't compatible with this option.
Disable Keyboard Section: Used to disable the processing of keyboard parts by this Building Block. You can disbale the arrows and / or the numpad.
Use Caret: Do you want to see the caret in your string. If you set it to TRUE you should use 2D Text or 3D Text. Text Display isn't compatible with this option.


Joystick Controller BB

 Joystick Controller
Categorized in Controllers/Joystick

Description

Apply to a BEOBJECT.
Sends standard joystick messages to the building block owner.
Joystick Controller.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Messages sent are Joy_Up / Joy_Down / Joy_Left / Joy_Right / Joy_ButtonN, N ranging from 1 to 6.
These messages are sent automatically on joystick commands.
This building block is meant to be used in association with 'Character Controller'. This combination allow you to use and test quite quickly a character with its animations.

See also: "Keyboard Controller", "Character Controller", "Joystick Mapper", "Joystick Waiter".


Joystick Mapper BB

 Joystick Mapper
Categorized in Controllers/Joystick

Description

Apply to a BEOBJECT.
Binds specific messages to joystick commands.
Joystick Mapper.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Analog Position: vector containing joystick's X-axis, Y-axis and Z-axis values respectively.

Axis Sensitivity: threshold in percentages of 3 axes after which the messages are triggered. 1 means sensitive response and 99 demands maximum effort to get a response.

This building block allows specific messages to be sent when receiving a joystick command. The object receiving the message can be of any type, therefore the color of a light could be controlled via joystick just as much as the position of a 3D Entity, for example.
Messages are bound to joystick commands in the custom dialog box by clicking on the desired command in the dialog box and then selecting (or creating) the message to be sent to the object, and then clicking on 'Add'. Selection can also be done by pressing the joystick buttons directly.

If the message 'DEAD' was meant to be sent to the character when pressing UP, the way to do it would be to apply the Joystick Mapper building block to the character (or to specify the character as the building block's Target, i.e. message receiver). Via the custom dialog box, UP would be pressed, 'DEAD' would be entered as the message to be sent, and 'Add' would be clicked. "JOY_UP bound with message DEAD" would then appear in the bottom half of the box indicating that this message had successfully been bound to the appropriate joystick command.

See also: Joystick Waiter.

Warning

- Bound messages can only be sent to the the target object of the building block 'Joystick Mapper'.


Joystick Waiter BB

 Joystick Waiter
Version 2.00 - Virtools
Categorized in Controllers/Joystick

Description

Apply to a BEOBJECT.
Activates different outputs according to Joystick commands.
Joystick Waiter.cmo

Technical Information

On: activates the behavior.
Off: disables the behavior.

Joystick Idle: is activated when the joystick is idle (no direction, no button pressed.)
xxx Moved: is activated when the joystick is moving in its xxx axis. See the settings for the possible axis list.
Button xxx Moved: is activated when the xxxth joystick button is pressed, with xxx ranging from 1 to 32.

Analog Position: vector containing joystick's X-axis, Y-axis and Z-axis values respectively.
Rotation: vector containing joystick's X-axis, Y-axis and Z-axis rotation values respectively.
Sliders: vector2D containing joystick's Slider1 (U Axis) and Slider2 (V Axis) values respectively.
Point Of View: angle containing joystick's point of view (a negative value means the POV is centered).

Axis Sensitivity: minimum move needed to activate an output, values between 0 and 1. Use X-axis for absolute moves, Y-axis for relative moves sensitivity. Z-axis is obsolete and remains for backward compatibility only.
Axis Outputs: The possible Axis are: Axis X, Axis Y, Axis Z, Rotation X, Rotation Y, Rotation Z, Slider 1, Slider 2, Point Of View (it can be moved or centered, activating two different outputs.)
Button Outputs: Choose the buttons among 32 you want to see states.
Relative Moves: Which axis' outputs should be activated by relative moves only.

Each output is activated according to the joystick's state while the building block remains active. Relative moves are usually used for the sliders and the point of view.

See also: Joystick Mapper.

Warning

The outputs that are activated depends greatly on the joystick. For example, an analog stick can activate the Z-rotation and the slider1 outputs - i.e. not necessarily the outputs you expect. In this case, you may be better off using the "Relative Moves" check boxes so that the joystick works in the way you expect.

It is impossible to gurarantee that two different joysticks will work in the same way, and so produce the same results.

As both points above are related to hardware, this is beyond Virtools control.


Key Event BB

 Key Event
Categorized in Controllers/Keyboard

Description

Apply to a BEOBJECT.
Activates one output when a specific key is pressed and a different output when the released.
Key Event.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Pressed: is activated when the key is pressed.
Released: is activated when the key is released.

Key: key to wait for. This is chosen in the parameter dialog box by first clicking "Select Key" and then pressing the key to wait for. The desired key will then appear to the right of "Select Key".

Key State: current state of the expected key, with TRUE = pressed and FALSE = released.

You can add many inputs parameters to detect combos.


Key Waiter BB

 Key Waiter
Categorized in Controllers/Keyboard

Description

Apply to a BEOBJECT.
Waits for a key to be pressed.
Key Waiter.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Key: key to wait for. This is chosen in the parameter dialog box by first clicking "Select Key" and then pressing the key to wait for. The desired key will then appear to the right of "Select Key".

Wait For Any Key: if TRUE, the building block will wait any key to be pressed. The input parameter is deleted, and a output parameter is created; and in this case the output parameter retrieves the pressed key.
Useful for "Press any key to continue..." capabilities.

Waits for a key to be pressed. If the setting parameter 'Wait Any Key' is set to FALSE, this building block will wait for a specific given key (default), if set to TRUE, then it will wait for anykey to be pressed, retrieving this key as an output parameter.

See Also: Switch On Key, Key Event.


Keyboard Controller BB

 Keyboard Controller
Categorized in Controllers/Keyboard

Description

Apply to a BEOBJECT.
Emulates joystick messages using the keyboard.
Keyboard Controller.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Maps keys to Joystick messages, as follows:
Num 8 -> Joy_Up
Num 2 -> Joy_Down
Num 4 -> Joy_Left
Num 6 -> Joy_Right
Insert -> Button 1
Home -> Button 2
Prior -> Button 3
Delete -> Button 4
End -> Button 5
Next -> Button 6

This building block emulates a joystick.

See also: "Joystick Controller", "Character Controller".


Keyboard Mapper BB

 Keyboard Mapper
Categorized in Controllers/Keyboard

Description

Apply to a BEOBJECT.
Binds specific messages to keyboard keys.
Keyboard Mapper.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

This building block allows specific messages to be sent when certain keys on the keyboard are pressed.
The object receiving the message can be of any type, therefore the color of a light could be controlled via the keyboard just as much as the position of a 3D Entity, for example. Messages are bound to keys in the custom dialog box by clicking on the desired key in the dialog box and then selecting (or creating) the message to be sent to the object, and then clicking on 'Add'.

If the message 'DEAD' was meant to be sent to the character when pressing the D key, the way to do it would be to apply the Keyboard Mapper building block to the character (or to specify the character as the building block's Target, i.e. message receiver). Via the custom dialog box, the D key would be pressed, 'DEAD' would be entered as the message to be sent, and 'Add' would be clicked. "D bound with message DEAD" would then appear in the bottom half of the box indicating that this message had successfully been bound to the appropriate keyboard key.

Warning

- Bound messages can only be sent to the the target object of the building block 'Keyboard Mapper'.


Midi Event BB

 Midi Event
Categorized in Controllers/Midi

Description

Apply to a BEOBJECT.
Gets a Midi event ON/OFF.
Midi Event.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Activated: is activated once a note gets ON.
If the "Ask For All Commands" setting is set to TRUE, then this bOut is activated each time MidiIn device gets a Midi command (not only the "Note ON" and "Note OFF" signal).
Deactivated: is activated when a note gets OFF.
If the "Ask For All Commands" setting is set to TRUE, then this bOut does not exist.

Channel: which channel is to be parsed by this building block (if you want to parse several channels at same time, you'll need to use several "Read Midi Signal" building block).
Note N: the note(s) which ON/OFF event rules the bOuts activations.

The Midi Event building block can work with one or several given notes.
If you use several notes, the "Activated" bOut is activated if and only if the combinasion of all this notes is successfull (ie: all notes activated).
The "Deactivated" bOut is activated when one of the notes is released.
If you use only one note, the "Activated" bOut is activated if and only if this note gets activated. The "Deactivated" bOut is activated when the notes is released.

Warning

- Unlike the "Read Midi Signal" building block this one expect a specific note (or a combinasion of specific notes).
- Unlike the "Switch On Midi" building block this one doesn't stay activated if the specific note is still pressed (it is just activated once when the note gets OFF ... it's an event).


Mouse Waiter BB

 Mouse Waiter
Categorized in Controllers/Mouse

Description

Apply to a BEOBJECT.
Activates different outputs according to mouse actions.
Mouse Waiter.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Move: activated if the mouse has been moved.
Left Button Down: activated if the left mouse button has been pressed.
Left Button Up: activated if the left mouse button has been released.
Right Button Down: activated if the right mouse button has been pressed.
Right Button Up: activated if the right mouse button has been released.
Middle Button Down: activated if the middle mouse button has been pressed.
Middle Button Up: activated if the middle mouse button has been released.
Roll: activated if the mouse wheel has been moved.

Mouse Position: position of the mouse cursor on the screen (NB: this position is NOT expressed in the render window but in the screen coordinates system).
Wheel Direction: direction of the mouse wheel, if applicable.
Left Button: TRUE if the left mouse button is down, FALSE otherwise.
Middle Button: TRUE if the middle mouse button is down, FALSE otherwise.
Right Button: TRUE if the right mouse button is down, FALSE otherwise.

Stay Active:
if FALSE, the 'On' and 'Off' input will be replaced by a 'In' input, and the building block will be deactivated after the first event.
Outputs: only checked outputs will be activated.


Read Midi BB

 Read Midi
Categorized in Controllers/Midi

Description

Apply to a BEOBJECT.
Reads a Midi signal.
Read Midi-Input Port.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Activated: is activated once a note gets ON. If the Ask For All Commands setting is set to TRUE, then this bOut is activated each time MidiIn device recieves a Midi command (not only the Note ON and Note OFF signals).
Deactivated: is activated when a note gets OFF (not present if the Ask For All Commands setting is not selected).

Channel: the channel to parse (if you want to parse several channels at same time, you'll need to use several Read Midi BBs).

Note: the received note (Byte #1).
Attack: the attack of this note (Byte #2) also called velocity.
Command: the received command (available only if you have selected the Ask For All Commands setting check box).

Ask For All Commands: to complete.

Warning

This building block is the only one you can use among the Midi event and state catchers if you want to get other commands than "Note ON" and "Note OFF".


Set Midi Input Port BB

 Set Midi Input Port
Categorized in Controllers/Midi

Description

Apply to a BEOBJECT.
Sets the Midi Input Port (usally 0).
Read Midi-Input Port.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Midi Input Port: the midi input port number.

This building block tells the Midi Manager which Midi Port (MidiIn Port) is to be used.
Default value is 0 (theorically your sound card). 1 is sometimes useful for a second Sound Card or if you want to test your interaction with a virtual keyboard (like "Virtual Piano" © in the "CakeWalk" © software).

Warning

- You shouldn't change the MidiIn Port at run-time.


Switch On Key BB

 Switch On Key
Categorized in Controllers/Keyboard

Description

Apply to a BEOBJECT.
Activates the appropriate output when receiving a Key.
Switch On Key.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Out 0: is activated when Key1 is pressed.
Out 1: is activated when Key2 in pressed.
...etc.

Key 0: first awaited Key.
Key 1: second awaited Key.
...etc.

You can add as many 'Output' as you want, the 'Input Parameters' will be added automatically.
This building block doesn't need to loop.

See also: WaitKey .


Switch On Midi BB

 Switch On Midi
Categorized in Controllers/Midi

Description

Apply to a BEOBJECT.
Activates the appropriate output when receiving a Midi event.
Switch On Midi.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Out N: is activated if the Nth note gets ON.

Channel: which channel is to be parsed by this building block (if you want to parse several channels at same time, you'll need to use several "Switch On Midi" building block).
Note N: the note(s) which ON event rules the bOuts activations.

Nop [None]: a useless pOut, used to keep the building block interface symmetry.
Attack N: the attack of the Nth note (Byte #2) also called velocity.

Warning

- The activated outputs remains activated after a "Note ON" signal occures for one of the given notes until the corresponding "Note OFF" signal occures.


Grids

Basic

3D Entity Fill: Fill a grid's layer using the bounding box of a 3D Entity

Fill Layer: Fills a specific layer type with some value.

Get Pos From Value: Gets the position of all the layer squares confirm test.

Get Square From 3D Pos: Gets the value of a square

Layer Slider: Impede the 3d object to enter into no-null squares of a specific layers.

Set Grid Priority: Sets the grid's priority

Set Square From 3D Pos: Sets the value of a square

Switch If Square: Switch streaming if the value on the specified layer on the specified position isn't NULL.

Path Finding

Character Grid Path Follow: Allow to a character to follow a path generated by the GridPathSolver

Grid Path Init: Initialize the grid graph for grid path finding

Grid Path Solver: Solve a new path finding problem.


3D Entity Fill BB

 3D Entity Fill
Categorized in Grids/Basic

Description

Apply to a BEOBJECT.
Fill a grid's layer using a 3D Entity
3D Entity Fill.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Object: to get shape from.
Solid Layer: layer to be filled with object inner surface.
Shape Layer: layer to be filled with object outlines.
Value: value to be written.

Only Bounding Box: Just use bounding box to fill solid layer.

The "3D Entity Fill" building block fill grids squares with an object shape & surface.


Character Grid Path Follow BB

 Character Grid Path Follow
Categorized in Grids/Path Finding

Description

Apply to a CHARACTER.
Makes a Character follow a path generated by the GridPathSolver BB.
Path Finding.cmo

Technical Information

On: activates or reactivates following the path.
Off: deactivates following the path.
Reset: aborts following the path.

Out: activates when Character has finished following the path.
Can't Follow Path: activates when Reset is activated or when target can't follow the path
Collision Happen: activates when the Character collides with a 3D Entity that has the Path Finding Obstacle Attribute.
Avoid Happen: activates when the Character avoids a 3D Entity that has the Path Finding Obstacle Attribute.
Enter Teleporter: activates when the Character enters a teleporter linker.
Travel Teleporter: activates when the Character disappears after entering a teleporter linker.
Exit Teleporter: activates when the Character exits a teleporter linker.

Path ID: Path ID
Character Direction: defines the character's frontal direction.
Change Direction Factor: allows the Character to "anticipate" changes of direction.
Limit Angle: stops the Character from walking while turning if the rotation angle is greater than Limit Angle.
Fuzzyness: adds noise to the path.
To And Fro: Character follows the path in both ways, indefinitely.
Max Blocked Time: maximum time a Character must stay blocked before aborting (Can't Follow Path activates at this moment).
Blocked Distance: minimum distance a Character must cover before a Character is considered as being "blocked".
Enter Teleporter Time: time the character must wait before taking the teleporter.
Travel Teleporter Time: teleporter travel time.
Exit Teleporter Time: time the Character remains before exiting a teleporter.

Collision Object: the 3D Entity the Character collided with.
Avoid Object: the 3D Entity the Character managed to avoid.

Manage Teleporter: adds teleporter pIns and pOuts.


Fill Layer BB

 Fill Layer
Categorized in Grids

Description

Apply to a BEOBJECT.
Fills a specific layer type with some value.
Fill Layer.cmo

Technical Information

In: triggers the behavior's process.
Out: is activated when the behavior's process is completed.

Layer: Layer to be concidered.
Value: Value to be put on each square.

Warning

- by now the only possible values are bound to a 0-255 range.


Get Pos From Value BB

 Get Pos From Value
Categorized in Grids

Description

Apply to a BEOBJECT.
Gets the position of all the layer squares confirm test.
Get Pos From Value.cmo

Technical Information

In: triggers the behavior's process.
Loop In: triggers the next step in a behavior's process loop.
Out: is activated when the behavior's process is completed.
Loop Out: is activated when the behavior's process needs to loop.

Layer: Layer to be concidered.
Value: Value to be put.
Test: Test to be done with the given value.

Pos3d: 3d position of the pointed square (nota bene: this position is expressed in a specific grid coordinate [see next output parameter]). The Y component of the given 3d vector stands for the 'height validity' [0-1].
Grid Ref: Grid basis in which the 3d position is expressed (it is also the grid from which the square were retrieved).

Remember, if you want to express an object position just set the referential as your object, and let 3dpos to (0,0,0)

Warning

- by now the only possible values are bound to a 0-255 range.
- the Test is taken into concideration only when entering by 'In'. (You can't change it will looping)


Get Square From 3dpos BB

 Get Square From 3D Pos
Categorized in Grids

Description

Apply to a BEOBJECT.
Gets the value of a square
Get Square From 3D Pos.cmo

Technical Information

In: triggers the behavior's process.
Out: is activated when the behavior's process is completed.

Pos3d: 3d position to be converted into a 2d position in the affected grid.
Ref: basis in which the 3d position is expressed.
Layer: Layer to be considered.

Value: Value to be retrieved.

Remember, if you want to express an object position just set the referential as your object, and let 3dpos to (0,0,0)

Warning

- by now the only possible values are bound to a 0-255 range.


Grid Path Init BB

 Grid Path Init
Categorized in Grids/Path Finding

Description

Apply to a BEOBJECT.
Initialize the grid graph for grid path finding
Path Finding.cmo

Technical Information

In: Activate the initialisation of the grid path graph.

Out: Is activate when graph is initialized.
Error: Is activate if graph can't be initialyzed..

Layer 1: Obstacle layer.
...etc.


Grid Path Solver BB

 Grid Path Solver
Categorized in Grids/Path Finding

Description

Apply to a BEOBJECT.
Solve a new path finding problem.
Path Finding.cmo

Technical Information

On: Activate the search.
Reset: Abord the search

Found: Is activate when the path is found.
Not Found: Is activate when the path is not found.

Position In Owner Ref: Position in owner referencial
Goal Position: Position in goal referencial
Goal Position Ref: Goal referential.
Heuristic Method: Method to calculate distance
Heuristic Factor: Determine importance of heuristic in calculs.
Diagonal: Enable diagonal moves.
Obstacle Layer: Layer which stand for obstacle.
Obstacle Threshold: If obstacle layer value is higher than obstacle threshold then it is an obstacle.
Slowing Factor: Increase or decrease the effect of the layer obstacle.
Use Linkers: Allow the target to use linkers
Teleporter As Obstacles: Do the target must consider teleporters as obstacles
Ms/Frame: Max time to spend for path calculation for one frame.

Path ID: Path representation
or
List of point: Path representation
or
Curve: Path representation
Path's Length: Path's Length

Path Type: Choose the representation of the path.
Optimize Path: Optimize number of points in the result path.


Layer Slider BB

 Layer Slider
Version 2.00 - Virtools
Categorized in Grids

Description

Apply to a 3DENTITY.
Impede the 3d object to enter into no-null squares of a specific layers.
Layer Slider.cmo

Technical Information

On: Activates the building block (it will be called every frames).
Off: Deactivate the building block.

Contact: activate each time there's a contact.
No Contact: activate each time there's no contact.

Influence Radius: amount of the object bounding sphere radius that will be taken into concideration to impede obstacles penetration.
( in most case 30% or 40% for a character would be fine )
A new functionnality concerning the camera has been added: the influence radius is taken into concideration for the cameras.
Layer To Slide On: layer type to slide on.

Reaction Vector: (Parameter added by settings) 3d vector response (beware, this vector isn't normalized).

Reaction Vector: boolean value to be check if you want the reaction vector to be output as a parameter.
Output Contact Count: defines the number of output parameters to be added, so you can get all the contact points between the object (modelized as a cylinder) and the non-nul squares of the specified layers.
Accuracy: maximum accuracy for object collision (higher values for bad FPS, or if the velocity is too high).

You can specify has many layer has you want.

Warning

- 'Layer Slider' doesn't take the Grid's Priority into consideration. All the grids are taken into consideration.
- 'Layer Slider' needs accurate environnement;
1 - the object proportional diameter must be inferior to the width and length of a grid square.
2 - the object should not move with a too great velocity (ie: greater than it's radius).
3 - if you have a bad frame rate and do not want your object to pass trough walls when frame rate is too low, you should increment the Accurate setting.

- for cameras, try to put a high influence radius: as the near clip plane is quite a small value, the resulting velocity with regard to the camera radius is often very high.


Set Grid Priority BB

 Set Grid Priority
Categorized in Grids

Description

Apply to a GRID.
Sets the grid's priority
Set Grid Priority.cmo

Technical Information

In: triggers the behavior's process.
Out: is activated when the behavior's process is completed.

Priority: The grid priority..

See Also: 'Activate Object' and 'Deactivate Object' (for grids activation or deactivation)


Set Square From 3dpos BB

 Set Square From 3D Pos
Categorized in Grids/Basic

Description

Apply to a BEOBJECT.
Sets the value of a square.
Set Square From 3D Pos.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Pos3D: 3d position to be converted into a 2d position in the affected grid.
Ref: basis in which the 3d position is expressed.
Layer: Layer to be conidered.
Value: Value to be retrieved.

Remember, if you want to express an object position just set the referential as your object, and let 3dpos to (0,0,0)

Warning

- by now the only possible values are bound to a 0-255 range.


Switch If Square BB

 Switch If Square
Categorized in Grids

Description

Apply to a BEOBJECT.
Switch streaming if the value on the specified layer on the specified position isn't NULL.
Switch If Square.cmo

Technical Information

In: triggers the behavior's process.

None: is activated when the behavior's process is completed.
Layer1: is activated when a none null value is detected on first layer, at the specific position.
Layer2: is activated when a none null value is detected on second layer, at the specific position.
...

Pos3d: 3d position to be converted into a 2d position in the affected grid.
Ref: basis in which the 3d position is expressed.
Layer1: First layer to be considered.
Layer2: Second layer to be considered.
...

Value1: Value of square from first Layer.
Value2: Value of square from second Layer.
...

Remember, if you want to express an object position just set the referential as your object, and let 3dpos to (0,0,0).

Warning

- by now the only possible values are bound to a 0-255 range.


Interface

Controls

Drag and Drop: Enables you to drag and drop a 2D Entity.

PushButton: Transforms a 2D Frame into a push button.

Fonts

Create Font: Creates a font from a provided texture.

Create System Font: Create a font from a system font name

Delete Font: Delete a font (created by CreateFont or CreateSystemFont)

Set Font Properties: Sets the visual appearance of a font.

Layouts

2D Curve Layout: Organize a set of 2D belong a 3D curve in space

2D Flow Layout: Organize a set of 2D entities horizontaly or verticaly

2D Grid Layout: Organize as a grid a set of 2D entities into a 2D Frame

3D Curve Layout: Organize a set of 3D belong a 3D curve in space

3D Flow Layout: Organize a set of 3D entities belong a direction in space

3D Grid Layout: Organize a set of 3D entities into a 3D Grid

Align 2D: Aligns a 2D Entity on a model.

Align 3D: Aligns 3D Entities on a model.

Primitives

Draw Rectangle: Draws a rectangle and a border at a specified position.

Screen

2D Picking: Returns the 3D Entity, the normal and the exact position of the 2d mouse picking

Additional View: Allows additional views to be displayed on screen simultaneously.

Get Proportional Screen Pos: Converts a given 2d position on the screen to a proportional position.

Get Screen Proportional Pos: Converts a position from a 2d proportional position to the screen.

Mouse Cursor: Display a texture instead of the standard cursor.

Mouse Cursor System: Change the system mouse cursor pointer.

Resize View: Allows main view to be resized.

Set Pickable: Sets the pickable state of a 3D Entity

Text

2D Text: Display a text on a 2D Frame, using a texture font

3D Text: Display a text on the plane XY of a 3D Frame, using a texture font

BitmapText Display: Displays a Bitmap Text on top of the 3D environment

Set Caret Position: Insert a caret into a string.

Text Display: Displays a text on top of the 3D environment


2D Curve Layout BB

 2D Curve Layout
Categorized in Interface/Layouts

Description

Apply to a BEOBJECT.
test - 2D Curve layout
2D Curve Layout.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Components: group containing the 2D entities to organize.
Center: if checked, we place the center of the frame on the curve.

The entities are placed on screen like if they were along the 3D curve


2D Flow Layout BB

 2D Flow Layout
Categorized in Interface/Layouts

Description

Apply to a BEOBJECT.
Organize a set of 2D entities horizontaly or verticaly
2D Flow Layout.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Components: group containing the 2D entities to organize.
Flow Alignment: alignement to use / target.
Top Margin: margin from the top of the target.
Side Margin: margin from the left or right side of the target (depends on alignement).
Gap Size: space between the entities displaced.
Horizontal Flow: if checked, create an horizontal flow else a vertical ones.
Set Parent: if checked, set the target as parent of the entities in group.

The target determine the position of the flow.


2D Grid Layout BB

 2D Grid Layout
Categorized in Interface/Layouts

Description

Apply to a BEOBJECT.
Organize a set of 2D entities into a 2D grid (i.e. an array)
2D Grid Layout.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Components Array: array containing only objects (Base Type only, not Parameter).
Margin: margins to add to the dimension of the target frame.
Horizontal Gap Size: horizontal space between the entities displaced.
Vertical Gap Size: vertical space between the entities displaced.
Resize: if checked, resizes the target frame to match the extents of the generated grid.
Set Parent: if checked, set the target as parent of the entities in the array.

The target determine the position of the grid.


2D Picking BB

 2D Picking
Version 2.00 - Virtools
Categorized in Interface/Screen

Description

Apply to a BEOBJECT.
Returns the 3D Entity, the normal and the exact position of the 2d mouse picking
2D Picking.cmo

Technical Information

In: triggers the process.

True: is activated when the ray intersects an object or a sprite.
False: is activated when the ray doesn't intersect an object.
Window Relative: Check this parameter if you give coordinates in the render window coordinate system, or leave it uncheck if you give them in the entire screen coordinates (like the values returned by the GetMousePosition behavior). For fullscreen mode, this parameter makes no difference.
Object Picked: The first object in Z order, under the picking.
Intersection Point: exact 3d point coordinates of the intersection point (this point is given in world space coordinates).
Intersection Normal: coordinates of the normal vector on the picked object.
UV Coordinates: coordinates on the 'texel' picked (pixel on the texture).
Distance from The Viewpoint: distance of the exact 3d point from the viewpoint
Face Index: index, on the object, of the picked face
Sprite: picked sprite, if any.

Local Output: check this if you want Intersection Point and Normal expressed in the picked object referential.


2D Text BB

 2D Text
Categorized in Interface/Text

Description

Apply to a 2DENTITY.
Display text in a 2D Frame.
2D Text.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Font:font created with the building blocks "Create Font" or "Create System Font".
Text:text to be displayed. The text can be multiline.
Alignment:alignement of the text in the frame.
Margins:margins to leave empty in the border of the frame.
Offset:offset at which the text is displayed inside the frame. This offset can be used to make a scrolling inside the frame, thus taking advantage of the frame clipping.
Paragraph Indentation:space to leave horizontally and vertically at each paragraph start (a paragraph begins just after a carriage return).
Background Material:material to be used if a background must be drawn (option "Background" enabled).
Caret Size:size of the caret in percent. The caret is only displayed when using the building blocks "Input String" or "Set Caret Position" and with the option "Show Caret" enabled.
Caret Material:material to be used for the display of the caret.

Text Extents:real extents of the text drawn. Can be used to achieve a scrolling with the Offset parameter.
Line Count:number of text lines displayed.

Text Properties:options of text displaying:

  • Screen Proportionnal: Enable this option if the text must be proportionnal of the screen size. Else, the size is fixed.
  • Background: Enable this to display a background material behind the text, using the extents of the text.
  • Clip To Dimension: Enable this to clip the text to the frame extents.
  • Resize Verticaly: Enable this to resize the frame according to the text height.
  • Resize Horizontaly: Enable this to resize the frame according to the text width. Works only with no wrapping and no justification.
  • WordWrap: Enables the word wrapping of the text (automatically put a word to the next line when it doesn't fit in the frame.)
  • Justified: Extension of the wrapping: words not fitting are sent to the next line and the spaces of the line are stretched for the line to fit exactly the frame width. These two options are incompatible with the Resize Horizontaly option.
  • Compiled: Enable this to compile the graphic data of the text, for more efficiency, if you know the string won't change after the first display.
  • Multiple: Transforms the behavior in an In-Out building block, allowing you to draw several text on several frames with a single building block. Typically you can use this with an Array containing a text and a position, then with an Array Iterator, move the frame to the stored position then display the text, and so on for each line of the array, all of this in one behavioral frame.
  • Show Caret: Enable this if you want the caret to be displayed, when there is one.

Remarks

Before you can display text, you must create a font with either Create System Font or Create Font.

See Also: Create System Font, Delete Font, 2D Text, 3D Text (all in the category Interface/Text).


3D Curve Layout BB

 3D Curve Layout
Categorized in Interface/Layouts

Description

Apply to a GROUP.
Organize a set of 3D belong a 3D curve in space
3D Curve Layout.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Curve: curve to position the 3D entities to organize.
A: starting position in percent on the curve to consider.
B: ending position in percent on the curve to consider.
Follow: if TRUE, the 3D Entity's orientation will point in the direction of the curve's tangent.
Roll: angle to roll around the follow axis.
Direction: specifies which base vector is to be the following direction (if the 'Follow' parameter is set to TRUE).
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

The entities in the group are placed along the curve.


3D Flow Layout BB

 3D Flow Layout
Categorized in Interface/Layouts

Description

Apply to a GROUP.
Organize a set of 3D entities belong a direction in space
3D Flow Layout.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Model: 3D Entity determining the position and direction of the flow.
Flow Direction:on which axis of the target referencial the flow must lie.
Flow Alignement: alignement to use / target.
Support: select depth start of the flow / target.
Top Margin: margin from the top of the target.
Side Margin: margin from the left or right side of the target (depends on alignement).
Offset Margin: margin from the XY plan of the target (depends on alignement).
Gap Size: space between the displaced entities.
Keep Children?: if checked, displace the childs of the entities in group.


3D Grid Layout BB

 3D Grid Layout
Categorized in Interface/Layouts

Description

Apply to a GROUP.
Organize a set of 3D entities into a 3D Grid
3D Grid Layout.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Model: Model determining the position and orientation of the grid. Entities will be parented to it.
Std Margin: margins in the axis X,Y to add to the dimension of the target frame.
Front Margin: margins in the axis +Z to add to the dimension of the target frame.
Rear Margin: margins in the axis -Z to add to the dimension of the target frame.
Support: type of alignement, on the Z axis.
Horizontal Gap Size: horizontal space between the entities displaced.
Vertical Gap Size: vertical space between the entities displaced.
Depth Gap Size: depth space between the entities displaced.

The target group must contain Arrays, representing a layer of the 3D grid. This array must only contains objects (Basic Type not Parameter).


3D Text BB

 3D Text
Categorized in Interface/Text

Description

Apply to a 3DENTITY.
Display text on the XY plane of a 3D Frame.
3D Text.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates when the process is activated.
Exit Off: activates when the process is deactivated.

Font: font to use (previously created with the BBs "Create Font" or "Create System Font").
Text: text to display. The text can be one or several lines.
Alignment: alignment of the text in the frame.
Margins: margins to leave empty in the border of the frame.
Offset: offset at which the text is displayed inside the frame. This offset can be used to make a scrolling inside the frame, thus taking advantage of the frame clipping.
Paragraph Indentation: space to leave horizontally and vertically at each paragraph start (a paragraph begins just after a carriage return).
Background Material: material to be used if a background must be drawn (option "Background" enabled).
Caret Size: size of the caret in percent. The caret is only displayed when using the building blocks "Input String" or "Set Caret Position" and with the option "Show Caret" enabled.
Caret Material: material to be used for the display of the caret.

Text Extents: real extents of the text drawn. Can be used to achieve a scrolling with the Offset parameter.
Line Count: number of text lines displayed.

Text Properties: options of text displaying:

  • Screen Proportionnal: Enable this option if the text must be proportional of the screen size. Else, the size is fixed.
  • Background: Enable this to display a background material behind the text, using the extents of the text.
  • Clip To Dimension: Enable this to clip the text to the frame extents.
  • Resize Verticaly: Enable this to resize the frame according to the text height.
  • Resize Horizontaly: Enable this to resize the frame according to the text width. Works only with no wrapping and no justification.
  • WordWrap: Enables the word wrapping of the text (automatically put a word to the next line when it doesn't fit in the frame.)
  • Justified: Extension of the wrapping: words not fitting are sent to the next line and the spaces of the line are stretched for the line to fit exactly the frame width. These two options are incompatible with the Resize Horizontaly option.
  • Compiled: Enable this to compile the graphic data of the text, for more efficiency, if you know the string won't change after the first display.
  • Multiple: Transforms the behavior in an In-Out building block, allowing you to draw several text on several frames with a single building block. Typically you can use this with an Array containing a text and a position, then with an Array Iterator, move the frame to the stored position then display the text, and so on for each line of the array, all of this in one behavioral frame.
  • Show Caret: Enable this if you want the caret to be displayed, when there is one.

Remarks

Before you can display text, you must create a font with either Create System Font or Create Font.

See Also: Create System Font, Delete Font, 2D Text, 3D Text (all in the category Interface/Text).


Additional View BB

 Additional View
Categorized in Interface/Screen

Description

Apply to a CAMERA.
Allows additional views to be displayed on screen simultaneously.
Additional View.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated when the behavior's process is started.
Exit Off: is activated when the behavior's process is stopped.

View Region: the screen region defined by a rectangle in which the render will be done.
Render Options: options of rendering.
Overwrite 2D: if TRUE, renders the view above every 2d content.


Align 2D BB

 Align 2D
Categorized in Interface/Layouts

Description

Apply to a 2DENTITY.
Aligns a 2D Entity on a model.
Align 2D.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Model: model on which the frame will be aligned.
Alignment: type of alignement.
Center: if a center alignement is desired, either vertically or horizontally, should the frame be centered in the model or left alone.
Margins: margins of alignement, added to the model extents.


Align 3D BB

 Align 3D
Categorized in Interface/Layouts

Description

Apply to a 3DENTITY.
Aligns a 3D Entity.
Align 3D.cmo

Technical Information

In: activates the process.
Out: activates when the process is complete.

Model: 3D Entity used to align the element.
Alignment: type of alignment along the X and Y plane.
Support: type of alignment along the Z axis.
Center: if selected, the element is centrally aligned (vertically or horizontally).
Margins: margins of alignment in X and Y plane, added to model extents.
Depth Margins: margins of alignment, in axis Z, added to model extents.


BitmapText Display BB

 BitmapText Display
Categorized in Interface/Text

Description

Apply to a BEOBJECT.
Displays Bitmap Text on top of the 3D environment
BitmapText Display.cmo

Technical Information

On/Reset: activates the behavior, update the displayed text and reset the inserted lines.
Off: deactivates the behavior.
Carriage Return: Add a new line to the text to be displayed
Exit On: is activated when the behavior was triggered by 'On' input.
Exit Off: is activated when the behavior was triggered by 'Off' input.
Line Added: is activated when a new line is added.

Position: x,y position for the text on the screen, in pixels. It represents the top margin in Y and the left margin in X for the align left mode, the right margin in X for the right aligned mode and the center of the text for center align mode.
Character Spacing: Choose the number of pixel between each characters. Default is 1.
Scale: Choose the horizontal and vertical scaling of the font. Warning values greater than 2 and smaller than 0.5 lead to disgracious visual effects (Moreover, values < 1 may crash some machines...).
Alignment: Choose the justification of the text: either left justified, centered on the position or right justified.
Vertical Spacing: When printing several lines with the carriage return input, you can choose here the space (in pixels) to leave between each line.
Text: Text you want to display. You can change the type of this parameter to display something else.

Font: The chosen font to be used for displaying the string. The font is a 2DSprite with a fixed set of characters drawn in it, each character separed by vertical lines. The bitmap must start by a vertical line of a color, followed by some spaces (representing the typical pixels to let for 'space' character) and another vertical lines + all the other characters. The characters used are:

!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
Look at the 2DSprite/ArialFont.bmp in the "General_Resources" for an example of font designing....
Enter the character "|" if you want a carriage return in your string.
If you want to change dynamically the parameters printed in the string, you'll need to loop the behavior in the "On" input.
You must provide input parameters (e.g.: the string to be displayed )
You can add any input parameters (of any type) as you want and they'll be printed, separated by a space.


Create Font BB

 Create Font
Categorized in Interface/Fonts

Description

Apply to a BEOBJECT.
Creates a Font from a specified Texture.
Fonts.cmo

Technical Information

In: activates the process.
Out: activates when the process is complete.

Font Name: name for the font: must be unique.
Font Texture: the Texture from which to create the font.
Horizontal/Vertical Character Number: number of characters horizontally and vertically in the texture.
Proportionnal: should characters be proportionally spaced.
Font Zone: zone of the texture in pixels where the font should be read.
First Character: ASCII code of the first character present in the Texture.

Space Size: Percentage of a character cell to be used for the space (by default 30%) This option will not be saved, so you have to leave your Create Font BB if you change it.

Font: the created font.

Remarks

Create Font only creates a font - to display text using this font, use either of the BBs 2D Text or 3D Text.

See Also: Create System Font, Delete Font, 2D Text, 3D Text (all in the category Interface/Text).


Create System Font BB

 Create System Font
Categorized in Interface/Fonts

Description

Apply to a BEOBJECT.
Create a font from a system font name
Fonts.cmo

Technical Information

In: activates the process.
Success: activates if a new system font is created.
Error: activates if no font could be created.

Font Name: name used to identify the font.
System Font Name: select the system font to use.
Font Weight: select the weight of the font to use.
Italic: check this to use the italic version of the selected font.
Underline: check this to use the underlined version of the selected font.

Font Created: a font identifier, give this to the related building blocks.

Texture Resolution: select the desired size of the generated texture, higher resolution give nicer font but use more video memory.
Full Charset: if checked, draw characters with ASCII code > 128, else we use a half sized texture
Render Control Characters: if checked we draw the control character of ASCII table.
Dynamic Texture: if checked the texture created is dynamic.
Font Size: set the font size.

Remarks

Create System Font only creates a font - to display text using this font, use either of the BBs 2D Text or 3D Text.

See Also: Create Font, Delete Font, 2D Text, 3D Text (all in the category Interface/Text).


Delete Font BB

 Delete Font
Categorized in Interface/Fonts

Description

Apply to a BEOBJECT.
Delete a font (created by CreateFont or CreateSystemFont)
Fonts.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Font: the font identifier of the font to delete.

This block releases the ressources occupied by a font. The font could be a font created by 'Create Font', or 'Create System Font' blocks
See Also: 'Create Font', 'Create System Font', 'Text2D', 'Text3D' (in the Interface/Text category).


Drag and Drop BB

 Drag and Drop
Categorized in Interface/Controls

Description

Apply to a 2DENTITY.
Enables you to drag and drop a 2D Entity.
Drag and Drop.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Limit Rectangle: Rectangle limitting the entity. Let 0,0,0,0 if the entity must not be constraint.
This behavior allow you to pick and move any 2D Entity, with its hierarchy, with the possibility of constraint its moving to a given rectangle.


Draw Rectangle BB

 Draw Rectangle
Categorized in Interface/Primitives

Description

Apply to a BEOBJECT.
Draws a rectangle and a border at a specified position.
Draw Rectangle.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Interior: should the interior of the rectangle be drawn.
Color: color of the rectangle.
Material: material to use for the rectangle rendering.
Screen Coordinates: position and size of the rectangle on screen.
Texture Coordinates: texture coordinates of the rectangle.
Border: should the border of the rectangle be drawn.
Border Color: color of the border.
Border Size: size of the border, in screen coordinates.


Get Proportional Screen Pos BB

 Get Proportional Screen Pos
Categorized in Interface/Screen

Description

Apply to a BEOBJECT.
Converts a given 2d position on the screen to a proportional position.
Get Proportional Screen Position.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Pos X: X position on screen.
Pos Y: Y position on screen.

%Pos X: proportional X position on screen.
%Pos Y: proportional Y position on screen.

eg: if the 3dview size is (400,300), and X=200,Y=150 then %X=50 and %Y=50.

Warning

- the position is supposed to be given in the 3dview window.


Get Screen Proportional Pos BB

 Get Screen Proportional Pos
Categorized in Interface/Screen

Description

Apply to a BEOBJECT.
Converts a position from a 2d proportional position to the screen.
Get Screen Proportional Pos.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

%Pos X: proportional X position on screen.
%Pos Y: proportional Y position on screen.

Pos X: X position on screen.
Pos Y: Y position on screen.

eg: if the 3dview size is (400,300), and %X=50,%Y=50 then X=200 and Y=150.

Warning

- the position is to be given in the 3dview window.


Mouse Cursor System BB

 Mouse Cursor System
Categorized in Interface/Screen

Description

Apply to a BEOBJECT.
Changes the system mouse cursor pointer.
Mouse Cursor System.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

Mouse Pointer: the pointer to display.

Note: The Frame Rate must use 'synchronize to screen' and the Behavior Rate 'Linked to Frame Rate' (see Time Settings) in order to avoid that the default system cursor reappears in frames where Virtools doesn't process it.


Mouse Cursor BB

 Mouse Cursor
Categorized in Interface/Screen

Description

Apply to a BEOBJECT.
Display a texture instead of the standard cursor.
Mouse Cursor.cmo

Technical Information

On: activates it.
Off: disables it.

Cursor Texture: texture to use to represent the mouse cursor.
Cursor Size: size in screen coordinates of the mouse cursor.
Cursor Color: color and transparency of the cursor.
Shadow: either to draw a shadow under the cursor.
Shadow Distance: distance of the shadow in screen coordinates.
Shadow Angle: angle of projection of the shadow.
Shadow Intensity: intensity of the shadow.


PushButton BB

 PushButton
Categorized in Interface/Controls

Description

Apply to a 2DENTITY.
Transforms a 2D Frame into a push button.
PushButton.cmo

Technical Information

On: activates the process.
Off: deactivates the process.
Disable: disables the button.

Pressed: is activated when button is pressed.
Released: is activated when button is released.
Active: is activated when button is activated.
Enter Button: is activated when the cursor enters the button.
Exit Button: is activated when the cursor exits the button.
In Button: is activated when the cursor is in the button.

Released Material: Material to use as the button is released.
Pressed Material: Material to use as the button is pressed.
RollOver Material: Material to use when the mouse is on the button.
Font: font to use if the button must have a text on it.
Text: text to display on the button.
Pressed Offset: Offset to apply to the text when the button is pressed.
Disabled Material: Material to use as the button is disabled.

Events: Events to be taken into account.

Current Material: Material currently used on the button.


Resize View BB

 Resize View
Categorized in Interface/Screen

Description

Apply to a BEOBJECT.
Allows main view to be resized.
Resize View.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated when the behavior's process is started.
Exit Off: is activated when the behavior's process is stopped.

View Region: The screen region defined by a rectangle the main view will be resized.


Set Caret Position BB

 Set Caret Position
Categorized in Interface/Text

Description

Apply to a BEOBJECT.
Insert a caret into a string.
Set Caret Position.cmo

Technical Information

In: triggers the process.
Out: activated when the behavior's process is completed.

Text: string to insert caret into.
Caret Position: position ofthe caret in the string. -1 means no caret.
Text: string with caret into.

Warning

- the caret will only be displayed by 2D Text and 3D Text building blocks.


Set Font Properties BB

 Set Font Properties
Categorized in Interface/Fonts

Description

Apply to a BEOBJECT.
Modifies font properties, changing the appearance of a font.
Fonts.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Font: font created with the building blocks "Create Font" or "Create System Font".
Space: space between characters (can be negative).
Scale: factor to multiply the characters.
Italic Offset: italic offset (positive is for right italic, negative is for left).
Color: color of the font (top color of the font if gradient is enabled).
End Color: bottom color of the font if gradient is enabled.
Shadow Color: color of the shadow, if the shadow is enabled.
Shadow Angle: angle of the projection of the shadow.
Shadow Distance: distance of the shadow from the main font.
Shadow Size: scale of the shadow.
Lit Material: material to use for the font if the lighting is enabled for the font.

Font Properties: properties of the font:

  • Gradient: Enables a gradient rendering for the font.
  • Shadow: Enables the shadowing of the font.
  • Lighting: Enables the lighting of the font.
  • Disable Filter: Enables the filtering of the texture.

Remarks

Set Font Properties only modifies the properties of an existing font - you must first create a font using Create System Font or Create Font. To display text, use the BBs 2D Text or 3D Text.

See Also: Create System Font, Delete Font, 2D Text, 3D Text (all in the category Interface/Text).


Set Pickable BB

 Set Pickable
Categorized in Interface/Screen

Description

Apply to a RENDEROBJECT.
Sets the pickable state of a 3D Entity
Set Pickable.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Pickable: if TRUE, the Render Object (3d entity, sprite, etc...) can be picked.


Text Display BB

 Text Display
Version 2.00 - Virtools
Categorized in Interface/Text

Description

Apply to a BEOBJECT.
Displays text on top of the 3D environment
Text Display.cmo

Technical Information

On: activates the behavior.
Off: deactivates the behavior.

Exit On: is activated when the behavior was triggered by 'On' input.
Exit Off: is activated when the behavior was triggered by 'Off' input.

Offset: X/Y offset for the text position on the screen (X/Y=0/0 is the top left corner of the screen).
Color: color expressed in RGBA.
Align: Chooses the alignment of the text inside the sprite text.
Size: vertical size of the text (expressed pixels).
Text: Text you want to display. You can change the type of this parameter to display something else.

Sprite Size: size of the sprite in which you draw the text (the smaller, the faster).

You must provide input parameters (e.g.: the string to be displayed ). You can add any input parameters (of any type) as you want and they'll be printed, separated by a space. If you want to change the color, the size of the text, you need to reenter by the On input.

See also: 2D Interface and Text Display Whitepaper


Lights

Basic

Set Light Attenuation: Sets the Constant, Linear and Quadratic Attenuation of a light.

Set Light Color: Sets the Color of a Light.

Set Light Range: Sets the range of the light.

Set Light Target: Makes a 3D Entity become the target of a light.

Set Light Type: Sets the type of a Light.

Set Specular Flag: Tells whether a light should be specular or not.

Spot Light Properties: Sets the properties of a spotlight (internal and external diameter of the light cone).

FX

Lens Flare: Renders the Light with a specific 'Light Texture'.

Light Sprite: Renders the Light with a specific 'Light Texture'.

Lightmap: Calculates lightmaps (textures containing lighting and shadows) for a set of objects with a set of lights.

Static Lightmap: Generates objects with lightmaps (textures containing lighting and shadows).


Lens Flare BB

 Lens Flare
Categorized in Lights/FX

Description

Apply to a LIGHT.
Simulates a 'lens flare' by rendering a Light with a specific Texture.
Lens Flare.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates when the process is activated.
Exit Off: activates when the process is deactivated.

Flare Array: Array containing flares, glares and glow values (see below).
Flare Texture: Texture containing one or several flares, glares or glow elements.
Size Scale: allows you to change the size of all flares at once by the same factor.

Read Array Each Frame: if selected, Lens Flare reads Flare Array at each frame. This adds to processing time, and is only useful if the Flare Array changes dynamically between frames.

Remarks

Flare Array must have the following format - note that the order of the columns is important, the names are not:

0. Texture Region (Parameter Rectangle): rectangle defining the flare in the Texture. (0,0,0,0) means the entire Texture.
1. Position (Float): position of the flare on the virtual line, going through the light and intersecting the center of the screen. 1 means the light, 0 means the center of the screen.
2. Color (Parameter Color): color of the flare.
3. Size (Parameter 2D Vector): horizontal and vertical size of the flare.
4. Angular Speed (Float): rotating speed of the flare when it moves. 0 means no rotation at all.
5. Fade In Time (Integer): time in ms for the flare to appear.
6. Fade Out Time (Integer): time in ms for the flare to disappear.
7. Visibility Angle (Parameter Angle): angle from the center of the camera in which the flare is visible. 0 means in fact 90° so the entire half space before the camera. Use different values between 10 and 30° for the rings to see them disappear one after the other.

Here is an example of a 'lens flare', followed by the Flare Texture and Flare Array used; Size Scale was set to 0.5,0.5.

Flare Texture:

Flare Array:


Light Color Progression BB

 Light Color Progression
Categorized in Lights/FX

Description

Apply to a LIGHT.
OBSOLETE.

Makes a Light progressively change from one color to another.

Technical Information

In: triggers the process
Loop In: triggers the next step in a behavior's process loop.

Out: is activated when the process is completed.
Loop Out: is activated when the behavior's process needs to loop.

Duration: how long the whole process should last.
Progression Curve: 2D Curve representing the progression of the 3D Entity along its movement.
Start Color: initial color in RGBA.
End Color: final color in RGBA.

Time Based: If checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.

- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.

Warning

This building block is obsolete and is only included for backwards compatibility.


Light Sprite BB

 Light Sprite
Categorized in Lights/FX

Description

Apply to a LIGHT.
Renders the Light with a specific 'Light Texture'.
Light Sprite.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Out (Loop): is activated when one building block process is completed.

Light Texture: name of the texture used as the sprite.
Size Factor: as a percentage, with the Sprite having the same size as the light's range at 100%.

Remarks

- This building block only needs to be looped if the Light Texture or the Size Factor need to be changed at each frame.
To loop it just link the 'Out (Loop)' output to the 'On' input.


LightMap BB

 LightMap
Categorized in Lights/FX

Description

Apply to a BEOBJECT.
Generates and displays 'lightmaps' (textures containing lighting and shadows) for a Group of 3DOBJECTs from a given set of Lights.
Lightmap.cmo

Technical Information

On: activates the display of lightmaps (n.b. lightmaps must first be generated).
Off: deactivates the display of lightmaps.
Generate: generates lightmaps.

Exit On: activates when the display of lightmaps is activated.
Exit Off: activates when the display of lightmaps is deactivated.
Exit Generate: activates when lightmaps are generated.

Receiving Objects: the Group of elements to lightmap. If no Group is selected, all 3DOBJECTs in the current Level are selected.
Occluder Objects: the Group of elements that cast shadows or transmit light (transparent objects only). if no Group is selected, all 3DOBJECTs of the current Level are selected.
The elements in this Group are not necessarily the same as the elements in the Group Receiving Objects: for example a red window should be in the occluder group to let the light pass through, but not in the receiving group because lightmaps will alter its transparent rendering. On the other hand, a flat floor will receive shadows but will probably not cast them, so not putting it in the occluders group will accelerate the process slightly.
Lights: the Group of Lights to use in creating lightmaps. If no Group is selected, all Lights of the Level are used.
Lightmap Resolution: the resolution of the lightmaps, according to the world scale. 1 means a texel = 1 world unit, 0.1 means a texel = 0.1 world unit etc. The lower this number, the sharper shadows appear, a greater number will make shadows smoother but the creation process slower.
Supersampling: used to make light/shadow calculations sharper without expanding the size of the textures. 2 means than for each texel of lightmap, 4 rays (2 horizontally and 2 vertically) are cast instead of 1, giving more accuracy for occluder edges. This pIn multiplies calculation time by its square value, but not the texture size.
Blur Pass: specifies the number of gaussian blur passes to apply to the generated lightmap. This smoothes shadows, giving the impression of a more diffuse lighting, applying greater realism to the final scene. Values between 2 and 4 generally give the best results.
Threshold: an angle taken into account when finding the planar mapped faces. The greater the angle, the more faces found to map in a single Group. E.g. an angle of 0 means than only REALLY coplanar faces, like the two triangle faces of a plane. With this value, a cylinder segmented in 16 segments will end up with 18 group of faces (16 segments + 1 top cap + 1 bottom cap) leading to a poor realism because joining textures will be noticeable. Using an angle of 90° for example will lead to 6 group of faces, giving a smoother impression (less joining texture to be noticed).
In any case, try to avoid smooth objects in the receiving group, because the mapping will never be perfect.
Opacity: a color that to multiply the lightmap by. This allows effects such as flickering for example, by dynamically dimming this color.

Save?: if selected, the lightmaps are saved with the composition. This means lightmaps will not have to be generated again; however a Lightmap BB is still required to display lightmaps (see also the BB Static Lightmap).
Show Polygons?: if selected, random colors are displayed, showing which faces are grouped together.
Display Computation Time?: if selected, the time taken for generating lightmaps is written to the Event Log after completion.

See also: Static LightMap


Set Light Attenuation BB

 Set Light Attenuation
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Sets the Constant, Linear and Quadratic Attenuation of a light.
Set Light Attenuation.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Constant Attenuation: positive float value for constant light attenuation.
Linear Attenuation: positive float value for linear light attenuation.
Quadratic Attenuation: positive float value for quadratic light attenuation.

This building block is useful when used for flashing lights, in which case a value such as 10 would be appropriate.


Set Light Color BB

 Set Light Color
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Sets the Color of a Light.
Set Light Color.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Color: color expressed in RGBA.


Set Light Range BB

 Set Light Range
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Sets the range of the light.
Set Light Range.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Range: distance from which meshes no longer receive light.


Set Light Target BB

 Set Light Target
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Makes a 3D Entity become the target of a light.
Set Light Target.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Target: 3D Entity to target.

This building block doesn't need to be looped. (ie: the light will constantly follow the selected object)

Warning

- this building block is valid only with a spotlight.
- if you delete the light, the target may also be deleted depending of the options you used for deletion.


Set Light Type BB

 Set Light Type
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Sets the type of a Light.
Set Light Type.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Light Type: Point, Spot, Directional.


Set Linear Attenuation BB

 Set Linear Attenuation
Categorized in Lights/Basic

Description

Apply to a LIGHT.
OBSOLETE.

Sets the value of the 'Linear Attenuation' of a Light

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Linear Attenuation: positive float value.

Useful for flashing lights: set the constant to a high value like 10.

Warning

This building block is obsolete and is only included for backwards compatibility


Set Quadratic Attenuation BB

 Set Quadratic Attenuation
Categorized in Lights/Basic

Description

Apply to a LIGHT.
OBSOLETE.

Sets the value of the 'Quadratic Attenuation' of a Light.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Quadratic Attenuation: positive float value.

Useful for flashing lights: set the constant to a high value like 10.

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Specular Flag BB

 Set Specular Flag
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Tells whether a light should be specular or not.
Set Specular Flag.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Specular Highlight: Specifies if you want the light to produce a specular highlight.

To make highlights appear on an object, it should be defined as having the specular property.


Spot Light Properties BB

 Spot Light Properties
Categorized in Lights/Basic

Description

Apply to a LIGHT.
Sets the properties of a spotlight (internal and external diameter of the light cone).
Spot Light Properties.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Fall Off: external angle of the light cone.
Fall Off Shape: shape of the attenuation of the light cone (linear=1.0, fade with an asymptote at 0 = 5.0, fade with an asymptote to 1.0 = 0.2 ... etc).
Hot Spot: inner angle of the light cone.


Static LightMap BB

 Static LightMap
Categorized in Lights/FX

Description

Apply to a BEOBJECT.
Displays previously generated lightmaps (Textures showing lighting and shadows).
Static Lightmap.cmo

Technical Information

In: activates the process.

Out: activates when the process completes.

Receiving Objects: the Group of elements to lightmap. If no Group is selected, all 3DOBJECTs in the current Level are selected.
Occluder Objects: the Group of elements that cast shadows or transmit light (transparent objects only). if no Group is selected, all 3DOBJECTs of the current Level are selected.
The elements in this Group are not necessarily the same as the elements in the Group Receiving Objects: for example a red window should be in the occluder group to let the light pass through, but not in the receiving group because lightmaps will alter its transparent rendering. On the other hand, a flat floor will receive shadows but will probably not cast them, so not putting it in the occluders group will accelerate the process slightly.
Lights: the Group of Lights to use in creating lightmaps. If no Group is selected, all Lights of the Level are used.
Lightmap Resolution: the resolution of the lightmaps, according to the world scale. 1 means a texel = 1 world unit, 0.1 means a texel = 0.1 world unit etc. The lower this number, the sharper shadows appear, but the greater the size of texture lightmaps generated and time taken to calculate.
Supersampling: used to make light/shadow calculations sharper without expanding the size of the textures. 2 means than for each texel of lightmap, 4 rays (2 horizontally and 2 vertically) are cast instead of 1, giving more accuracy for occluder edges. This pIn multiplies calculation time by its square value, but not the texture size.
Blur Pass: specifies the number of gaussian blur passes to apply to the generated lightmap. This smoothes shadows, giving the impression of a more diffuse lighting, applying greater realism to the final scene. Values between 2 and 4 generally give the best results.
Threshold: an angle taken into account when finding the planar mapped faces. The greater the angle, the more faces found to map in a single Group. E.g. an angle of 0 means than only REALLY coplanar faces, like the two triangle faces of a plane. With this value, a cylinder segmented in 16 segments will end up with 18 group of faces (16 segments + 1 top cap + 1 bottom cap) leading to a poor realism because joining textures will be noticeable. Using an angle of 90° for example will lead to 6 group of faces, giving a smoother impression (less joining texture to be noticed).
In any case, try to avoid smooth objects in the receiving group, because the mapping will never be perfect.

Display Computation Time?: if selected, the time taken for generating lightmaps is written to the Event Log after completion.

Remarks

The original objects will be kept, so the new one will be at the exact same place. Hide the old objects and if the result is what you expected, destroy them. You should use the Lightmap building block first to tune your rendering (place lights exactly, change the resolution, blur passes and supersampling), then, when the result is good, use Static Lightmap to creates objects with lightmaps that will not require a specific building block to render correctly (should be faster too).

See also: LightMap


Logics

Array

Add Row: Adds a new row to the array.

Array Load: Loads elements into an array from a formatted file.

Array Save: Writes elements from an array to a text file.

Change Value If: Get elements from an array, using the input parameter key and then replace it by the 4th input parameter's value.

Clear Array: Removes all the rows of the array.

Column Operation: Performs an operation between two columns and put the result in a third one.

Column Product: Performs the multiplication of all the elements of a column.

Column Sum: Calculates the sum of all the elements of a column.

Column Transform: Performs an operation between one column value and a operand and store the result in the column.

Create Group From Array: Create a group with entities elements matching the given value.

Get Cell: Gets the cell of a chosen row and column.

Get Column Name: Gets the name of a column.

Get Highest: Gets the element of an array, which value in the given column is the highest.

Get Key Row: Gets elements from an array, using the key column as a search criterion on the given key value.

Get Lowest: Gets the element of an array, which value in the given column is the lowest.

Get Nearest: Gets the element of an array, which value in the given column is the nearest from the reference value.

Get Row: Gets the elements of a chosen row.

Insert Column: Inserts a column in the array.

Iterator: Iterate on each row of an array and return the values of the current row.

Iterator If: Iterates on each row matching a value and return the values of them.

Make Rows Unique: Assures the uniqueness of the elements of a column.

Move Column: Moves a column of the array.

Move Row: Moves a row of the array.

Remove Column: Removes a column of the array.

Remove Key Row: Remove elements from an array.

Remove Row: Remove a row of the array.

Remove Row If: Remove rows matching a value from an array.

Reverse Order: Reverse the rows order of the array.

Row Search: Get the first row index found in an array, where the value in the chosen column match the comparison with the reference value given.

Set Cell: Sets the element of a chosen row and column.

Set Key Row: Sets the elements of a row, using the key column as a search criterion.

Set Row: Set the elements value of a row of an array.

Shuffle Order: Shuffle the rows order of the array

Sort Rows: Sorts the rows of an array, according to the values of a given column.

Swap Rows: Swaps two rows of an array.

Test Cell: Compare an array element (cell) with a given reference value.

Value Count: Returns the number of elements in a column matching the given value.

Attribute

Has Attribute: Gets the parameter of an attribute (if it exists) on the object.

Objects With Attribute Iterator: Retrieves each element of a group with a particular attribute

Remove Attribute: Removes an attribute from the object.

Set Attribute: Gives an attribute to the object, and/or sets the value of this attribute.

Calculator

Bezier Transform: Transform a float value into another float value according to a 2d bezier curve shape, and given boundaries.

Calculator: Calculates the value of an arithmetic expression; 'a' stand for the first parameter, 'b' for the second, ...etc.

Get Component: Extracts the components of a COLOR, VECTOR or 2dVECTOR.

Get Delta Time: Returns the elapsed time between the previous and the current Behavioral Process.

Identity: Outputs the Input Parameter(s) when activated.

Mini Calculator: Processes a simple operation (+,-,*,/) between 'a' and 'b'

Modify Component: Modify a vector

Op: Process any existing Parameter Operation (go to settings).

Per Second: Calculates a progression (Y) according to a given speed (X) : Y=X*Elapsed Time During One Frame. X can be either an Angle, a Float, a Percentage, Vector or a 2dVector.

Random: Retrieves a Random Variable between 'Min' an 'Max'.

Set Component: Composes a COLOR, VECTOR or 2dVECTOR, by specifying each components.

Threshold: Binds a variable between two limits (Min and Max), and exit by the corresponding output according to the comparison result.

Variation: Computes the difference between old and new value of X.

Groups

Add To Group: Adds the object to a Group.

Fill Group By Class: Add all objects of a given type to the group.

Get Nearest In Group: Get the nearest object in the selected group from the given position.

Group Clear: Remove all the elements of a group.

Group Iterator: Retrieves each element of a group.

Group Operator: Makes combination of groups and objects wearing attributes.

Is In Group: Check if the object is in a specific group.

Remove From Group: Removes the object from a Group.

Interpolator

Interpolator: Performs an interpolation between 2 parameters

Interpolator Object Orientation: Performs an interpolation between orientations of two given 3D Entity.

Loops

Bezier Progression: Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of milliseconds.

Chrono: Chronometer (ON=Start, OFF=Stop).

Collection Iterator: Retrieves each element of a Collection.

Counter: Exits 'MaxCount' times by the 'Looping' output and when finished, exits by 'Out' output.

Delayer: Waits for a given time to elapse using internal looping.

Hierarchy Parser: Iterate recursively on an object and all its children.

IBCQ: Incremental Bezier Curve Query: Interpolates a float according to a 2D Bezier curve in the [0,1] range.

Linear Progression: Increments from 'Start Value' to 'End Value' in 'Number of Steps' steps.

Noise Progression: Interpolates a float according to a Perlin noise function in the [Min,Max] range, in a given number of milliseconds (or frames).

Timer: Waits (throw looping) for a given time to has elapsed.

While: Loops while 'Condition' is TRUE.

Message

Broadcast Message: Sends a Message to every objects waiting for it.

Check For Message: Check the message manager to see if a specific message has been received by the object.

Get Message Data: Reads the data bound with the selected message.

Send Message: Sends a Message to a 3D Entity.

Send Message To Group: Sends a Message to each Object of a Group.

Switch On Message: Activates the appropriate output when receiving a message.

Wait Message: Waits the receipt of a Message.

Streaming

All But One: Activates all the Outputs but not the one corresponding to the activated input.

Binary Memory: Memorizes in a 'State Memory' whether the behavior was triggered by 'In 0' or 'In 1'.

Binary Switch: Activates the appropriate output, according to a Boolean condition.

Bool Event: Detects a boolean value change.

FIFO: First In First Out

Keep Active: Keeps streaming activated even if inputs has been activate only once.

LIFO: Last In First Out

Nop: Join several links and dispatch the stream to all the outputs.

One At A Time: When reseted, this building block activates a Output corresponding to the last activated Input.

Parameter Selector: According to the Input activated, routes the corresponding Input Parameter to the Output Parameter.

Priority: Sets priorities between several signals (Inputs Activation).

Random Switch: Switches the sequential stream to a randomly chosen ouput according to each coef.

Sequencer: When 'In' is activated for the nth time, exits by the nth output.

Specific Bool Event: Detects a boolean value change. Same as 'BoolEvent', but with specific outputs.

Stop & Go: Activates the output only when the input stops being active.

Streaming Event: Activates outputs on the input activation change.

Switch On Parameter: Switches the sequential stream to the corresponding ouput, following the result of comparison between 'Test' and the others input parameters

Trigger Event: activates 'Activated' output when 'In' begins to be activated / activates 'Deactivated' output when 'In' stops being activated.

Strings

Create String: Creates a string by concatenating elements, separating them by an optionnal delimiter.

Get SubString: Gets a sub string from an initial string.

Load String: Loads a string from a file.

Output To Console: Displays a string in the Dev console.

Reverse String: Reverse the given string.

Scan String: Retrieves values (float, vector or anything else) from a string.

Synchro

Enter Critical Section: Makes the object enter a critical section.

Leave Critical Section: Makes the attached object leave the critical section.

Rendezvous: Waits for a group of objects/characters expected to be at the rendez-vous to all be present in order to allow them to pass through. You need to choose a Meeting Name and a Number of participants.

Wait For All: Waits until all behavior Inputs have been activated to activate the output

Test

Is In View Frustum: Tests if the object is in the viewing frustrum of the active camera.

Object Between: Tests if there is an object between the two given entities

Proximity: Compares the distance between two 3D Entities with a given threshold distance.

Ray Box Intersection: Returns the nearest object intersected by the ray, the position of the intersection point and the normal at this point.

Ray Intersection: Returns the nearest object intersected by the ray, the position of the intersection point and the normal at this point.

Test: Activates the appropriate output, according to the test between A and B.


Add Object To Group BB

 Add Object To Group
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
OBSOLETE - see Add to Group BB.

Adds the Object to a Group.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Group: group to which the object will be added.
Object: object to add to the group.

See also: Add To Group.

Warning

This building block is obsolete and is only included for backwards compatibility.


Add Row BB

 Add Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Adds a new row to the array.

Technical Information

In: triggers the process.

Out: is activated if the row is rightly added.
Already Present: is activated if the specified value in the key column already exists.

Unique Key Column: if TRUE, then adding a value.

This building block, when attached to an array or when given an array as a target, creates as many parameters as there are columns in this array, each parameter of the type of the corresponding column. When activated, the building block add a new row at the end of the array and set the values of this row with the specified input parameters.
If the Unique Key Column setting is set to TRUE, it creates the new row only if the value in the key column wasn't already present in the array. (If the value in the key column was already present, the Already Present output is activated).


Add To Group BB

 Add To Group
Categorized in Logics/Groups

Description

Apply to a BEOBJECT.
Adds the object to a Group.
Group Iterator - Add To Group - Remove From Group - Is In Group.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Group: group to which the object will be added.

See also: Is In Group, Remove From Group.


All But One BB

 All But One
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Activates all the Outputs but not the one corresponding to the activated input.
All But One - Switch On Parameter.cmo

Technical Information

In 0: triggers the process.
In 1: triggers the process.

Out 0: is activated if we enter by any Input but the 'In 0'.
Out 1: is activated if we enter by any Input but the 'In 1'.

Activates all the Outputs but not the one corresponding to the activated input.

Warning

- You can add as many inputs as needed (number of outputs will automatically be equal to the number of inputs).
- Note also, there's a priority order from up to down if 2 signals occur at same time.


Array Load BB

 Array Load
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Loads cells into an array from a formatted file.

Technical Information

In: triggers the process.

Out: is activated if the file is loaded succesfully.
File Error: is activated if the file couldn't be loaded correctly.

File: name of the file containing the array to load. Must be in given as an absolute path or relative to the .cmo or the .exe.
Append: if TRUE, appends the file contents to your existing array.
First Column: indicates the column in your array that should receive the first column of your file letting you load information without destroying the first columns.

This behavior, when attached to an array or when given an array as a target,
read the input of the given file, formatted in this style:

    value<tab<value<tab<value↵
    value<tab<value<tab<value↵
    value<tab<value<tab<value↵
    etc...
Native supported types are INTEGER, FLOATS, STRINGS, OBJECTS.
for all other types, a PARAMETER will be created, with the type of the analysed parameter.
eg: if the string "0,1,0" is found in a Parameter Column, then the vector (0,1,0) will be added to the array as a Parameter containing vectors.
Objects are referenced by their names. The name is read from the file and then we search in the current level an object with the same name, whatever its class can be: therefore, use unique names for objects you want to be able to load and save.
The floats must be in the u.s. format (e.g: 15.234).
The destination array must be preformatted. That means, if your file contains a Vector column and a Float Column, then the destination array (the owner of the building block theorically), should be compound of a Vector column and a Float Column.
You can append the file contents to your existing array or decide to replace all the existing values by the new ones...


Array Save BB

 Array Save
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Writes cells from an array to a text file.

Technical Information

In: triggers the process.

Out: is activated if the file is writen successfully.
Write Error: is activated if the file can't be written correctly.

File: name of the file containing the array to save. Must be in given as an absolute path.
First Column: indicates the column in your array where the saving process should start.
Number of Column: Number of columns (from the "First Column") you want to write in the file.
Append: TRUE if you want to append at the end of an already existing file (If the file doesn't exist, it will be created).

This building block, when attached to an array or when given an array as a target, writes the array to the given file, formatted in this style:

value	value	value
value	value	value
value	value	value etc...

See the Array Load BB to know how parameters, objects and native values will be written.


Bezier Interpolator BB

 Bezier Interpolator
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
OBSOLETE - see Bezier Progression BB.

Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of steps.

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Number of steps: number of steps in which the whole range will be covered.
Progression Curve: 2D Curve representing the progression of the output value.
Min: lower end of the range covered by the Bezier-interpolated value.
Max: higher end of the range covered by the Bezier-interpolated value.

Value: current Bezier-interpolated value.
Delta: subtraction between current Bezier-interpolated value and the previous one.

This building block can be used to transform a linear progression to a Bezier curve progression in the [Min,Max] range.

Warning

This building block is obsolete and is only included for backwards compatibility.


Bezier Progression BB

 Bezier Progression
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of milliseconds.
Bezier Progression.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Duration: how long the whole process should last.
or Number of Frames: number of steps in which the whole range is covered.
A: lower end of the range covered by the Bezier-interpolated value.
B: higher end of the range covered by the Bezier-interpolated value.
Progression Curve: 2D Curve representing the progression of the output value.

Elapsed Time: time elapsed since the start of the progression.
or Current Frame: current step of the progression.
Value: current Bezier-interpolated value.
Delta: subtraction between current Bezier-interpolated value and the previous one.
Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolates at the same time (in the same loop) a color value, a vector, a orientation or something like this.

Time Based: If checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.
Tip: Since the 'Progression' value is given as an output parameter, you can use it in the loop to interpolate the orientation of the object at the same time (with the 'Interpolator Orientation' building block for example).

This building block can be used to transform a linear progression to a Bezier curve progression in the [A,B] range.

See also: Linear Progression.

Warning

- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependent.
- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.
(for the 'Progression' output parameter)


Bezier Transform BB

 Bezier Transform
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Transform a float value into another float value according to a 2d bezier curve shape, and given boundaries.
Bezier Transform.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

X: input value.
Progression Curve: 2D curve representing the progression of Y value according to X value.
Boundaries: X boundaries and Y boundaries ruling the bezier transformation formula. Changing the "Use 4 Floats As Boundaries" setting, you can define those boundaries by filling a rectangle parameter, or by filling 4 float values.

Y: output value.

Use 4 Floats As Boundaries: If checked, 4 Float pIn will appear at the top of the building block, in order to let the user define the boundary values using 4 floats instead of 1 rectangle parameter.

The Bezier Transform building block is useful to convert a (float) value into another (float) value according to some progression curve shape.


Binary Memory BB

 Binary Memory
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Memorizes in a 'State Memory' whether the behavior was triggered by 'In 0' or 'In 1'.
Bool Event - Specific Bool Event - Binary Switch - Binary Memory.cmo

Technical Information

In 0: triggers the process.
In 1: triggers the process.

Out 0: is activated when the process was triggered by 'In 0'.
Out 1: is activated when the process was triggered by 'In 1'.

State: "True" if the building block is activated by 'In 0', "False" otherwise.
Memorizes in a 'State Memory' whether the behavior was triggered by 'In 0' or 'In 1'.
This building block can be used as a simplified 'Parameter Selector'.


Binary Switch BB

 Binary Switch
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Activates the appropriate output, according to a Boolean condition.
Bool Event - Specific Bool Event - Binary Switch - Binary Memory.cmo

Technical Information

In: triggers the process.

True: is activated when Condition=True.
False: is activated when Condition=False.

Condition: boolean value.

This building block acts just like the 'While' building block.


Bool Event BB

 Bool Event
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Detects a boolean value change.
Bool Event - Specific Bool Event - Binary Switch - Binary Memory.cmo

Technical Information

In: triggers the process.
Reset: resets the internal state memorized by the building block.
The internal state is then set to FALSE, and none of the output is activated.

Change Detected: is activated when 'Value' has changed (either from TRUE to FALSE, or from FALSE to TRUE).
No Change: is activated when 'Value' has remained unchanged.

Value: boolean value.

If the boolean value has changed since the last processing of the building block, the "Change Detected" output is activated, otherwise the "No Change" output is activated.

Warning

- after a "Restore Initial Condition" event, the inner state of the building block isn't reseted. The only way to reset the building block is to activate its "Reset" input.
- you can activate at same time "In" and "Reset" (the building block is then reset and the "In" input is activated).


Broadcast Message BB

 Broadcast Message
Version 2.00 - Virtools
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Sends a Message to every objects waiting for it.
Messages.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Message: message to broadcast.

You can bind data with your message simply by adding Input Parameters to the BroadcastMessage building block. These data can then be retrieved by using a "GetDataMessage" building block with the "WaitMessage" building block .
If an object from another scene was waiting for the message with a "Wait For Message" building block, the output of this building block will be activated when launching its scene (with no reset).
See also: WaitMessage, GetDataMessage.


Calculator BB

 Calculator
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Calculates the value of an arithmetic expression; 'a' stand for the first parameter, 'b' for the second, ...etc.
Calculator.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Expression: Arithmetic expression .
A: first value.
B: second value.
C: third value.
D: ...etc.

X: result.

You can add as many 'Input Parameters' as you want.
The first argument after 'Expression' will stand for 'a' in the arithmetic expression.
The second argument after 'Expression' will stand for 'b' in the arithmetic expression.
...etc.
You should note that whatever name the input param has, its associated letter will only be determined by its position (as described above).

Available FLOAT Operations:
Operation
Addition
Subtraction
Multiplication
Division
Sine
Tangent
Cosine
Absolute Value
Square Root
Arctangent
ArcSine
ArcCosine
Power
Natural Logarithme
Exponential
Modulus
         Syntax
+
-
*
/
Sin
Tan
Cos
Abs
Sqrt
Atan
Asin
Acos
^
Ln
Exp
\
         Example
a+5
b-c
-3.2+(7*b)
5/11.5
Sin(a*pi)
Tan(pi/4) ----> 1.0
5*Cos(0.2)
Abs(-3.8) ----> 3.8
Sin(pi/3)-Sqrt(3)/2
Atan(1) ----> pi/4
Asin(1) ----> 1.570...
Acos(0.5) ----> 1.04...
3^2 ----> 9
Ln(2.72)
Exp(1) ----> 2.72...
32\6 ----> 2

Available VECTOR Operations:
Operation
Addition
Subtraction
Dot Product
Division
Absolute Value
Cross Product
         Syntax
+
-
*
/
Abs
^
         Example
a+b ----> if a=[1,-2,3] & b=[-4,5,6] then x=[-3,3,9]
b-c ----> if b=[1,-2,3] & c=[-4,5,6] then x=[5,-7,-3]
a*b ----> if a=[3,1,0] & b=[-2,5,1] then x=-1
a/b ----> if a=[1,0,3] & b=[-4,2,6] then x=[-0.25,0,2]
Abs(a) ----> if a=[-1,5,-3] then x=[1,5,3]
a^b ----> if a=[1,0,0] & b=[0,1,0] then x=[0,0,1]

Available Constants:
Syntax
PI
         Associated Value
3.141592654...
         Example
5*Sin(pi)

Additionnal Technical Information:
- All Arithmetic Expressions are CASE-INSENSITIVE ; which means, "sin(pi/b)" = "SIN(PI/B)" = "Sin(Pi/b)" = "sIN(pI/B)"
- Priority between operation are managed ; which means / has a higher priority than +.
- The tree describing the combination of operations is created each time the Arithmetic Expression String change, but this tree isn't recreated if a parametric input change its value. It means that the 'Calculator' buiding block is in fact a very efficient way to compute mathematic operations (Where 'Parametric Operations' need time to create and compute mathematic combinations).
- For the moment the syntax [x,y,z] is not allowed. You can write V.x (the x component of V), but you can write in it (like [0,V.y,V.z]). Use 'Set Component' to rebuild your vector (or color...).
- Scientific number writing is allowed. It means 100000 can be written 1e5 (or 10e4), and 0.1 can be written 1e-1 (or 10e-2).

Warning

- All the 'input parameters' must be either FLOATS, VECTOR ANGLES, PERCENTAGE (except the very first one, which stand for the arithmetic STRING expression).
- If you create a non-FLOAT or non-VECTOR or non-ANGLE or non-PERCENTAGE 'input param', it will be transformed into a FLOAT one. Beware ... you'll have to set your value again !!!
- Important Warning: the Cross Product was wrong in the previous version (before Dev 2.1).
before: [1,0,0] ^ [0,1,0] = [0,0,-1]
now: [1,0,0] ^ [0,1,0] = [0,0,1]
If you had a old composition that use cross product in "Calculator" it will still work as before.
All new composition using cross product in "Calculator" will now work in correct order.
But beware, if you're working with an old composition that use cross product in "Calculator", and drag and drop a new "Calculator", there will be a conflict between old cross product and new cross product. You should then replace all the "Calculator" that use the cross product.


Change Value If BB

 Change Value If
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Get cells from an array, using the input parameter key and then replace it by the 4th input parameter's value.

Technical Information

In: triggers the process.

Found: is activated when matching cells are found in specified column.
Not Found: is activated if there's no matching cells in the column.

Column: index of the column in which your search will be done.
Operation: comparison operator used to compare the parsed values with the reference value.
(Reference Value): this input parameter is created when choosing the column and editing the building block.
It must contains the reference value for the test.
(New Value): Input parameter that will be created when choosing the column and editing the building block and that will contain the value to set in replacement of the matched one.

Number Changed: number of rows changed in the array.

This building block will go through the entire array and will change the values in the rows for which the comparison of given column value and reference value will be true. If it finds somes, it exits by the first input and write in its output parameter the number of rows it actually changed.


Check For Message BB

 Check For Message
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Check the message manager to see if a specific message has been received by the object.
Messages.cmo

Technical Information

In: triggers the building block process.

No Message: is activated until the message is received .
Message Arrived: is activated when the wanted message is received.

Message: message to wait for.

Message Count: number of time the message has been received in the same frame.

The output is activated only when the message has been received.

Warning

- This building block doesn't wait a message to be received, it check for at the current frame.
- Therefore, you need to loop this building block by using the 'No Message' output which is activate if the message doesn't arrived.


Chrono BB

 Chrono
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Chronometer (ON=Start, OFF=Stop).
Chrono - Counter - Delayer - Timer.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated when the "On" input is activated.
Exit Off: is activated when the "Off" input is activated.

Elapsed Time: current time elapsed since the building block has been activated by ON.

When activated by ON, the "Elapsed Time" output parameter is set to 0.

See also: "Delayer" BB, "Timer" BB.


Clear Array BB

 Clear Array
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Removes all the rows of the array.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

This building block removes all the rows of the given array.

Warning

- The columns aren't removed. There's simply no more rows.


Collection Iterator BB

 Collection Iterator
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Retrieves each element of a Collection.
Collection Iterator.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Collection: the Collection to parse.

Element: current parsed element of the Collection.
Index: index of the current element.


Column Product BB

 Column Product
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Performs the multiplication of all the cells of a column.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Column: the column from which the product must be calculated.

(Product Value): this output parameter will be created when choosing the column and editing the building block. The type of this parameter is choosen according to the type of the given column.

Warning

- This building block will only work on integer or float basic types, not the parameter versions.


Column Sum BB

 Column Sum
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Calculates the sum of all the elements of a column.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Column: the column from which the sum must be calculated.

(Sum Value): this output parameter will be created when choosing the column and editing the building block. The type of this parameter is choosen according to the type of the given column.

Warning

- This building block will only work on integer or float basic types, not the parameter versions.


Column Transform BB

 Column Transform
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Performs an operation between one column value and a operand and store the result in the column.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Column: index of the column to be transformed by the equation.
Operation: operation to perform between the column and the operand.
(Operand): this input parameter will be created when choosing the column and editing the building block. The type of this parameter is choosen according to the type of the given column.

Warning

- This building block can only be used with column containing integer or float basic types, not the parameter versions.


Columns Operation BB

 Column Operation
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Performs an operation between two columns and put the result in a third one.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Column 1: index of the first source column.
Operation: operation to perform between the two columns.
Column 2: index of the second source column.
Result Column: index of the column receiving the results (It can be one of the two source column) of the equation.

This building block performs the operation array[rc][i] = array[c1][i] (op) array[c2][i] for every i going from 0 to (number of rows-1) in the array. The operation will only work on FLOAT and INTEGER values.

Warning

- The operation will only work on integer or float basic types, not the parameter versions.


Counter BB

 Counter
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Exits 'MaxCount' times by the 'Looping' output and when finished, exits by 'Out' output.
Chrono - Counter - Delayer - Timer.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Max Count: number of steps in the count loop.
Start index: index at which the counter will start (by default 1).
Step: number to add to the counter at each loop (by default 1).

CurrentCount: current step in the count loop.

Use this to execute a task 'Maxcount' times.
The "In" input resets the current count to 0.


Create Group From Array BB

 Create Group From Array
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Creates a group with entities cells matching the given value.

Technical Information

In: triggers the process.

Created: is activated when matching cells have been found.
No Elements Found: is activated when no matching cells have been found in the array.

Entities Column: column in which the entities (BeObject) are taken.
Search Column: index of the column in which your search will be done.
Operator: comparison operator that will be used to compare the array value with the reference value.
(Reference Value): this output parameter will be created when choosing the column and editing the building block. The type of this parameter is choosen according to the type of the given column.

Group: created group, which contains all the entities matching the value comparison.

Remarks

The column containing the entities must be in the Object basic type, not one of the parameter type representing a class of object.


Create String BB

 Create String
Categorized in Logics/Strings

Description

Apply to a BEOBJECT.
Creates a string by concatenating elements, separating them with an optional delimiter.
Create String - Input String - Reverse String.cmo

Technical Information

Create: creates the string by reading the inputs parameters.
Add Line: adds to the currently created string a new line by reading the inputs parameters.
Clear: clears the currently created string.

Out: is activated when the process is completed.

Delimiter: the delimiter character or string to insert between given elements.

(Format): This setting(s) will be created as you add input parameters : they let you modify the way your parameter will be displayed in the string. the format looks like %[flags] [width] [.precision] [{h | l | I64 | L}]type.

Type:
The type character is the only required format field ; it appears after any optional format fields. The type character determines whether the associated argument is interpreted as a character, string, or number. The types C and S, and the behavior of c and s with printf functions, are Microsoft extensions and are not ANSI-compatible.

Character | Type | Output Format
c | int or wint_t | When used with printf functions, specifies a single-byte character; when used with wprintf functions, specifies a wide character.
C | int or wint_t | When used with printf functions, specifies a wide character; when used with wprintf functions, specifies a single-byte character.
d | int | Signed decimal integer.
i | int | Signed decimal integer.
o | int | Unsigned octal integer.
u | int | Unsigned decimal integer.
x | int | Unsigned hexadecimal integer, using “abcdef.”
X | int | Unsigned hexadecimal integer, using “ABCDEF.”
e | double | Signed value having the form [ – ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or –.
E | double | Identical to the e format except that E rather than e introduces the exponent.
f | double | Signed value having the form [ – ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
g | double | Signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than –4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
G | double | Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate).
n | Pointer to integer | Number of characters successfully written so far to the stream or buffer; this value is stored in the integer whose address is given as the argument.
p | Pointer to void | Prints the address pointed to by the argument in the form xxxx:yyyy where xxxx is the segment and yyyy is the offset, and the digits x and y are uppercase hexadecimal digits.
s | String | When used with printf functions, specifies a single-byte–character string; when used with wprintf functions, specifies a wide-character string. Characters are printed up to the first null character or until the precision value is reached.
S | String | When used with printf functions, specifies a wide-character string; when used with wprintf functions, specifies a single-byte–character string. Characters are printed up to the first null character or until the precision value is reached.

Flag:

flag | Meaning | Default
- | Left align the result within the given field width. | Right align.
+ | Prefix the output value with a sign (+ or –) if the output value is of a signed type. | Sign appears only for negative signed values (–).
0 | If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and – appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored. | No padding.
blank(' ') | Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear. | No blank appears.
# | When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. | No blank appears.
 | When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. | Decimal point appears only if digits follow it.
 | When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Ignored when used with c, d, i, u, or s. | Decimal point appears only if digits follow it. Trailing zeros are truncated.

Width:

The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values — depending on whether the – flag (for left alignment) is specified — until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).

The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the Precision specification described below).

If the width specification is an asterisk (*), an int argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. A nonexistent or small field width does not cause the truncation of a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.

Precision:

The third optional field of the format specification is the precision specification. It specifies a non-negative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits (see the table below). Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output, as shown below:

printf( "%.0d", 0 );      /* No characters output */

If the precision specification is an asterisk (*), an int argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list.

Type | Meaning | Default
c, C | The precision has no effect. | Character is printed.
d, i, u, o, x, X | The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. | Default precision is 1.
e, E | The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. | Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed.
f | The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. | Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.
g, G | The precision specifies the maximum number of significant digits printed. | Six significant digits are printed, with any trailing zeros truncated.
s, S | The precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed. | Characters are printed until a null character is encountered.

Part of this documention is (C) Microsoft Corporation.

Example:

-To print a float with 2 decimals : %.2f
-To print an integer of any size left aligned in 6 spaces : %-6d

Text: the created string.

You can add as many Input Parameters as you want (of any type !).


Delayer BB

 Delayer
Version 2.00 - Virtools
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Waits for a given time to elapse using internal looping.
Chrono - Counter - Delayer - Timer.cmo

Technical Information

In: triggers the process
Out: is activated when the time is elapsed.

Time to Wait: time to wait.
Elapsed Time: time elapsed.

This building block stay internally activated until the given lapse is finished. It just delay the activation of its output.

See Also: "Timer" BB and "Chrono" BB..


Enter Critical Section BB

 Enter Critical Section
Categorized in Logics/Synchro

Description

Apply to a BEOBJECT.
Makes the object enter a critical section.
Enter - Leave Critical Section.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Critical Section: the critical section name.

The output is activated only when the object has entered the critical section. Critical sections can be accessed by only one object at a time. Therefore the building block will be blocked until the critical section becomes free again.

Warning

- If you use a target pIn for the "Enter Critical Section" BB, be sure NOT TO MODIFY this target if the "Enter Critical Section" BB is activated. You should only change the target (if you need to do so) only before entering by "In" input, or after exiting by "Out" output... But never while the building block is internally looping.


FIFO BB

 FIFO
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
First In First Out - stores a sequence of activated inputs, and play it back.
FIFO.cmo

Technical Information

Unstack: activates the next output corresponding to the next index in the stored sequence.
In 1: Input signals to be managed (only if the 'Reset' has been activated).
In 2: Input signals to be managed (only if the 'Reset' has been activated).
...
In N: Input signals to be managed (only if the 'Reset' has been activated).

Out Unstack: is activated when the Unstack input has been activated.
Out 1: Output signals to be managed (only if signals 'In 1' succeed in crossing the building block).
...

Stack Size: max number of input activation the building block can record.

When the 'Unstack' signal occurs, the first signal, stored in the FIFO list, is managed and is deleted from the FIFO list, and the corresponding output is activated.
If 'Unstack' is activated once again, the second signal is managed. In fact, this building block repeats the sequence you play, step by step.
You can add as many inputs as needed (number of outputs will automatically be equal to the number of inputs).
Note also, there's a priority order from up to down if 2 signals occures at same time.
If you ever need to change the maximum size of Stack, go to the building block settings...

For an example, load the composition "Technical Samples\Logics\Fifo.cmo".

Example

To unstack an undefined number of step, here is an example:

Assuming the sequence used In 1 and In 2,

the start of unstack activates the last input of Fifo, and will be used as an "End sequence" marker, and resets the Priority,
then FIFO loops through the Priority, unstack the stored sequence,
then when the stored sequence is finished, the "End sequence" marker activate the last input of Priority,
thus stoping the loop, and activating the last output of priority to indicate the end of the loop.

Warning

Assuming the stack size is 8, a sequence of 8 signals has been stored, and 5 signals has been played (Unstack has been activated 5 times): if you stop unstacking and begin to play another sequence, you just have 5 signals available for storing.

Related building block : LIFO


Fill Group By Class BB

 Fill Group By Class
Categorized in Logics/Groups

Description

Apply to a GROUP.
Add all objects of a given type to the group.
Group Clear - Fill Group By Class - Get Nearest In Group.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Class: type of objects you want in the group.
Derived Class: if you want the objects of derived type to be added in the group too.
eg: - lets say Type=3DEntity, and Derived=TRUE, then 3DEntities and 3DObjects will be added to the group.
- if Type=3DEntity, and Derived=FALSE, then 3Dentities will be added to the group, but not the 3DObjects.
Only In Current Scene: if TRUE, the building block will only parse the objects of the current scene. Otherwise, all the objects of the entire level (with the given type) will be parsed.
See also: Add To Group, Remove From Group.


Get Cell BB

 Get Cell
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets the cell of a chosen row and column.

Technical Information

In: triggers the process.

Found: is activated if the given cell index exists.
Not Found: is activated if the given cell doesn't exist.

Row Index: the index of the row from which the cell must be returned.
Column Index: the column of the row from which the cell must be returned.

Cell Value: The cell of the row found. You need to change the type of this parameter according to the type of the column you will have at runtime.

Remarks

This BB does not update its output parameter type automatically when edited as the "Get Row" BB because it is designed to work with array builded at runtime with BB such as "Insert Column".


Get Column Name BB

 Get Column Name
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets the name of a column.

Technical Information

In: triggers the process.

Out: is activated when the process is completed.

Column Index: the index of the column from which the name must be returned.

Column Name: the name of the column.


Get Component BB

 Get Component
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Extracts the components of a COLOR, VECTOR or 2dVECTOR.
Get - Set Component.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Variable: the COLOR, VECTOR, EULER ANGLES, VECTOR 2D, RECTANGLE, BOUNDING BOX or STRUCTURE you want the component to be extract from.

Component 1: the first component (float).
Component 2: the second component (float).
Component 3: the third component (float).

Rectangle/Box Mode: if the input parameter type is a RECTANGLE or a BOX, then this settings define how the informations will be returned (center/half-size ... top,left corner/ bottom/right corner ... or top,left corner/size).

This building block retrieves all components of either a COLCOLOR, VECTOR, EULER ANGLES, VECTOR 2D, RECTANGLE, BOUNDING BOX or STRUCTURE.
eg: Say 'Variable' is a vector and is equal to [8,3,5].
Then, 'Component 1'=8.
and , 'Component 2'=3.
and , 'Component 3'=5.

If you change the type of 'Variable', then (if needed) the number of output parameters will be changed automatically.

Note: when you set the "Variable" pIn to a STRUCTURE, the pOuts are created to match the structure parameters.

See Also: SetComponent.

Warning

- COLOR componants are to be get from 0.0 to 1.0 (so it'll much easier for you to process calculs). Therefore, [1,1,1]=white and [1,0,0]=red.


Get Delta Time BB

 Get Delta Time
Version 2.00 - Virtools
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Returns the elapsed time between the previous and the current Behavioral Process.
Time.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Delta Time: elapsed time between two behavioral process.

Warning

- previous versions of this building block used a INTEGER type for the output value... now it's a TIME (i.e. a float).


Get Highest BB

 Get Highest
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets the cells of an array, which value in the given column is the highest.

Technical Information

In: triggers the process.

Found: is activated when an highest element is found in the array.
Not Found: is activated when an highest element is not found.

Column: the column in which the highest value must be searched.

Row Number: the index of the row in which the cell has been found.
(Element Values): all the cells of the row found are written in these subsequent output parameters.

Remarks

As with the "Sort Rows" BB, only base types INTEGER, FLOAT and STRING are fully supported by this BB. Other types may lead to undefined behavior. See the "Sort Rows" documentation for more reference on this.


Get Key Row BB

 Get Key Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets cells from an array, using the key column as a search criterion on the given key value.

Technical Information

In: triggers the process.

Found: is activated when a matching row is found in the array.
Not Found: is activated when a matching row is not found in the array.

(Key Value): input parameter that will be created when choosing the target array and editing the building block and that will contain the value to search in the key column.

(Element Values): all the cells of the found row are written in these subsequent output parameters.

Warning

- If you change the target array dynamically, make sure it has the same format as the one given in author mode. (The output parameters are only created in author mode, when editing the building block.)


Get Lowest BB

 Get Lowest
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets the cells of an array, which value in the given column is the lowest.

Technical Information

In: triggers the process.

Found: is activated when a lowest element is found in the array.
Not Found: is activated when a lowest element is not found.

Column: the column in which the lowest value must be searched.

Row Number: the index of the row in which the cell has been found.
(Element Values): all the cells of the row found are written in these subsequent output parameters.

Remarks

As with the "Sort Rows" BB, only base types INTEGER, FLOAT and STRING are fully supported by this BB. Other types may lead to undefined behavior. See the "Sort Rows" documentation for more reference on this.


Get Message Data BB

 Get Message Data
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Reads the data bound with the selected message.
Messages.cmo

Technical Information

In: triggers the process (and reset message parsing loop).
Next Data: ask for the next event when more than one event occures at the same behavioral frame.

Out: is activated when the process is completed.
Data Received: is activated each time the message is received.

Message: message with which the datas are bound.
Sender: object which sent the message.

This building block should be linked to the output of the 'WaitMessage' (or similar BB), with a link delay=0.
Simply add Output Parameters of the same type and in the same order as the Input Parameters of the corresponding SendMessage BB.

This building block is useful when it isn't possible to share parameter between two scripts.
However, with shortcut parameters (Ctrl C ... Ctrl+Shift V), you can pass parameters from one script to another, but it's still useful if you use Dev intending to make your own player with different levels, and try to share informations between them... (like the score, or the found bonus, or the name of the new level to load). This communication can be done with messages sent to the level.

If more than one message is received, "Data Received" output is activated once; then if you enter by "Next Data" input (by linking "Data Received" to "Next Data" input with a 0 link delay), you'll get the second message.
Since many messages can occur at same time, this feature is very useful.

See also: Send Message, Wait Message, Send Message To Group, Check For Message.

Warning

- You have to link this building block with a link delay=0, to "Wait Message" (or a similar behavior).


Get Nearest BB

 Get Nearest
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets the cell of an array, which value in the given column is the nearest from the reference value.

Technical Information

In: triggers the process.

Found: is activated when a nearest element is found in the array.
Not Found: is activated when a nearest element is not found.

Column: the column in which the Nearest value must be searched.
(Reference Value): input parameter that will be created when choosing the column and editing the building block and that will contain the reference value to test.

Row Number: the index of the row in which the cell has been found.
(Element Values): all the cells of the row found are written in these subsequent output parameters.

Remarks

As with the "Sort Rows" BB, only base types INTEGER, FLOAT and STRING are fully supported by this BB. Other types may lead to undefined behavior. See the "Sort Rows" documentation for more reference on this.

Warning

- If you change the target array dynamically, make sure it has the same format as the one given in author mode. (The output parameters are only created in author mode, when editing the building block.)


Get Nearest In Group BB

 Get Nearest In Group
Categorized in Logics/Groups

Description

Apply to a BEOBJECT.
Get the nearest object in the selected group from the given position.
Group Clear - Fill Group By Class - Get Nearest In Group.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Group: name of the group in which to search.
Position: vector expressed in cartesian coordinates.
Referential: coordinate system in which the position is expressed.

Nearest Object: nearest object from the owner. It can't be the same than the given referential.
Distance: distance to the nearest object.

Warning

- as many other distances given in Virtools, the distance here is the distance between the two objects basis.


Get Row BB

 Get Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Gets the cells of a chosen row.

Technical Information

In: triggers the process.

Found: is activated if the given row index exists.
Not Found: is activated if the given row index doesn't exist.

Row Index: the index of the row from which the cells must be returned.

(Element Values): all the cells of the row found are written in these subsequent output parameters.

Warning

- If you change the target array dynamically, make sure it has the same format as the one given in author mode. (The output parameters are only created in author mode, when editing the building block.)


Get SubString BB

 Get SubString
Categorized in Logics/Strings

Description

Apply to a BEOBJECT.
Returns part of a string.
Load String - Scan String - Get SubString.cmo

Technical Information

In: activates the process.
Out: activates when the process has completed.

String: the string to manipulate.
Start: the position of the first character; note that numbering starts at 0.
Length: the length of the substring to copy. 0 means the whole string.

SubString: the name of the new string (the sub-string you create).


Group Clear BB

 Group Clear
Categorized in Logics/Groups

Description

Apply to a GROUP.
Remove all the elements of a group.
Group Clear - Fill Group By Class - Get Nearest In Group.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

See also: Add To Group, Remove From Group.


Group Iterator BB

 Group Iterator
Categorized in Logics/Groups

Description

Apply to a BEOBJECT.
Retrieves each element of a group.
Group Iterator - Add To Group - Remove From Group - Is In Group.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Group: the group to parse.

Element: current parsed element of the group.
Index: index of the current element.

This building block is useful in many situations. Suppose you want to change the diffuse color of several materials. As the "Set Diffuse" building block is targetable, you just have to put all the materials you want the color to be changed in a group, and parse all the elements (materials) of this group, and link the "Loop Out" output to the "Set Diffuse" building block. The retrieved "Element" will be the current parsed material, and have to be used (linked) as the Target of the "Set Diffuse" building block.
But this building block is also useful to find a specifique information amoung a group. For instance, which material use the texture T ? Or which is the strongest ennemy amoung them all ? (supposing they have a Ennemy attribut, for example).

eg:

See also: Add To Group, Remove From Group.

Warning

- Beware, each if you explicitly put a link delay of 1 for looping link, this will mean you want to wait 1 behavioral frame each time you parse a material. In most case, a link delay of 0 for the looping link must be used.


Group Operator BB

 Group Operator
Categorized in Logics/Groups

Description

Apply to a GROUP.
Makes combination of groups and objects wearing attributes.
Attributes - Group Operator.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Operator: the Set Operator.
Group or Attribute: the set you want to operate the current group with. An attribute describe the set of all the objects of the current scene wearing this attribute.
You can change this input parameter to a Group.

Available operations are UNION, INTERSECTION and SUBTRACTION.

See also: Add To Group, Remove From Group.


Has Attribute BB

 Has Attribute
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
Gets the parameter of an attribute (if it exists) on the given object.
Attributes - Group Operator.cmo

Technical Information

In: triggers the process.

True: is activated if the object has the given attribute.
False: is activated if the object has not the given attribute.

Object: the object that should have or not the attribute. NULL means owner
Attribute: the type of attribute to test.

Attribute Value: if the "True" output is activated, this output parameter contains the value of the attribute.

- If the specified type "Attribute" has no parameter value then the output parameter "Attribute Value" is desabled.


Has Attribute Obsolete BB

 Has Attribute Obsolete
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
OBSOLETE - see Has Attribute BB.

Gets the parameter of an attribute (if it exists) on the given object.

Technical Information

In: triggers the process.

True: is activated if the object has the given attribute.
False: is activated if the object has not the given attribute.

Object: the object that should have or not the attribute. NULL means owner
Attribute: the type of attribute to test.

Attribute Value: if the "True" output is activated, this output parameter contains the value of the attribute.

- If the specified type "Attribute" has no parameter value then the output parameter "Attribute Value" is desabled.

Warning

This building block is obsolete and is only included for backwards compatibility.


Hierarchy Parser BB

 Hierarchy Parser
Categorized in Logics/Loops

Description

Apply to a 3DENTITY.
Iterates recursively on an object and all its children.
Hierarchy Parser.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Max Recursivity: Maximum depth of childhood covered. 0 means infinite.

Current: Current object parsed.
Depth: Depth of the current object (0 means the root, 1 a direct child of the root, etc.)


IBCQ BB

 IBCQ
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Incremental Bezier Curve Query: Interpolates a float according to a 2D Bezier curve in the [0,1] range.
IBCQ.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Delta_In: linear progression step in the [0%, 100%] range. (if Delta=1%, there will be 100 steps in the progression).
Progression Curve: 2D Curve representing the progression of the 3D Entity along its movement.

Delta_Out: current Bezier-interpolated Delta value (PERCENTAGE).
Value: current Bezier-interpolated value (PERCENTAGE).
Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolate at the same time (in the same loop) a color value, a vector, a orientation or something like this.

This building block can be used to transform a linear progression to a Bezier curve progression. Useful to simulate acceleration on a movement.

See also: Bezier Interpolator, Time Bezier Interpolator, Bezier Interpolator.

Warning

- Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.


Identity BB

 Identity
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Outputs the Input Parameter(s) when activated.
ParamOp.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block is usefull to put a value into a local parameter, at runtime.
Other ways to perform that kind of thing is to use a "Parameter Selector" building block.
Sometimes, using a Parameter Operation in conjunction with the "Identity" building block can be replaced with a single "Op" building block.
You can add as many Inputs Parameters as you want ( from any type ), the Output Parameters will be added automtically.


Insert Column BB

 Insert Column
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Inserts a column in the array.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Index: index of the new column (next columns will be automatically shift).
Column Name: name to be given to the new column.
Column Type: type of the new column (Integer, Float, String, Object, Parameter).
Parameter Type: type of the parameter to create (used only to know which type of parameter has to be used if Column Type is "Parameter").

Remarks

- If you specify -1 for the Index, the column will be append after all the existing columns.
- The Parameter Type input parameter is taken into consideration only if Column Type is "Parameter". Otherwise, it's useless.
- The "Insert Column" isn't supposed to be used in combination with BB such as "Iterator" or "Add Row" BB. Because the Iterator BB (as many other array BB) dynamically change its outputs/inputs when they are edited (right-click + Edit Building Block), to match the column numbers and types. If you add a column to your array after having the "Iterator" BB edited, the "Iterator" BB won't be aware of this change, and its outputs/inputs won't be updated.
Thus the "Insert Column" BB should be used instead with a "Get Cell" and "Set Cell" BB.


Interpolator BB

 Interpolator
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
Performs an interpolation between 2 parameters
Interpolator.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first value.
B: second value.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated value.

Use HSV Interpolation for Color: if you want to perform an HSV Color interpolation, set the type of "C" output parameter to COLOR, and set the boolean value of this setting parameter to TRUE.

This building block performs an interpolation between A and B, and put the result into C.
If Value=0% then C=A, if Value=100% then C=B.
This building block is a generic building block which can perform several kind of interpolation:
- FLOAT interpolation
- VECTOR2D interpolation
- VECTOR interpolation
- INTEGER interpolation
- MATRIX interpolation
- QUATERNION interpolation
- EULER ANGLES interpolation
- COLOR interpolation
- HSV COLOR interpolation
- RECTANGLE interpolation
To use this building block as a Vector Interpolator, just change the type of the output parameter "C" (the type of the input parameters will be changed automatically).


Interpolator Color BB

 Interpolator Color
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
OBSOLETE - replaced by Interpolator BB.

Performs a linear interpolation between 2 colors.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first color.
B: second color.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated color.

If Value=0% then C=A, if Value=100% then C=B.

Warning

This building block is obsolete and is only included for backwards compatibility.


Interpolator Float BB

 Interpolator Float
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
OBSOLETE - see Interpolator BB.

Performs a linear interpolation between 2 floats.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first float.
B: second float.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated float.

If Value=0% then C=A, if Value=100% then C=B.

Warning

This building block is obsolete and is only included for backwards compatibility.


Interpolator HSV Color BB

 Interpolator HSV Color
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
OBSOLETE - see Interpolator BB.

Interpolates a color Using HSV color Model

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first color.
B: second color.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated color.

If Value=0% then C=A, if Value=100% then C=B.
HSV Interpolation should be better in most case than classic Color Interpolations, because you can for example interpolate colors without modifying the Luminosity, or Saturation of your color.

Warning

This building block is obsolete and is only included for backwards compatibility.


Interpolator Int BB

 Interpolator Int
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
OBSOLETE - see Interpolator BB.

Performs an interpolation between 2 integers.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first int.
B: second int.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated int.

If Value=0% then C=A, if Value=100% then C=B.

Warning

This building block is obsolete and is only included for backwards compatibility.


Interpolator Matrix BB

 Interpolator Matrix
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
OBSOLETE - see Interpolator BB.

Performs a linear interpolation between matrices.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first matrix.
B: second matrix.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated matrix.

This building block interpolates the orientation information stored inside the two given matrices, as well as the scale.
If Value=0% then C=A, if Value=100% then C=B.

- This building block perform a quaternion slerp, and a scaling interpolation. Therefore, you might find it a bit slow for a massive use (see "Set Orientation", "Look At", and "Interpolate Orientation" building blocks).
- Beware to use a LEFT-HAND oriented basis for your object. Interpolation will not work correctly if the basis of your object if RIGHT-HAND oriented.

Warning

This building block is obsolete and is only included for backwards compatibility.


Interpolator Object Orientation BB

 Interpolator Object Orientation
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
Performs an interpolation between orientations of two given 3D Entity.
Interpolator.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first 3D Entity which matrix will be taken.
B: second 3D Entity which matrix will be taken.
Value: value to be taken between A and B ( 0% means A, 100% means B ).
Scale: the resulted normalized matrix is multiply with this scale value (useful if the object receiving this matrix has a non-unitary scale). This parameter is used and visible only if the setting 'Objects are all 1x1x1 scaled' is set to TRUE.

C: interpolated matrix.

Objects are all 1x1x1 scaled: if set to TRUE, then no scale calculation is performed, and process time is saved. You should set this parameter to TRUE if you know all your objects to be 1x1x1 scaled.

If Value=0% then C=A matrix, if Value=100% then C=B matrix.


Interpolator Vector BB

 Interpolator Vector
Categorized in Logics/Interpolator

Description

Apply to a BEOBJECT.
OBSOLETE - Interpolator BB.

Performs a linear interpolation between 2 vectors.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

A: first vector.
B: second vector.
Value: value to be taken between A and B ( 0% means A, 100% means B ).

C: interpolated vector.

The interpolation is performed on each coordinate.
If Value=0% then C=A, if Value=100% then C=B.

Warning

This building block is obsolete and is only included for backwards compatibility.


Is In Group BB

 Is In Group
Categorized in Logics/Groups

Description

Apply to a BEOBJECT.
Check if the object is in a specific group.
Group Iterator - Add To Group - Remove From Group - Is In Group.cmo

Technical Information

In: triggers the process.

True: is activated if the Behavioral Object is in the given group.
False: is activated if the Behavioral Object is not in the given group.

Object: object to be tested.
Group: the group.

This building block checks weither an object is in a group or not.

See also: Add To Group, Remove From Group.


Is In View Frustum BB

 Is In View Frustum
Version 2.00 - Virtools
Categorized in Logics/Test

Description

Apply to a BEOBJECT.
Tests if the object is in the viewing frustrum of the active camera.
Is In View Frustum.cmo

Technical Information

In: triggers the process.

Inside: is activated if the bounding box of the object is in the view frustum.
Outside: is activated if the bounding box of the object is not in the view frustum.

Object: the entity used for the test (can be a 2D or 3D entity).
Test Hierarchy: if this boolean is set to true, all the children of the object will be tested too (worth only for 3D entities).

Extents: rectangle containing the screen extents of the object.
Fully Inside: TRUE if the object is fully inside the frustum, FALSE otherwise.

This building block will consider 3D Frames like punctual objects, even if their interface meshes are displayed.
The viewing frustum is a 3D Volume in a scene positionned relatively to the viewport's camera. For perspective viewing, the camera is positioned at the tip of an imaginary pyramid. This pyramid is intersected by two clipping planes, the front plane and the far plane. The Volume in the pyramid between the front and the back clipping planes is the viewing frustum. Only objects in the viewing frustum are visible.


Iterator BB

 Iterator
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Iterate on each row of an array and return the values of the current row.

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Starting Row: index of the row where iteration should start.
Ending Row: index of the row where iteration should stop (inclusive). -1 means the last row.
Backward: specfifies the direction of theiteration:FALSE=normal,TRUE=backward.

Row Index: index of the current parsed row.
(Element Values): all the cells of the current row are written in these subsequent output parameters.

Warning

- If you change the target array dynamically, make sure it has the same format as the one given in author mode (The output parameters are only created in author mode, when editing the building block).


Iterator If BB

 Iterator If
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Iterates on each row matching a value and return the values of them.

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Column: column in which your search will be done.
Operator: comparison operator that will be use to compare the column values with the reference value.
(Reference Value): this input parameter will be created when choosing the column and editing the building block. The type of this parameter is choosen according to the type of the given column.

Row Index: index of the current parsed row.
(Element Values): all the cells of the current parsed row are written in these subsequent output parameters.

Warning

- If you change the target array dynamically, make sure it has the same format as the one given in author mode (The output parameters are only created in author mode, when editing the building block).


Keep Active BB

 Keep Active
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Keeps streaming activated even if inputs has been activate only once.
Keep Active.cmo

Technical Information

Reset: resets the building block to its initial state (deactivates all inputs).
In 1: Input signals to be memorised.
...

OutReset: is activated when the building block has been reset.
Out 1: Constante output signal corresponding to the input memorised signal.
...

One at a time: specify whether several outputs can be activated simultaneously, or not. If only one output can be activated, then it is the one corresponding to the last activated input.

This building block memorizes the input streaming(s), and activate outputs at each frame, even if the input signal(s) stops.

Warning

- you can add as many Inputs as you want, the corresponding Outputs will be added automatically.
- if two inputs are activated at same time, AND the "One at a time" setting is set to TRUE, then only the highest input is taken into account.


Leave Critical Section BB

 Leave Critical Section
Categorized in Logics/Synchro

Description

Apply to a BEOBJECT.
Makes the attached object leave the critical section.
Enter - Leave Critical Section.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Critical Section: the critical section name.

When the object leaves the Critical Section, the Critical Section becomes accessible for the others. Only one object can be in the Critical Section at the same time.


LIFO BB

 LIFO
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Last In First Out - stores a sequence of activated inputs, and play it back in inverted order.
LIFO.cmo

Technical Information

Unstack: activates the next output corresponding to the next index in the inverted stored sequence.
In 1: Input signals to be managed (only if the 'Reset' has been activated).
In 2: Input signals to be managed (only if the 'Reset' has been activated).
...
In N: Input signals to be managed (only if the 'Reset' has been activated).

Out Unstack: is activated when the Unstack input has been activated.
Out 1: Output signals to be managed (only if signals 'In 1' succeed in crossing the behavior).
...

Stack Size: max number of input activation the building block can record.

When the 'Unstack' signal occurs, the last signal, stored in the LIFO list, is managed and is deleted from the LIFO list. If 'Unstack' is activated once again, the ante-last signal is managed. Actually , this behavior repeats the sequence you play in the inverted order, step by step.
You can add as many inputs as needed (number of outputs will automatically be equal to the number of inputs).
Note also there's a priority order from up to down if 2 signals occur at same time.
If you ever need to change the maximum size of Stack, go to the building block settings...

For example load the LIFO.CMO in technical sample.

Related building block : FIFO


Linear Progression BB

 Linear Progression
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Increments from 'Start Value' to 'End Value' in 'Number of Steps' steps.
Interpolator.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Duration: how long the whole process should last.
or Number of Frames: number of steps in which the whole range is covered.
A: First value of the progression.
B: Last value of the progression.

Elapsed Time: time elapsed since the start of the progression.
or Current Frame: current step of the progression.
Value: current interpolated value.
Delta: subtraction between current value and the last one.
Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolate at the same time (in the same loop) another parameter such as a color value, a vector, an orientation,....

Time Based: if checked, this building block will be Time and not Frame Rate dependent. Making this building block Time dependent has the advantage that compositions will run at the same rate on all computer configurations.
Tip: Since the 'Progression' value is given as an output parameter, you can use it in the loop to interpolate the orientation of the object at the same time (with the 'Interpolator Orientation' building block for example).

This building block is ideal for linear progressions.
The "In" input resets the current step to 0.

See also: Bezier Progression.

Warning

- If Number of Steps= 5, Loop Out will be activated 5 time, but as you enter by In at beginning, you'll then enter 1 + 5 time into the building block; that's why at the end of last loop, current step will be equal to 6.
- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally lapse of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frames link delay, the process will become frame dependent.
- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.
(for the 'Progression' output parameter)


Load String BB

 Load String
Categorized in Logics/Strings

Description

Apply to a BEOBJECT.
Loads a string from a file.
Load String - Scan String - Get SubString.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.
File Error: activates if there is any sort of error, i.e. if the string contained in File could not successfully be loaded.

File: name of the file containing the string to load. Must be given as an absolute path or relative to the .cmo or the .exe.

String: the loaded string.

Note that in the event of a File Error, the last successfully loaded String is the value stored in String. If Load String has not yet successfully processed, then there is no value for String.


Make Rows Unique BB

 Make Rows Unique
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Ensures the uniqueness of the cells of a column.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Column: index of the column where duplicated values are to be searched.

This building block will delete all the rows containing a value in the given column that has already been parsed. But you should sort your array before calling this bulding block, because rows are deleted only if they follow each other. Thus, if you want to have only one row of a value in your array, you need to first sort the array on this column, then apply a unique on the same column.

Warning

- Do not forget to sort your array before calling this building block (see "Sort Rows" building block).


Mini Calculator BB

 Mini Calculator
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Processes a simple operation (+,-,*,/) between 'a' and 'b'
Mini Calculator - Modify Component - Random - Threshold - Nop.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Operator: operator string (among '+', '-', '*', '/').
A: first value.
B: second value.

X: result of the operation.

The supported operations (given as a string of characters) are '+' '-' '*' '/'.
See also, enhanced version with "Calculator".

Warning

- The only supproted type is FLOAT (and all the derived type like ANGLE and PERCENTAGE).
- It is now easy and more natural to use the "Op" building block.


Modify Component BB

 Modify Component
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Composes a 2dVector, Box, Color, Quaternion, Rectangle or Vector, by specifying none, one or several of its components.
Mini Calculator - Modify Component - Random - Threshold - Nop.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Vin: the original input (Vector by default). You can modify its type with those available (2dVector, Box, Color, Quaternion, Rectangle or Vector). The settings change according to the type of the original input, as well as the number of components and their types.
Created : one of the original input's component (float for a Vector). Edit the settings to choose which component you want edited.

Vout: the composed 2dVector, Box, Color, Quaternion, Rectangle or Vector.

  • Settings in 2dVector mode :
    Modify X:     check to modify the X (float) component of the 2dVector Input.
    Modify Y: check to modify the Y (float) component of the 2dVector Input..
  • Settings in Box mode :
    Modify Min: check to modify the Min (Vector) component of the Box Input.
    Modify Max: check to modify the Max (Vector) component of the Box Input..
  • Settings in Color mode :
    Modify R: check to modify the R(float) component of the Color Input.
    Modify G: check to modify the G (float) component of the ColorInput..
    Modify B: check to modify the B (float) component of the Color Input.
    Modify Alpha: check to modify the Alpha (float) component of the Color Input..
  • Settings in Quaternion mode :
    Modify X: check to modify the X (float) component of the Quaternion Input.
    Modify Y: check to modify the Y (float) component of the Quaternion Input..
    Modify Z: check to modify the Z (float) component of the Quaternion Input.
    Modify W: check to modify the W (float) component of the Quaternion Input..
  • Settings in Rectangle mode :
    Modify TopLeft: check to modify the TopLeft (2dVector) component of the Rectangle Input.
    Modify BottomRight: check to modify the BottomRight (2dVector) component of the Rectangle Input..
  • Settings in Vector mode :
    Modify X: check to modify the X (float) component of the Vector Input.
    Modify Y: check to modify the Y (float) component of the Vector Input..
    Modify Z: check to modify the Z (float) component of the Vector Input.

This building block composes either a 2dVector, Box, Color, Quaternion, Rectangle or Vector from none/some of their components.
eg: Say 'Variable' is a Vector (2,2,2).
In the settings, chek "Modify X"
Set X value with (0)
Then 'Vout'=[0,2,2].

If you change the type of 'Vin', all settings are reseted and all automatically added parameters input are destroyed.

See Also: Get Component, Set Component.

Warning

- COLOR components are to be get from 0.0 to 1.0 (so it'll much easier for you to process calculs). Therefore, [1,1,1]=white and [1,0,0]=red.


Move Column BB

 Move Column
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Moves a column of the array.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Src Column: index of the column to move.
Dest Column: index of the column to insert before. -1 means the Src Column will be inserted after all the columns.

Warning

- The "Move Column" isn't supposed to be used in combination with BB such as Iterator BB. Because the Iterator BB (as many other array BB) dynamically change its outputs/inputs when they are edited (right-click + Edit Building Block), to match the column numbers and types.
If you remove dynamically a column to your array after having the "Iterator" BB edited, the "Iterator" BB won't be aware of this change, and its outputs/inputs won't be update.
Thus the "Move Column" BB should be used instead with a "Get Cell" and "Set Cell" BB.


Move Row BB

 Move Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Moves a row of the array.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Src Row: index of the row to move.
Dest Row: index of the row before which to insert the source row. -1 means Src Row will be put at end.


Noise Progression BB

 Noise Progression
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Interpolates a float according to a 1D Perlin Noise function in the [Min,Max] range, in a given number of milliseconds.
Noise Progression.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: is activated when the needs to loop.

Duration: how long the whole process should last.
or Number of Frames: number of steps in which the whole range is covered.
A: lower end of the range covered by the Noise-interpolated value.
B: higher end of the range covered by the Noise-interpolated value.
Alpha: The parameter "a" controls how rough the final noise function will be. Small values of "a", eg: 1, give very rough functions, larger values give smoother functions.
Beta: Some positive number greater than 1, most commonly it will be powers of 2.
Harmonics: Number of harmonics of these functions, creating a weighted sum of all different noise functions, giving a more complex result.

Elapsed Time: time elapsed since the start of the progression.
or Current Frame: current step of the progression.
Value: current Noise-interpolated value.
Delta: subtraction between current Noise-interpolated value and the previous one.
Progression: percentage between 0% and 100% which defines the progression of the process. start=0%, middle time=50%, end=100%. Useful if you need to interpolates at the same time (in the same loop) a color vlaue, a vector, a orientation or something like this.

Time Based: If checked, this building block will be Time and not Frame Rate dependant. Making this building block Time dependant has the advantage that compositions will run at the same rate on all computer configurations.

This building block can be used to "shake" the camera to simulate an earthquake effect, or more generally to put more "life" in a scripted behavior.
See also: Bezier Progression.

Warning

- As a time dependant looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally laps of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frame link delay, the process will become frame dependant.
- also Remember: PERCENTAGE values are compatible with FLOAT values, and ANGLE values.
(for the 'Progression' output parameter)


Nop BB

 Nop
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Join several links and dispatch the stream to all the outputs.
Mini Calculator - Modify Component - Random - Threshold - Nop.cmo

Technical Information

In K: any of the inputs will trigger the process.
Out K: if the building block is activated, all the outputs are then activated.

This convenient building block acts just like an interface object in the schematique.
You can add as many inputs and outputs as needed.


Object Between BB

 Object Between
Categorized in Logics/Test

Description

Apply to a BEOBJECT.
Tests if there is an object between the two given entities
Object Between.cmo

Technical Information

In: triggers the process.

Yes: is activated if an obstacle is between the two given objects.
No: is activated if there is no obstacle between the two objects.

Object 1: the first object of the test.
Object 2: the second object of the test.
Precision: level of precision of the intersection detection. whether 'Bounding Box' (tests only the intersection between bounding box) or 'Face' (test intersection with all the faces of obstacles)
Test Only Obstacles: if this boolean is set to TRUE, only obstacles registred in the Collision Manager will be taken into account during the test.

Obstacle: the nearest object from object #1 that is between object #1 and #2.


Objects With Attribute Iterator BB

 Objects With Attribute Iterator
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
Retrieves each element of a group with a particular attribute
Attributes - Group Operator.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Attribute: the attribute type.

Object: the current parsed objects carrying the attribute.
(Attribute value): The attribute value (if any) for the returned object.

This building block parse all the objects of the current scene carrying the specified attribute.

See also: Set Attribute, Remove Attribute.


One At A Time BB

 One At A Time
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
When reseted, this building block activates the Output corresponding to the last activated Input.
One At A Time.cmo

Technical Information

Reset: Activates the output corresponding to the last activated input.
In 1: Input signals to be memorized.
In 2: Input signals to be memorized.
In n: Input signals to be memorized.
When several inputs are activated during the same frame, the higher "n" Input is taken into account.
...

Out Reset: is activated when the building block has been reseted.
Out n: activated if Reset is activated and "In n" is the last activated input(with the exception of Reset). The frame when Reset is activated is also taken into account to determine what is the last activated input.
...

While the 'Reset' signal isn't activated, no output is activated.
You can add as many inputs as needed (number of outputs will automatically be equal to the number of inputs).


Op BB

 Op
Version 2.00 - Virtools
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Processes any valid paramOp.
ParamOp.cmo

Technical Information

In: activates the process.
Out: is activated when the process is complete.

p1: first argument of the operation.
p2: second argument of the operation.

res: result of the operation.

Setting: the paramOp to perform.

Remarks

This BB allows you to perform a paramOp at any moment. For example, suppose you need to get an object's position, and want to store this position in a local parameter. One method would be to do the following:

Using the Op BB however is a lot easier:


Output To Console BB

 Output To Console
Categorized in Logics/Strings

Description

Apply to a BEOBJECT.
Writes a string to the console (Event Log).
Output To Console.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

String: text to display in the Event Log.
Output Target?: if selected, the target/owner is displayed before the text in the Event Log.
Beep?: if selected, a 'beep' sound is played as the text is written to the Event Log.

Remarks

Use 'beep' only if necessary as this can take up system resources and slow down playback.


Parameter Selector BB

 Parameter Selector
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
According to the Input activated, routes the corresponding Input Parameter to the Output Parameter.
Sequencer - Parameter Selector.cmo

Technical Information

In 0: triggers the building block process.
In 1: triggers the building block process.
...etc.
Out: is activated when the building block process is completed.

pIn 0: first parameter.
pIn 1: second parameter.
...etc.
Selected: selected parameter.

If "In 0" is activated, "Selected" parameter will be "pIn 0".
If "In 1" is activated, "Selected" parameter will be "pIn 1".
...etc.
Generally speaking, if "In K" is activated, Selected parameter will be "pIn K".
You can add as many 'Inputs' as needed (number of 'Input Parameters' will automatically be equal to the number of 'Inputs').
Note: if you change the type of parameter out 'Selected', the 'input parameters' will transform their type to match it.


Per Second BB

 Per Second
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Calculates a progression (Y) according to a given speed (X): Y=X*Elapsed Time During One Frame. X can be any kind of parameter as far as this parameter is only made of float values (or derived type).
Time.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

pIn 0: Input value to be concidered in 1 second.

pIn 0: Output value, pOut N = pIn N * Ellapsed Time (in s.). The elapsed time represents the duration of one rendering process.

Examples of its use ... - Assume you need to make an object rotate at the speed of 5 degrees per second, just change 'Y' parameter type to an angle, and give 'pIn 0' the value 5. Then link 'pOut 0' to the input parameter of the 'Rotate' building block, and loop.
- Or assume you need to make an object translate in depth at the speed of 2 units per second, just change 'pOut 0' parameter type to a vector, and give 'pIn 0' the value [0,0,2]. Then link 'pOut 0' to the input parameter of the 'Translate' building block, and loop.

Warning

- You add as many pOut as you want, a corresponding number of pIn will be created.
- You can change the type of any pOut, the corresponding pIn will be automatically cast to this type.
- The "Per Second" building block works only for parameters compound of FLOAT values (and only FLOAT values).
ex: PERCENTAGE, ANGLE, FLOAT, VECTOR, VECTOR 2D, MATRIX, COLOR ...etc.
- If you enter an INTEGER type, the pOut and corresponding pIn will be cast to a FLOAT. but beware, if you enter any other non-FLOAT compatible type you won't be warn, and the "Per Second" building block wont't work.


Priority BB

 Priority
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Sets priorities between several signals (Inputs Activation).
Priority.cmo

Technical Information

Reset: resets the building block to its initial state.
In 1: triggers the building block process.
In 2: triggers the building block process.

Out Reset: is activated when the building block has been reset.
Out 1: is activated when the building block has been activated by In1 (assuming the priority level allows it).
Out 2: is activated when the building block has been activated by In2 (assuming the priority level allows it).

You can add as many inputs as needed (number of outputs will automatically be equal to the number of inputs).

When reseted, the building block sets the priority level to 0.
An incoming signal in "In 1" sets the priority to 1, and activates the Out1 output.
An incoming signal in "In 2" raises the priority to 2, activates the "Out 2" output, and disables "In 1" (resulting in the impossibility for "In 1" signals to activate "Out 1").
Generally speaking, an incoming signal in "In K" activates "Out K" only if priority<=K. If so, priority is raised to K, and any incoming signal in a lower input can't activate the corresponding output.
The Reset input resets the priority to 0 and unlocks all inputs.


Proximity BB

 Proximity
Categorized in Logics/Test

Description

Apply to a BEOBJECT.
Compares the distance between two 3D Entities with a given threshold distance.
Proximity.cmo

Technical Information

In: triggers the process.

InRange: is activated if the calculated distance is inferior to the threshold distance.
OutRange: is activated if the calculated distance is superior to the threshold distance.
EnterRange: is activated when swithcing from OutRange to InRange (out->in).
ExitRange: is activated when swithcing from InRange to OutRange (in->out).
Else: is activated if none of the other outputs are activated.

Distance: threshold distance.
Object A: first 3D entity.
Object B: second 3D entity.
Barycenter: test the proximity from the barycenters of the objects, otherwise, distance is calculate by considering the object basis.

Current Distance: current distance between the 3D Entities.

Use Outputs: check only the outputs that may be relevant to your use.
The useless outputs will then be removed, and only those useful will be kept.

Warning

- There's always only one output activated at a time. This means that if a object enters the range, the only activated output will be "EnterRange", even if in fact it is also inside the range.
- If the "EnterRange" output doesn't exist but the "InRange" output exists, then the "InRange" ouput will be activated as soon as the object enter the range.
- If the "ExitRange" output doesn't exist but the "OutRange" output exists, then the "OutRange" ouput will be activated as soon as the object leave the range.


Random BB

 Random
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Retrieves a Random Variable between 'Min' an 'Max'.
Mini Calculator - Modify Component - Random - Threshold - Nop.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Min: minimum value.
Max: maximum value.

Rand: random value between Min and Max.

You can change the type of the Output Parameter "Rand" to FLOAT, INT, VECTOR, BOOL (No range needed for bool), 2DVECTOR or COLOR, and the two Input Parameters will be changed automatically.

Warning

- You can also use the "Random" Parameter Operation to perform this calculation.
- The Max value will never be reached by this building block.


Random Switch BB

 Random Switch
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Switches the sequential stream to a randomly chosen ouput according to each coef.
Random Switch.cmo

Technical Information

In: triggers the process.

Out 0: is randomly activated with a probabilty of Coef 0 (assuming the sum of all coeficient is 1).
Out 1: is randomly activated with a probabilty of Coef 1 (assuming the sum of all coeficient is 1).
...etc.

Coef 0: coefficient of propability which correspond to the activation of the output "Out 0".
Coef 1: coefficient of propability which correspond to the activation of the output "Out 1".
...etc.
Setting: Forbid twice the same: forbid the redundancy of twice the same activation (if you want to prevent the current activated output to be activated next time).

E.g.: if "Coef 0" is twice bigger than "Coef 1", then "Out 0" has twice the probability than "Out 1" to be activated.
You can add as many Outputs as you want, the Input Parameters will be added automatically.


Ray Box Intersection BB

 Ray Box Intersection
Categorized in Logics/Test

Description

Apply to a BEOBJECT.
Returns the nearest object intersected by the ray, the position of the intersection point and the normal at this point.
Enter - Leave Critical Section.cmo

Technical Information

In: triggers the process.

True: is activated when the ray intersects an object.
False: is activated when the ray doesn't intersect any object.
Origin Inside: is activated when the ray origin is inside a bounding box of an object.

Ray Origin: the starting point of the ray.
Ray Direction: the direction vector of the ray.
Referential: the referential in which all the above coordinates are expressed.
Depth: Depth of the intersection detection area (ie: the distance where the ray stops).
Group: group of the parsed objects.

Object Intersected: The nearest object intersected by the ray.
Intersection Point: coordinates of the intersection point.
Intersection Normal: coordinates of the normal vector of the intersection point.
Distance: distance between the origin of the ray and the intersection point.

Local Output: check this if you want Intersection Point and Normal expressed in the intersected object referential.

Warning

- The object to which the building block applies, can not be returned.


Ray Intersection BB

 Ray Intersection
Categorized in Logics/Test

Description

Apply to a BEOBJECT.
Returns the nearest object intersected by the ray, the position of the intersection point and the normal at this point.
Enter - Leave Critical Section.cmo

Technical Information

In: triggers the process.

True: is activated when the ray intersects an object.
False: is activated when the ray doesn't intersect any object.

Ray Origin: the starting point of the ray.
Ray Direction: the direction vector of the ray.
Referential: the referential in which all the above coordinates are expressed.
Depth: depth of the intersection detection area (ie: the distance where the ray stops).
Group: group of the parsed objects. If no group is specified, it will parse all the objects of the scene.

Object Intersected: the nearest object intersected by the ray.
Face Index: index of the face intersected.
Nearest Vertex Index: index of the nearest vertex on the face intersected.
Intersection Point: coordinates of the intersection point.
Intersection Normal: coordinates of the normal vector of the intersection point.
Distance: distance between the origin of the ray and the intersection point.

Output Param Update: uncheck this if you're only interested by the intersected object. The other output parameter values won't be updated (it saves process time).
Skip Owner: check this if you want the object on which the "Ray Intersection" BB applies not to be parsed in the collision test.
Skip Transparent: check this if you don't want transparent objects to be parsed in the collision test.
Local Output: check this if you want Intersection Point and Normal expressed in the intersected object referential.


Remove Attribute BB

 Remove Attribute
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
Removes an attribute from an object.
Attributes - Group Operator.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object: the object that should remove its attribute. It can be of any type. NULL means owner
Attribute: the attribute type to remove from the object.


Remove Attribute Obsolete BB

 Remove Attribute Obsolete
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
OBSOLETE.

Removes an attribute from an object.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object: the object that should remove its attribute. It can be of any type. NULL means owner
Attribute: the attribute type to remove from the object.

Warning

This building block is obsolete and is only included for backwards compatibility.


Remove Column BB

 Remove Column
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Removes a column of the array.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Index: index of the column to remove.

Warning

- The "Remove Column" isn't supposed to be used in combination with BB such as Iterator BB. Because the Iterator BB (as many other array BB) dynamically change its outputs/inputs when they are edited (right-click + Edit Building Block), to match the column numbers and types.
If you remove dynamically a column to your array after having the "Iterator" BB edited, the "Iterator" BB won't be aware of this change, and its outputs/inputs won't be update.
Thus the "Remove Column" BB should be used instead with a "Get Cell" and "Set Cell" BB.


Remove From Group BB

 Remove From Group
Categorized in Logics/Groups

Description

Apply to a BEOBJECT.
Removes the object from a Group.
Group Iterator - Add To Group - Remove From Group - Is In Group.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Group: group from which the object is to be removed.


Remove Key Row BB

 Remove Key Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Remove cells from an array.

Technical Information

In: triggers the process.

Out: is activated when a matching cell is found and removed from the array.
No Elements Found: is activated when no matching cell has been found in the array.

Key: key value that will be removed.

This building block, using the input parameter as a research key in the key column, remove the first found row, if any.
You can trigger it several times with the same key to be sure to remove all the matching keys, or use the "Remove If" BB instead.


Remove Object From Group BB

 Remove Object From Group
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
OBSOLETE - see Remove From Group BB.

Removes the object from a Group.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Group: group from which the object will be removed.
Object: object to remove from the group.

Warning

This building block is obsolete and is only included for backwards compatibility.


Remove Row BB

 Remove Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Remove a row of the array.

Technical Information

In: triggers the process.

Removed: is activated when the row has been removed from the array.
Not Present: is activated when the row doesn't exist.

Row Index: index of the row to remove.

This building block removes the indexed row of the array and then exits by the first output if the row index was valid.


Remove Row If BB

 Remove Row If
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Remove rows matching a value from an array.

Technical Information

In: triggers the process.

Found: is activated when matching cells are found in specified column.
Not Found: is activated if there's no matching cells in the column.

Column: index of the column in which your search will be done.
Operation: comparison operator used to compare the parsed values with the reference value.
(Reference Value): this input parameter is created when choosing the column and editing the building block.
It must contains the reference value for the test.

Number Removed: number of rows removed from the array.

This building block will go through the entire array and will remove the rows for which the comparison of given column value and reference value will be true. If it finds somes, it exits by the first input and write in its output parameter the number of rows it actually removed.


Rendezvous BB

 Rendezvous
Categorized in Logics/Synchro

Description

Apply to a BEOBJECT.
Waits for a group of objects/characters expected to be at the rendez-vous to all be present in order to allow them to pass through. You need to choose a Meeting Name and a Number of participants.
Rendez Vous.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

RendezVous (1): a meeting name.
RendezVous (2): number of participants.

Number already arrived: number of objects arrived to the rendez-vous.

This building block is to be applied on each participant.
If the given 'Number of participants' is 5, each participant will be blocked until they are 5. (if they are only 4... the building block will still loop internally until they are 5...)


Reverse Order BB

 Reverse Order
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Reverse the rows order of the array.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Reverses the rows order of the array.


Reverse String BB

 Reverse String
Categorized in Logics/Strings

Description

Apply to a BEOBJECT.
Reverse the given string.
Create String - Input String - Reverse String.cmo

Technical Information

In: triggers the process.
Out: activated when the behavior's process is completed.

Text: string to reverse.

Warning

- this behavior will alter the original string.


Row Search BB

 Row Search
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Get the first row index found in an array, where the value in the chosen column match the comparison with the reference value given.

Technical Information

In: triggers the process.

Found: is activated when a matching row is found in the array.
Not Found: is activated when no matching row is found in the array.

Column: column in which your search will be done.
First Search Row: row index at which the searching process will start.
Operation: comparison operator that will be used to compare the array value with the reference value.
(Reference Value): input parameter that will be created when choosing the column and editing the building block and that will contain the reference value to test.

First Row Found: row index of the first found cell.

This building block will go through the entire array and will stop at the first row for which the comparison of given column value and reference value will be true. If it finds ones, it exits by the first input and write in its output parameter the index of the first matching row. You can then reuse this index+1 in the second input parameter to continue searching the array.

Warning

- Beware when using operators others than EQUAL and NOT EQUAL of the restriction that applies to the "Sort Rows" BB for example, concerning parameter types others than INTEGER, FLOAT and STRING.


Scan String BB

 Scan String
Categorized in Logics/Strings

Description

Apply to a BEOBJECT.
Retrieves values (float, vector or anything else) from a string.
Load String - Scan String - Get SubString.cmo

Technical Information

In: activates the process.
Out: activates when the process has completed.

Text: the string to scan.
Delimiter: the delimiter character or string that separates the different elements.

Elements Found: the number of elements succesfuly retrieved from the string.

Remarks

An example - you want to scan the text "Hello_3.14_0,1,0" with the delimiter "-" and obtain a String, Float and Vector. Construct 3 pOuts (the first of String pType, the second of Float pType, and the third of Vector pType). The pIns are the following:
Text = Hello_3.14_0,1,0
Delimiter = _

You will then get the following result:
Elements Found = 3
String = Hello
Float = 3.14
Vector = (0,1,0)

Warning

- Try to use appropriated delimiters (like * or / or _ ), as some pTypes contain {Spaces} inside their representation, like Time (0m 5s 3ms).


Send Message BB

 Send Message
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Sends a Message to a 3D Entity.
Messages.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Message: message to send. You can create your own message (enter any string you want)
Dest: 3D Entity to send the message to.

You can bind data with your message, by adding Input Parameters to the "Send Message" building block.
These data will be retrieved by using the "Get Message Data" building block.

Useful to trigger building blocks when some special event occurs on a different script than the current one.

See also: Broadcast Message, Get Message Data, Send Message To Group, Wait Message.

Warning

- Message are received one behavioral frame after being sent.


Send Message To Group BB

 Send Message To Group
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Sends a Message to each Object of a Group.
Send Message To Group.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Message: message to send.
Group: group of objects to send the message to.

You can bind data with your message, by adding Input Parameters to the SendMessage Behavior. These data will be retrieved by using the GetDataMessage behavior.

Useful to trigger building blocks on all the group's objects, when some special event occurs on a different script than the current one.

See also: Broadcast Message, Get Message Data, Send Message, Wait Message.


Sequencer BB

 Sequencer
Version 2.00 - Virtools
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
When 'In' is activated for the nth time, exits by the nth output.
Sequencer - Parameter Selector.cmo

Technical Information

If you ever see a script with another kind of "Sequencer", it must be the 1.0 version of this building block (see Sequencer V1.0 documentation to understand how it worked).

Reset: resets the building block to its initial state by setting "Current" pOut = -1. The next activated output will be "Out 1".
In: triggers the building block process. Each time the "In" input is activated, an output is also activated.

Exit Reset: is activated after "Reset" input has been triggered.
Out 1: is activated when you activate the "In" input for the 1st time.
Out 2: is activated when you activate the "In" input for the 2nd time.
...

Current: "Current"=-1 when "Exit Reset" is activated, "Current"=0 when "Out 1" is activated, and for every n, "Current"=n-1 when "Out n" is activated.

When the last Output has been activated, "Current" pOut is set to -1, so the next output to be activated is "Out 1".

Warning

- If Out n is activated, the "Current" pOut = n-1.


Sequencer V1 BB

 Sequencer V1
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
When 'In' is activated for the nth time, exits by the nth output.

Technical Information

In: triggers the building block process.
Reset: resets the building block to its initial state (BEWARE, the "Out 0" is then activated [see Warning section below]).

Out 0: is activated when the building block process has been completed for the 1st time.
Out 1: is activated when the building block processed has been completed for the 2nd time.
...

When the last Output has been activated, the behavior is reset, so that the next output to be activated is "Out 0". You can add as many outputs as needed.

Warning

- You may not want the 'Reset' signal to activate the first output, and expect it just to reset the sequence. To do so, just don't link the first output to your loop stream. Consider the first output as the 'Reset Out' one.


Set Attribute BB

 Set Attribute
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
Gives an attribute to an object, and/or sets the value of this attribute.
Attributes - Group Operator.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object: the object receiving the attribute. It can be of any type. NULL means owner
Attribute: the name of the attribute.
Attribute Value: this input parameter is automatically construct after the first edition of the behavior, it should contains the new value of the attribute.

This building block gives the Object an attribute (if the attribute wasn't assigned to it yet) and gives it a value.


Set Attribute Obsolete BB

 Set Attribute Obsolete
Categorized in Logics/Attribute

Description

Apply to a BEOBJECT.
OBSOLETE.

Gives an attribute to an object, and/or sets the value of this attribute.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object: the object receiving the attribute. It can be of any type. NULL means owner
Attribute: the name of the attribute.
Attribute Value: this input parameter is automatically construct after the first edition of the behavior, it should contains the new value of the attribute.

This building block gives the Object an attribute (if the attribute wasn't assigned to it yet) and gives it a value.

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Cell BB

 Set Cell
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Sets the cell of a chosen row and column.

Technical Information

In: triggers the process.

Found: is activated if the given cell exists.
Not Found: is activated if the given cell doesn't exist.

Row Index: the index of the row of the cell.
Column Index: the index of the column of the cell.
(Value): the value to set in the cell. You need to change the type of this parameter according to the type of the column you will have at runtime.

Remarks

This BB does not update its input parameter type automatically when edited as the "Set Row" BB because it is designed to work with array builded at runtime with BB such as "Insert Column".


Set Component BB

 Set Component
Version 2.00 - Virtools
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Composes a COLOR, VECTOR or 2dVECTOR, by specifying each components.
Get - Set Component.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Component 1: the first component (float).
Component 2: the second component (float).
Component 3: the third component (float).

Variable: the composed COLOR, VECTOR, EULER ANGLES, VECTOR 2D, RECTANGLE, BOUNDING BOX or STRUCTURE .

Rectangle/Box Mode: if the output parameter type is a RECTANGLE or a BOUNDING BOX, then this settings define how informations should be given (center/half-size ... top,left(min) corner/ bottom/right(max) corner ... or top,left(min) corner/size).

This building block composes either a COLOR, VECTOR, EULER ANGLES, VECTOR 2D, RECTANGLE, BOUNDING BOX or a STRUCTURE from their components (floats or vector 2d for rectangles).
eg: Say 'Variable' is a vector and
'Component 1'=8.
'Component 2'=3.
'Component 3'=5.
Then 'Variable'=[8,3,5].

If you change the type of 'Variable', then (if needed) the number of input parameters will be changed automatically.

Note: when you set the "Variable" pOut to a STRUCTURE, the pIns are created to match the structure parameters.

See Also: Get Component.

Warning

- COLOR componants are to be get from 0.0 to 1.0 (so it'll much easier for you to process calculs). Therefore, [1,1,1]=white and [1,0,0]=red.


Set Key Row BB

 Set Key Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Sets the cells of a row, using the key column as a search criterion.

Technical Information

In: triggers the process.

Found: is activated when the matching row is found in the array.
Not Found: is activated when the matching row is not found in the array.

(Element Values): all the cells of the row to set are read from these input parameters. The value you give at the input representing the key column is used to find the row in the array. If more than one row containing this value in the key column are present, Set Key Row will only change the values of the first one found, from the start of the array. If you don't link some input parameters, the values will be unchanged.


Set Row BB

 Set Row
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Set the cells value of a row of an array.

Technical Information

In: triggers the process.

Out: is activated when process is completed.
Already Present: is activated if the given row already exist (only available in the unique key column mode).

Row Index: The index of the row from which the cells must be changed.
(Element Values): All the cells of the row to set are read from these input parameters.
If you don't link some input parameters, the values will be unchanged.

Unique Key Column: Specify if you want or not take care of the key column.


Shuffle Order BB

 Shuffle Order
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Shuffle the rows order of the array

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Shuffles the rows order of the array.


Sort Rows BB

 Sort Rows
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Sorts the rows of an array, according to the values of a given column.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Sorting Column: the column where values are to be concidered to actually sort the rows.
Ascending: check it, if you want your cells in increasing order, otherwise uncheck it.

Warning

- You can put any information and parameter types you want in all the column of the array, but beware to use only FLOAT, INTEGER and STRING for the "Sorting Column". Other types may lead to undefined behavior. For example OBJECTS type are sorted by the ID of the object, not by their name. PARAMETER types will be sorted by comparing their raw memory, making it works for the "Integer" parameters, but not for the "Float" parameters.


Specific Bool Event BB

 Specific Bool Event
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Detects a boolean value change. Same as 'BoolEvent', but with specific outputs.
Bool Event - Specific Bool Event - Binary Switch - Binary Memory.cmo

Technical Information

In: triggers the process.
Reset: resets the internal state memorized by the building block.
The internal state is then set to FALSE, and none of the output is activated.

True -> False: is activated when "Value" has changed from True to False.
False -> True: is activated when "Value" has changed from False to True.
Still True: is activated when "Value" has remained True.
Still False: is activated when "Value" has remained False.

Value: boolean value.

Warning

- you can activate at same time "In" and "Reset" (the building block is then reset and the "In" input is activated).


Stop & Go BB

 Stop & Go
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Activates the output only when the input stops being active.
Trigger Event - Stop & Go.cmo

Technical Information

In: triggers the process.
Out: is only when the input stops being active.

Warning

- This building block loops internally, therefore it is activated automatically each frame. Beware to choose a proper priority !
eg: if you use a "Switch On Key" building block to activate each frame the "Stop & Go", give the "Stop & Go" a smaller priority than the one you give to the "Switch On Key".
This is because there's no specific order in which the building block are called if they must loop internally.


Streaming Event BB

 Streaming Event
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Activates outputs on the input activation change.
Streaming Event.cmo

Technical Information

In 0: triggers the building block process.
In 1: triggers the building block process.
....

Out 0: is activated when the building block has been activated by "In 0" (assuming the StreamingEvent level allows it).
Out 1: is activated when the building block has been activated by "In 1" (assuming the StreamingEvent level allows it).

You can add as many Inputs as needed (number of Outputs will automatically be equal to the number of Inputs).

Last Activated Output: index of last activated output. If several outputs have been activated at the same frame, then it will be the highest index.

This building block allows you to detect streaming events, streaming changes. When you activate this building block several times by the "In 0", it will activate the corresponding output only the first time and not after.

You can "Reset" this building block (i.e: clear the BB's internal record of activations) by using one of the input as the reset one (its output will not be used). It may prove usefull for script deactivation and reactivation for instance.


Swap Rows BB

 Swap Rows
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Swaps two rows of an array.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Row 1: index of the row to swap with row 2.
Row 2: index of the row to swap with row 1.


Switch On Message BB

 Switch On Message
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Activates the appropriate output when receiving a message.
Messages.cmo

Technical Information

On: activates the behavior.
Off: deactivates the behavior.

Out 0: is activated when Message 0 is received.
Out 1: is activated when Message 1 is received.
...etc.

Message 0: first awaited message.
Message 1: second awaited message.
...etc.

You can add as many 'Outputs' as you want, the 'Input Parameters' will be added automatically.
This behavior doesn't need to loop (it'll wait message until it is deactivated by the 'Off' input).

See also: WaitMessage.

Warning

- The building block remains active after a message has been received.
If you want to deactivated it, you should enter by Off.


Switch On Parameter BB

 Switch On Parameter
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
Switches the sequential stream to the corresponding ouput, following the result of comparison between 'Test' and the others input parameters
All But One - Switch On Parameter.cmo

Technical Information

In: triggers the process.

None: is activated if Test is not identical to any other input parameter.
Out 1: is activated if Test is identical to Param 1.
Out 2: is activated if Test is identical to Param 2.
...etc.

Test: parameter to test.
Pin 1: the first reference parameter.
Pin 2: the second reference parameter.
...etc.

Float epsilon: precision for float comparisons.

This building block switch the sequential stream to the "Out K" if "Test"="Pin K".

You can add as many 'Outputs' as needed (the number of 'Input Parameters' will automatically be equal to the number of 'Inputs').
You can change the type of the "Test" input parameter (FLOAT, VECTOR, MESH, COLOR ... anything !). The type of all other input parameters will be cast to the type of "Test".
This building block is massively used (especially with the "Parameter Selection").


Test BB

 Test
Categorized in Logics/Test

Description

Apply to a BEOBJECT.
Activates the appropriate output, according to the test between A and B.
Create String - Input String - Reverse String.cmo

Technical Information

In: triggers the process.

True: is activated when Test succeed.
False: is activated when Test failed.

Test: Test to be done between A and B.
A: first value.
B: second value.

A and B could be either FLOAT values, or INTEGER values, or the ID of an object.
When you can, use this building block rather than equivalent Parameter Operation that binds you to combine a 'Binary Switch' to activate a output.
For instance, if Test is 'Greater Than', A=5 and B=2, then Behavior True is activated.

Warning

- If you want to test equality between two objects like Meshes, Vectors or other things, you'd better use the 'Switch On Parameter' Building Block.


Test Cell BB

 Test Cell
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Compare a cell with a given reference value.

Technical Information

In: triggers the process.

True: is activated when the test succeed for the given row.
False: is activated when the test failed for the given row.

Row Index: index of the row to test.
Column: index of the column in which your search will be done.
Operator: comparison operator that will be used to compare the cell value with the reference value.
(Reference Value): this input parameter will be created when choosing the column and editing the building block. The type of this parameter is chosen according to the type of the given column.


Threshold BB

 Threshold
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Binds a variable between two limits (Min and Max), and exit by the corresponding output according to the comparison result.
Mini Calculator - Modify Component - Random - Threshold - Nop.cmo

Technical Information

In: triggers the process.

X < Min: is activated if x < min.
X > Max: is activated if x > max.
Min < X < Max: is activated if x ≥ min and x ≤ max.

X: value to bind.
Min: minimum value.
Max: maximum value.

X: bounded value.

This building block is useful to bind a variable between two limits (Min and Max).
eg:
let Min=2 and Max=5, then if X=13 then bounded X value=5, and if X=0 then bounded X value=2.


Time Bezier Interpolator BB

 Time Bezier Interpolator
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
OBSOLETE - see Bezier Progression BB.

Interpolates a float according to a 2D Bezier curve in the [Min,Max] range, in a given number of milliseconds.

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Time (ms): time in which the whole range will be covered.
Curve: 2D Bezier curve.
Min: lower end of the range covered by the Bezier-interpolated value.
Max: higher end of the range covered by the Bezier-interpolated value.

Value: current Bezier-interpolated value.
Delta: subtraction between current Bezier-interpolated value and the last one.

This behavior can be used to transform a linear progression to a Bezier curve progression in the [Min,Max] range. It is frame rate independent.

See also: IBCQ, Bezier Interpolator

Warning

This building block is obsolete and is only included for backwards compatibility.


Timer BB

 Timer
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Waits (throw looping) for a given time to has elapsed.
Chrono - Counter - Delayer - Timer.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Duration: how long the whole process should last.

Elapsed Time: current time elapsed.
Exit by 'Out' if the given time to wait has elapsed, else exit by 'Loop Out'; You have to enter by 'In' to trigger (and reset) the time process.
Delta Time: time variation between two behavioral processes.

Warning

- As a time dependent looping process this building block has to be looped with a 1 frame link delay. The reason of this is because the internally lapse of time used is always equal to the duration of one global process of the building blocks.
This means, if you use 2 or 3 frames link delay, the process will become frame dependent.

See Also: "Delayer" BB, "Chrono" BB.


Trigger Event BB

 Trigger Event
Version 0.06 - Virtools
Categorized in Logics/Streaming

Description

Apply to a BEOBJECT.
activates 'Activated' output when 'In' begins to be activated / activates 'Deactivated' output when 'In' stops being activated.
Trigger Event - Stop & Go.cmo

Technical Information

In: triggers the process.

Activated: is activated once at the activation of the "In" input. It will not be activated anymore until "In" is deactivated and activated again.
Deactivated: is activated when the building block stops beeing activated by "In".

This building block activates 'Activated' output when 'In' begins to be activated / activates 'Deactivated' output when 'In' stops being activated.

Warning

- This building block loops internally, therefore it is activated automatically each frame. Beware to choose a proper priority !
eg: if you use a "Switch On Key" building block to activate each frame the "Trigger Event", give the "Trigger Event" a smaller priority than the one you give to the "Switch On Key".
This is because there's no specific order in which the building block are called if they must loop internally.


Value Count BB

 Value Count
Categorized in Logics/Array

Description

Apply to a DATAARRAY.
Returns the number of cells in a column matching the given value.

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Column: index of the column in which your search will be done.
Operator: comparison operator that will be used to compare the array value with the reference value.
(Reference Value): this output parameter will be created when choosing the column and editing the building block. The type of this parameter is chosen according to the type of the given column.

Count: number of cells in the given column matching the comparison.


Variation BB

 Variation
Categorized in Logics/Calculator

Description

Apply to a BEOBJECT.
Computes the difference between old and new value of X.
Variation.cmo

Technical Information

In: triggers the process.
Reset: resets the memorized old value to 0 (note that no output are activated).

Change: activated if old X value differs from new X value.
No Change: activated if old X value=new X value.

X: the new value to be compared to the old one.
Reset Value: the value to set to OldX when the BB is reset.

Delta: (new X value) - (old X value).
OldX: the old value stored for comparison.

Useful to compute the variation of a position (ie velocity), or to switch sequential streaming when a change of value occures.

Warning

- You can change the type of 'X', so it can be an ANGLE, VECTOR, FLOAT, INTEGER, 2DVECTOR, COLOR, and still get a Delta value (rem: FLOAT and ANGLE are anyway compatible, so does PERCENTAGE).
For all other types, the delta won't be calculated (But the variation will still be detected).
- Just change the 'X' type, and the 'Delta' type will automatically be changed.


Wait For All BB

 Wait For All
Categorized in Logics/Synchro

Description

Apply to a BEOBJECT.
Waits until all behavior Inputs have been activated to activate the output
Wait For All.cmo

Technical Information

In 0: triggers the process.
In 1: triggers the process.

Out: is activated only when all inputs have been activated once.

When all inputs have been activated, the building block activates the output and resets all the inputs.

You can add as many Input as needed.
When the ouptut is activated, all the inputs are reseted.
All the activated inputs remains activate until the output is triggered. Therefore they needn't to be active all at the same time.


Wait Message BB

 Wait Message
Categorized in Logics/Message

Description

Apply to a BEOBJECT.
Waits the receipt of a Message.
Messages.cmo

Technical Information

On: Starts waiting for a specific message.
Off: Stops waiting for a specific message.

Out: is activated when the awaited message is received.

Message: message to wait for.

The output is activated only when the message has been received.

Warning

- this is a special building block which actually does not stay active, but gives the opportunity to the message manager to activate the output of "Wait Message" when the message is received. Therefore don't be surprised if during a Trace Mode, you can't detect the activation of this building block.


While BB

 While
Categorized in Logics/Loops

Description

Apply to a BEOBJECT.
Loops while 'Condition' is TRUE.
While.cmo

Technical Information

In: triggers the process.
Loop In: triggers the next step in a process loop.

Out: is activated when 'Condition' becomes False.
Loop Out: is activated while 'Condition' is True.

Condition: condition to evaluate.

This behavior activates the 'Loop Out' output while the 'condition' is TRUE.


Materials-Textures

Animation

Movie Player: Plays a Movie (avi)

Texture Scroller: Scrolls the UV coords of a mesh's material (or one of its channel).

Texture Sine: Produces a sinusoidal displacement on the UV coords of a mesh's material (or one of its channel).

Basic

Set Alpha Test: Setups the Alpha Test of a Material.

Set Ambient: Sets the Ambient Color of a Material.

Set Blend Modes: Sets the blend modes of a Material.

Set Both Sided: Sets the Material to be rendered even if the face normals doesn't faces the camera.

Set Color Key: Sets the transparent color key of the selected texture.

Set Current Slot: Changes the current slot of the texture.

Set Diffuse: Sets the Diffuse Color of a Material

Set Emissive: Sets the Emissive Color of a Material

Set Fill Mode: Sets the fill mode of a Material : 1 = Point, 2 = WireFrame, 3 = Solid.

Set Lighting Mode: Sets the Lit mode of a mesh (lighting / no lighting).

Set Material: Sets the material of the 3D Entity (or replace an existing one).

Set Material Effect: Enables a special effect on a material.

Set Material Z Buffer: Sets the Z buffer rendering options of the material.

Set Prelit Color: Sets the color of a Prelit 3D Entity ( and Prelit the 3D Entity if it wasn't )

Set Shade Mode: Sets the Shade Mode of a Material

Set Specular: Sets the Specular Color of a Material

Set Texture: Sets the Texture of a Material.

Set Texture Mag: Sets the Material Filtering Mode when it is magnified.

Set Texture Min: Sets the Material Filtering Mode when it is minimized.

Set Transparent: Puts the Transparent flag to a Mesh (Allow Transparency to be applied with no ZBuffer problems)

Set Wrap Mode: Sets the way the texture applied to the mesh will be tiled.

Channel

Activate Channel: Activates or Deactivates a specific Channel of the Mesh.

Add Channel: Adds a Channel Material to the 3D Entity.

Remove Channel: Removes a channel material from the 3D Entity.

Set Channel Dest Blend: Sets the dest mode when Blending the Material of a specific channel.

Set Channel Material: Sets the Material of a Channel applied to the 3D Entity.

Set Channel Src Blend: Sets the Source mode when Blending the Material of a specific channel.

Mapping

Copy Mapping: Copies the texture coordinates from a mesh to another mesh,

Cylindrical Mapping: Maps an Object according to the Cylindrical.

Environment Mapping: Sets a 3D Entity to be rendered with 'pseudo' Environment Mapping.

Planar Mapping: Maps an Object according to the Planar.

Screen Mapping: Maps an Object according to the screen.

Spherical Mapping: Maps an Object according to the Spherical.

Procedural Textures

Blend Textures: Blends 2 textures.

Water Texture: Apply a water matrix to the texture.

Texture

Change Texture Size: Change the size of the texture.

Change Texture Video Format: Changes the desired video memory format of the texture applied to

Combine Texture: Combine two Textures into one

Copy Buffer to Texture: Copy a part of the frame buffer to a texture.

Filter Texture: Apply a filter matrix to the texture.

Pixel Value: Return the color of a given texture's pixel.

Set MipMap Level: Set the MipMap level of the texture.

Set MipMap Texture: Set the 'Full Size Texture' to contain the given mipmap textures.

Write In Texture: Write a colored pixel in the texture.


Activate Channel BB

 Activate Channel
Categorized in Materials-Textures/Channel

Description

Apply to a MESH.
Activates or Deactivates a specific Channel of the Mesh.
Activate Channel.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: index of channel to be activated or deactivated.
Activate: if TRUE, the channel is activated (i.e. shown), if FALSE, the channel is deactivated (i.e. hidden).

Load the composition "undocumented samples\ring.cmo" for an illustration of this.


Add Channel BB

 Add Channel
Categorized in Materials-Textures/Channel

Description

Apply to a MESH.
Adds a Channel Material to the 3D Entity.
Add Remove Channel.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Material: material to be added to the 3D Entity.
Channel: channel number assigned to the added material

The "Add Channel" BB adds a rendering layer to a whole mesh. If your 3D card supports multi-texture rendering in one single pass, the channel will be combined to the material to render the whole mesh in just one rendering pass.
If the material you try to add to the mesh via the "Add Channel" BB is already one of the mesh channels, then it won't be added anymore, until you remove it.

Load the composition "undocumented samples\ring.cmo" for an illustration of this behavior.

Warning

- If the material you want to add to the mesh via the "Add Channel" BB is already one of the mesh's channels, then it won't be added. This is to prevent excessive channel addition.


Blend Textures BB

 Blend Textures
Categorized in Materials-Textures/Procedural Textures

Description

Apply to a TEXTURE.
Blends up to two Textures with the current Texture.
Blend Textures.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

Texture 1: First Texture to blend with target Texture.
Texture 2: Second Texture to blend with the target Texture.
Blend Factor: amount of blending - 0% results in no blending at all, 100% results in all textures blending completely.

Remarks

All textures (Target Texture, Texture 1 and Texture 2) must be of the same size.


Change Texture Size BB

 Change Texture Size
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Change the size of the texture.
Change Texture Size.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Size: the new size of the texture.
Clear: if TRUE, the content of the texture is cleared (painted in black). If FALSE, the content of the texture is kept and smoothly filtered so it matches the new size.

This building block does not restretch the initial texture contents. It is mainly used for procedural texture, like the ones used by the Texture Render building block.


Change Texture Video Format BB

 Change Texture Video Format
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Changes the 'Desired Video Format' used to store a Texture in memory.
Change Texture Video Format.cmo

Technical Information

In: activates the process
Success: activates if the Desired Video Format has been successfully changed (i.e. if the current video card driver supports this format).
Failed: activates if the requested video memory format has not been successfully changed. In this case the closest available video memory format is used by the Texture.
Desired Video Format: desired texture video memory format.

Remarks

Change Texture Video Format allows you to change the video format for a Texture without having to go through the Texture Setup.


Combine Texture BB

 Combine Texture
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Combines two Textures with the Target Texture.
Combine Texture.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

Color Texture: the Texture to copy onto the Target Texture.
Color Filter: the percentage of each color to take from Color Texture.
Alpha Texture: the Texture to use as an alpha channel for the Target Texture.

Remarks

- All Textures (Target Texture, Color Texture and Alpha Texture) must be of the same size.
- Use pure white for Color Filter to obtain a pure copy (and best speed efficiency.).
- Only the red channel of the Alpha Texture is used if this Texture is specified.

Combine Texture is currently the only method to add an Alpha mask to an AVI file.

Warning

- This operation is destructive; you will lose your original (Target) Texture unless you have set Initial Conditions for it.


Copy Buffer to Texture BB

 Copy Buffer to Texture
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Copies a part of the frame buffer to a Texture.
Copy Buffer to Texture.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

Source: the section of the buffer to copy.
Destination: the part of the target Texture to copy to.

Remarks

Copy a source rectangle in the screen buffer to the texture. The given rectangles must have the same size. This behavior performs a copy directly from video memory to video memory so the system copy that is drawn in the texture setup will not be modified.


Copy Mapping BB

 Copy Mapping
Categorized in Materials-Textures/Mapping

Description

Apply to a MESH.
Copies the texture coordinates from a mesh to another mesh,
Copy Mapping.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Dest Channel: destination channel (-1 means the default material).
Src Mesh: source mesh (mesh from which to take the UVs coordinates.
Src Channel: source channel (-1 means the default material).
UV Tile: Multiply each copied UV coordinates by those factors.

Copies the uv coordinates of a source mesh (or one of its channels) to the uv coordinates of another mesh (or one of its channels).

Warning

- the two meshes MUST be identical. The only things that can be different are their mapping coordinates.


Cylindrical Mapping BB

 Cylindrical Mapping
Categorized in Materials-Textures/Mapping

Description

Apply to a 3DOBJECT.
Maps an Object according to the Cylindrical.
Cylindrical Mapping.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: if set to -1, the mapping is calculated only for the default material. Otherwise it is processed on the specified channel.
Mapping Referential: 3D Entity defining the position of the mapping cylinder, and its orientation.
UV Tile: scaling of the mapping projection around the cylinder (U coordinate), and along the cylinder (V coordinate).
Wrap Correction: if TRUE, a wrapping correction will be calculate in order to avoid cyclic mapping compression artifact. Otherwise projection will be only proportionnal to the angle around the cylinder.


Environment Mapping BB

 Environment Mapping
Categorized in Materials-Textures/Mapping

Description

Apply to a 3DOBJECT.
Sets a 3D Entity to be rendered with 'pseudo' Environment Mapping.
Environment Mapping.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: if set to -1, the environement mapping is calculated only for the default material. Otherwise it is processed on the specified channel.
Options:
Flip U: if TRUE, flip mapping horizontally.
Flip V: if TRUE, flip mapping vertically.
Use Ref Orientation: if TRUE, the orientation of "Projection Ref" will be used to define U and V axis (U = X axis of "Projection Ref", and V = Y axis of "Projection Ref"). If FALSE, the orientation will be calculated automatically from the "Projection Ref"'s position.
Reflective Mapping: computes the reflected vector for each vertex, depending on the camera (or Ref) position. This way you can still see some texture variation even on a totally flat plane (like windows).
Projection Ref: 3d Entity standing for the virtual light's position/orientation from which the environment mapping projection is performed.

The "Environment Mapping" BB change UV mapping coordinates in such a way that the mapped texture seems now to be a refection of light.
To perform such an effect you should use some kind of radial map with a large bright disk at the center.
Environment Mapping can thus be used to simulate Phong Shading.
If channel = -1, the material(s) used to render the environment mapping effect is/are the object's current material(s).
If channel > -1, the environment mapping effect is calculated on the specified channel, and the mesh's UV coordinates are only changed for this channel (not for the mesh itself).

For an example, load the compositions Environment Mapping.cmo.

You can also use the "Environment Mapping" building block to create a cartoon effect:
The left rendering cartoon style can be produce with the "Environment Mapping" building block and the right texture.

The Paper effect is just a full screen size 2D Sprite (unpickable).

Warning

- The "Environment Mapping" building block change the mesh's UV coordinates, thus, if you need to get back the initial mapping, you should set Initial Conditions on the mesh before activating the Environment Mapping BB.
- Loop this building block to get a constant effect.
- If "Use Ref Orientation" is TRUE and if "Projection Ref" is non-NULL, you should use a "Look At" building block (or simply a target light as a referential) to make sure the pseudo-light always faces the object.


Filter Texture BB

 Filter Texture
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Applies a custom filter to the Target Texture.
Filter Texture.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

Matrix Rows: A 3x3 integer matrix representing the filter to apply to the texture.
Scale: An integer to re-scale each value once multiplied by the matrix. 0 means the sum of all Matrix terms, for uniform scaling.

Remarks

Filter Texture allows you to produce effects similar to Adobe Photoshop's Custom Filter command. Known matrices to get you started include:

  • Gaussian Blur: (1,2,1),(2,4,2),(1,2,1)

  • Emboss Filter: (-1,0,1),(-1,0,1),(-1,0,1)

  • Low-Pass Filter: (0,1,0),(1,3,1),(0,1,0)

    • Comments


Movie Player BB

 Movie Player
Categorized in Materials-Textures/Animation

Description

Apply to a TEXTURE.
Plays a Movie (avi)
Movie Player.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Synchro Out: activated each time a slot changes.
One Loop Played: is activated once the animation has been performed.

Duration: how long the whole process should last.
Loop: tells wether or not the movie has to loop.
Starting Slot: the starting frame of the movie.
Ending Slot: the ending frame of the movie ( this frame will not be played !!! )

Current Slot: the current frame being played.

By default, 'Starting Slot'=0 and 'Ending Slot'=0, which means the movie has to be played from front to end.


Pixel Value BB

 Pixel Value
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Return the RGBA value of a given texture's pixel.
Pixel Value.cmo

Technical Information

In: activates the process.

In Range: activates if the (U,V) coordinates are included in [0,1] range.
Out Range: activates if the (U,V) coordinates aren't included in [0,1] range.

Slot: slot of the texture where the pixel should be read.
(U,V): pixel coordinate in the texture homogeneous referential ([0,0]=top left corner, [1,1]=bottom right corner).
Address Mode: defines the way the pixel should be bound to the texture limits when it exceeds [0,1] range.

Pixel: value of the pixel's color in RGBA format.

Use 2D Vector: should the BB use a 2D Vector format for the (U,V) coordinates.
Homogeneous: should the coordinates be given in the homogeneous referential of the texture. if TRUE, coordinates inside range are between 0 and 1, if FALSE, coordinates inside range are between 0 and texture's width for U, and between 0 and texture's height for V.

Remarks

- if UV = [0,0], the retrieved pixel is the top-left texture pixel.


Planar Mapping BB

 Planar Mapping
Categorized in Materials-Textures/Mapping

Description

Apply to a 3DOBJECT.
Maps an Object according to the Planar.
Planar Mapping.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: if set to -1, the mapping is calculated only for the default material. Otherwise it is processed on the specified channel.
Mapping Referential: the referential conducting the projection, along its Z axis. NULL means a planar mapping along the Z world axis.
UV Tile: Tiling of the projected texture, determines also the size of the texture projected if the material is in clamp mode.


Remove Channel BB

 Remove Channel
Categorized in Materials-Textures/Channel

Description

Apply to a MESH.
Removes a channel material from the 3D Entity.
Add Remove Channel.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Material: channel .
Channel: channel to be removed from the 3D Entity.

To choose which channel you want to remove, set one of the two input parameters:
- If you don't know the channel number, set it to -1 and specify the corresponding material.
- If you don't know which material correspond to your channel, specify a channel number greater than -1.

Warning

- If the channel number is smaller than 0, and if the material is NULL, no channel will be removed.
- If the channel number is greater than -1, and if the material is non-NULL, the preference will be given to the channel number as it is the fastest way to find a channel.


Screen Mapping BB

 Screen Mapping
Categorized in Materials-Textures/Mapping

Description

Apply to a 3DOBJECT.
Maps an Object according to the screen.
Screen Mapping.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: if set to -1, the mapping is calculated only for the default material. Otherwise it is processed on the specified channel.
Screen UVs: the texture coordinates coresponding to the screen region.
Rotation: angle to which rotate the projection.
Disable Perspective Correction: Disable perspective correction for rendering the object.

Warning

- The Disable Perspective Correction setting is to be used on Video cards that does allow to disable perspective correction. This option is only valid for the -1 channel.
- When Disable Perspective Correction setting is used, only the -1 channel (base channel) is affected by this building block. When using this option, the channel input of the building block is not used.
- When Disable Perspective Correction setting is used, the mesh texture coordinates are not modified. To display the mesh correctly, the building block must be kept active as long as the screen mapping should be applied.


Set Alpha Test BB

 Set Alpha Test
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Setups the Alpha Test of a Material.
Set Alpha Test.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Alpha Test Enable: The Alpha Test is enabled or not.
Alpha Test Function: select the Alpha Compare function the material should use.
Alpha Reference Value: select the Alpha reference value to use.


Set Ambient BB

 Set Ambient
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Ambient Color of a Material.
Set Ambient.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Ambient Color: ambient color.


Set Blend Modes BB

 Set Blend Modes
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the blend modes of a Material.
Set Blend Modes.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Blend: tells whether the blending is enable or not.
Source Blend: the blending mode of the source.
Destination Blend: the blending mode of the destination.
Texture Blend: how the texture will affect the material.

BLEND_ZERO
Blend factor is (0, 0, 0, 0).

BLEND_ONE
Blend factor is (1, 1, 1, 1).

BLEND_SRCCOLOR
Blend factor is (Rs, Gs, Bs, As).

BLEND_INVSRCCOLOR
Blend factor is (1-Rs, 1-Gs, 1-Bs, 1-As).

BLEND_SRCALPHA
Blend factor is (As, As, As, As).

BLEND_INVSRCALPHA
Blend factor is (1-As, 1-As, 1-As, 1-As).

BLEND_DESTALPHA
Blend factor is (Ad, Ad, Ad, Ad).

BLEND_INVDESTALPHA
Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).

BLEND_DESTCOLOR
Blend factor is (Rd, Gd, Bd, Ad).

BLEND_INVDESTCOLOR
Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).

BLEND_SRCALPHASAT
Blend factor is (f, f, f, 1); f = min(As, 1-Ad).

BLEND_BOTHSRCALPHA
Source blend factor is (As, As, As, As), and destination blend factor is (1-As, 1-As, 1-As, 1-As); the destination blend selection is overridden.

BLEND_BOTHINVSRCALPHA
Source blend factor is (1-As, 1-As, 1-As, 1-As), and destination blend factor is (As, As, As, As); the destination blend selection is overridden.

Resulting Color in the Destination Frame Buffer will be
FrameBufferColor = DestColor*DestBlendMode + SourceColor*SrcBlenMode


Set Both Sided BB

 Set Both Sided
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Material to be rendered even if the face normals doesn't faces the camera.
Set Both Sided.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Both Sided: if TRUE, the material will be two-sided (i.e. rendered even if the faces aren't turn toward the camera).

Use this building block to render walls or doors (or everything else) that have been modelized with no thickness.


Set Channel Dest Blend BB

 Set Channel Dest Blend
Categorized in Materials-Textures/Channel

Description

Apply to a MESH.
Sets the dest mode when Blending the Material of a specific channel.
Set Channel Blend.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: the channel which material will be changed.
Blending Mode: dest mode when Blending.

Load the composition "undocumented samples\ring.cmo" for an illustration of this behavior.


Set Channel Material BB

 Set Channel Material
Categorized in Materials-Textures/Channel

Description

Apply to a MESH.
Sets the Material of a Channel applied to the 3D Entity.
Set Channel Material.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: the channel which material will be changed.
Material: the material that will be put in the channel.


Set Channel Src Blend BB

 Set Channel Src Blend
Categorized in Materials-Textures/Channel

Description

Apply to a MESH.
Sets the Source mode when Blending the Material of a specific channel.
Set Channel Blend.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: the channel which material will be changed.
Blending Mode: Source mode when Blending.

Load the composition "undocumented samples\ring.cmo" for an illustration of this behavior.


Set Color Key BB

 Set Color Key
Categorized in Materials-Textures/Basic

Description

Apply to a TEXTURE.
Sets the transparent color key of the selected texture.
Set Color Key.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Translucent Color: the color you want to be invisible.
Transparent: if TRUE, the chosen color will appear translucent on the texture.


Set Current Slot BB

 Set Current Slot
Categorized in Materials-Textures/Basic

Description

Apply to a TEXTURE.
Changes the current slot of the texture.
Set Current Slot.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Slot Index: index of the new current texture slot.

Texture slots are simply different images contained in a texture.
See the Setup View for textures.


Set Dest Blend BB

 Set Dest Blend
Categorized in Materials-Textures/Texture

Description

Apply to a MATERIAL.
OBSOLETE.

Sets the Destination Mode when Blending is used on the material of the 3D entity.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Blending Mode:

BLEND_ZERO
Blend factor is (0, 0, 0, 0).

BLEND_ONE
Blend factor is (1, 1, 1, 1).

BLEND_SRCCOLOR
Blend factor is (Rs, Gs, Bs, As).

BLEND_INVSRCCOLOR
Blend factor is (1-Rs, 1-Gs, 1-Bs, 1-As).

BLEND_SRCALPHA
Blend factor is (As, As, As, As).

BLEND_INVSRCALPHA
Blend factor is (1-As, 1-As, 1-As, 1-As).

BLEND_DESTALPHA
Blend factor is (Ad, Ad, Ad, Ad).

BLEND_INVDESTALPHA
Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).

BLEND_DESTCOLOR
Blend factor is (Rd, Gd, Bd, Ad).

BLEND_INVDESTCOLOR
Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).

BLEND_SRCALPHASAT
Blend factor is (f, f, f, 1); f = min(As, 1-Ad).

BLEND_BOTHSRCALPHA
Source blend factor is (As, As, As, As), and destination blend factor is (1-As, 1-As, 1-As, 1-As); the destination blend selection is overridden.

BLEND_BOTHINVSRCALPHA
Source blend factor is (1-As, 1-As, 1-As, 1-As), and destination blend factor is (As, As, As, As); the destination blend selection is overridden.

Resulting Color in the Destination Frame Buffer will be
FrameBufferColor = DestColor*DestBlendMode + SourceColor*SrcBlenMode

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Diffuse BB

 Set Diffuse
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Diffuse Color of a Material
Set Diffuse.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Diffuse Color: the diffuse color.
Keep Alpha Component: specifies whether or not to keep the transparency of the material. (ie: whether or not the alpha field of the color will be considered.)

Warning

- This building block won't have any effect on prelited meshes.


Set Emissive BB

 Set Emissive
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Emissive Color of a Material
Set Emissive.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Emissive Color: the material's self-illumination color.


Set Fill Mode BB

 Set Fill Mode
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the fill mode of a Material: 1 = Point, 2 = WireFrame, 3 = Solid.
Set Fill Mode.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Fill Mode: Point / WireFrame / Solid / Zonly.
Point: the object is rendered as a set of points representing its vertices.
WireFrame: the object is rendered as a set lines representing its edges.
Solid: the object is rendered as a set of filled polygons representing its surface.
Zonly: the object is rendered to the Z buffer only.

see also: Use Z Information BB.


Set Lighting Mode BB

 Set Lighting Mode
Categorized in Materials-Textures/Basic

Description

Apply to a 3DENTITY.
Sets the Lit mode of a mesh (lighting / no lighting).
Set Lighting Mode.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Lighting Mode: PreLitMesh (no light calculation will be performed for this mesh) / LitMesh (perform light calculation).


Set Material 3DSprite BB

 Set Material 3DSprite
Categorized in Materials-Textures/Basic

Description

Apply to a SPRITE3D.
OBSOLETE.

Sets the material of the 3D Sprite.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Material: material for the 3D Sprite.

This behavior is equivalent to using the behavior 'Remove From Group' with a 'Target Parameter'.

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Material BB

 Set Material
Categorized in Materials-Textures/Basic

Description

Apply to a 3DENTITY.
Sets the material of the 3D Entity (or replace an existing one).
Set Material.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Material: material to be apply to the 3D Entity's current mesh.
Material To Replace: material to be replaced. If no "Material To Replace" is specified the first material is applied to the whole mesh.

Warning

- The "Set Material" building block can also be used to change the material of a 3D Sprite.
- If no "Material To Replace" is specified the first material is applied to the whole mesh.


Set Material Effect BB

 Set Material Effect
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Setup an effect on a material.
Set Material Effect.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Effect: A special effect you want to use on the material such as texture coordinate generation, bump mapping,etc. See the Material Setup.
Texture 1: In addition to the base material texture, 3 textures can be used for a given effect (such as bump map which requires a bump texture and a environment texture).
Texture 2: Optionnal Texture 2.
Texture 3: Optionnal Texture 3.
Created parameter: Once the behavior is first edited an additionnal parameter will be created according to the chosen effect, this parameter contains the effect settings such as the amplitude for a bump-mapping or a referential for a texture coordinate generation effect.

Remarks

- Texture input parameters are ignored by the BB if they are not connected to local parameters. For example if you want to modify only the Texture1 without modifying the other parameters you can delete all the local parameters after Texture 1.

Warning

- Effects are not guaranteed to work on every rasterizers (DirectX 5 rasterizer is unlikely to support any of them).
- Moreover there are no "Fallback" solution if an effect is not supported by the graphic card.


Set Material Z Buffer BB

 Set Material Z Buffer
Categorized in Materials/Basic

Description

Apply to a MATERIAL.
Set the Z Buffer rendering options options of the material.
Set Material Z Buffer.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Z Buffer Write: if TRUE, the material will force ZBuffer writing for all faces using this material.
Z Compare Function: select the Z Compare function the material should use (i.e. sets the Z Reading properties of faces using this material).
NEVER = Always fail the test.
LESS = Accept if value if less than current value.
EQUAL = Accept if value if equal than current value.
LESSEQUAL = Accept if value if less or equal than current value.
GREATER = Accept if value if greater than current value.
NOTEQUAL = Accept if value if different than current value.
GREATEREQUAL = Accept if value if greater or equal current value.
ALWAYS = Always accept the test.


Set MipMap Level BB

 Set MipMap Level
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Set the MipMap level of the texture.
Set MipMap Level.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Use MipMapping: if true mipmapping will be used for this texture.


Set MipMap Texture BB

 Create MipMap Texture
Categorized in Materials-Textures/Texture

Description

Apply to a BEOBJECT.
Manually sets the Textures to use for mipmapping.
Set MipMap Texture.cmo

Technical Information

In: activates the process.
Out: activates when the process completes.

Full Size Texture: Texture to use when mipmapping full size elements (1/1).
Size/2: Texture to use when mipmapping half size elements (1/2).

Remarks

This BB allows you to explicitly specify the number of mipmapping levels and the Textures to use at each level. This can be very useful for special effects.

You can construct pIns to reference as many Textures as you require levels of mipmapping. Remember that you must activate mipmapping for the Texture (either in the Texture Setup or using the Set MipMap Level BB). The Textures you specify as pIns are not modified.

In versions prior to Dev 2.5, this behavior was called Create MipMap Texture.


Set Prelit Color BB

 Set Prelit Color
Categorized in Materials-Textures/Basic

Description

Apply to a 3DENTITY.
Sets the color of a Prelit 3D Entity ( and Prelit the 3D Entity if it wasn't )
Set Prelit Color.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Filtering Color: color by which the texture colors are multiplied... e.g.: to see red components of the texture, set filtering color to (255, 0, 0, 128)..
Note that the alpha component is the fourth member of the filtering color

Warning

- The "Set Prelit Color" building block destroys the 'normals' information of the vertices. (Because the vertex color of a Prelit mesh, and the normal vector on each vertices, overlap)
- The "Set Prelit Color" building block can also be used to modify the color of a 3D Sprite.


Set Shade Mode BB

 Set Shade Mode
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Shade Mode of a Material
Set Shade Mode.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

ShadeMode: Flat, Gouraud or Phong.


Set Specular BB

 Set Specular
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Specular Color of a Material
Set Specular.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Specular Color: the specular color (useful to give metalic effects).
Specular Power: positive float value.


Set Specular Power BB

 Set Specular Power
Categorized in Materials-Textures/Mapping

Description

Apply to a MATERIAL.
OBSOLETE.

Sets the Power value of the Material (specular shape of the reflected light).

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Power: positive float value (Typically between 0 and 1).

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Src Blend BB

 Set Src Blend
Categorized in Materials-Textures/Mapping

Description

Apply to a MATERIAL.
OBSOLETE.

Sets the Source mode when Blending the Material.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Blending Mode:

BLEND_ZERO
Blend factor is (0, 0, 0, 0).

BLEND_ONE
Blend factor is (1, 1, 1, 1).

BLEND_SRCCOLOR
Blend factor is (Rs, Gs, Bs, As).

BLEND_INVSRCCOLOR
Blend factor is (1-Rs, 1-Gs, 1-Bs, 1-As).

BLEND_SRCALPHA
Blend factor is (As, As, As, As).

BLEND_INVSRCALPHA
Blend factor is (1-As, 1-As, 1-As, 1-As).

BLEND_DESTALPHA
Blend factor is (Ad, Ad, Ad, Ad).

BLEND_INVDESTALPHA
Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).

BLEND_DESTCOLOR
Blend factor is (Rd, Gd, Bd, Ad).

BLEND_INVDESTCOLOR
Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).

BLEND_SRCALPHASAT
Blend factor is (f, f, f, 1); f = min(As, 1-Ad).

BLEND_BOTHSRCALPHA
Source blend factor is (As, As, As, As), and destination blend factor is (1-As, 1-As, 1-As, 1-As); the destination blend selection is overridden.

BLEND_BOTHINVSRCALPHA
Source blend factor is (1-As, 1-As, 1-As, 1-As), and destination blend factor is (As, As, As, As); the destination blend selection is overridden.

Resulting Color in the Destination Frame Buffer will be
FrameBufferColor = DestColor*DestBlendMode + SourceColor*SrcBlenMode

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Texture BB

 Set Texture
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Texture of a Material.
Set Texture.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Texture: the texture to be set.
Perspective Correct: if TRUE, the mapping will be draw with a perspective correction. If FALSE, the mapping will be applied linearly without perspective correction.
Address Mode:
WRAP = Default mesh wrap mode is used (see VXTEXTURE_WRAPMODE).
MIRROR = Texture coordinates outside the range [0..1] are flipped evenly.
CLAMP = Texture coordinates greater than 1.0 are set to 1.0, and values less than 0.0 are set to 0.0.
BORDER = When texture coordinates are greater than 1.0 or less than 0.0 , texture is set to a color defined in CKMaterial::SetTextureBorderColor.

Warning

- If the object wasn't textured before, it is possible that no UV coords. were applied to its vertices. Therefore, you won't be able to see the texture properly. To do so, you have to assign some mapping method to the object. Whether with Virtools (for the moment, the only way to do something like that is throw the EnvMapping behavior), or by applying some texture mapping with a 3d graphic software specialized in it.


Set Texture Mag BB

 Set Texture Mag
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Material Filtering Mode when it is magnified.
Set Texture Mag.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Mode:
NEAREST: No Filter
LINEAR: Bilinear Interpolation
MIPNEAREST: Mip mapping
MIPLINEAR: Mip Mapping with Bilinear interpolation
LINEARMIPNEAREST: Trilinear Filtering
LINEARMIPLINEAR: Same as Mip Linear except that the texel is interpolated before, like for Linear
ANISOTROPIC: Anisotropic Filtering


Set Texture Min BB

 Set Texture Min
Categorized in Materials-Textures/Basic

Description

Apply to a MATERIAL.
Sets the Material Filtering Mode when it is minimized.
Set Texture Min.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Mode:
NEAREST: No Filter
LINEAR: Bilinear Interpolation
MIPNEAREST: Mip mapping
MIPLINEAR: Mip Mapping with Bilinear interpolation
LINEARMIPNEAREST: Trilinear Filtering
LINEARMIPLINEAR: Same as Mip Linear except that the texel is interpolated before, like for Linear

ANISOTROPIC: Anisotropic Filtering


Set Transparent BB

 Set Transparent
Categorized in Materials-Textures/Basic

Description

Apply to a MESH.
Sets the Transparent flag for a Mesh (but does not make the element transparent).

Technical Information

Set: sets the transparent flag to TRUE.
UnSet: sets the transparent flag to FALSE.

Out: is activated when the process is complete.

Remarks

This BB activates the transparency flag for a Mesh, so that the render engine treats the element as transparent and so draws it last (transparent objects are sorted and drawn last). Note that simply activating the transparent flag does not make an element transparent however.

This BB can be particularly useful when solving rendering problems that can occur when rendering a transparent object among the opaque objects or vice versa. Note that the render order is important if you set a (visually) transparent object to be rendered among the opaque objects.

This BB can also be used to render a Mesh as transparent if this mesh does not use a Material. This is very useful if you have created models in your modeling application that use vertex alpha values for transparency but do not appear transparent in Virtools simply because the Mesh does not use Material.


Set Wrap Mode BB

 Set Wrap Mode
Categorized in Materials-Textures/Basic

Description

Apply to a 3DENTITY.
Sets the way the texture applied to the mesh will be tiled.
Set Wrap Mode.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Mode: None / V Looping (loops in V [Vertical on Texture]) / U Looping (loops in U [Horizontal on Texture]) / UV (loop in both directions).


Spherical Mapping BB

 Spherical Mapping
Categorized in Materials-Textures/Mapping

Description

Apply to a 3DOBJECT.
Maps an Object according to the Spherical.
Spherical Mapping.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Channel: if set to -1, the mapping is calculated only for the default material. Otherwise it is processed on the specified channel.
Mapping Referential: the referential conducting the projection. NULL means a spherical mapping around the world center.
Wrap Correction: if TRUE, a wrapping correction will be calculate in order to avoid cyclic mapping compression artifact. Otherwise projection will be only proportionnal to the angle around the cylinder.


Texture Scroller BB

 Texture Scroller
Categorized in Materials-Textures/Animation

Description

Apply to a MESH.
Scrolls the UV coords of a mesh's material (or one of its channel).
Texture Scroller.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Scroll Vector: translation 2D Vector.
Channel: if set to -1, the mapping is calculated only for the default material. Otherwise it is processed on the specified channel.


Texture Sine BB

 Texture Sine
Categorized in Materials-Textures/Animation

Description

Apply to a MESH.
Produces a sinusoidal displacement on the UV coords of a mesh's material (or one of its channel).
Texture Sine.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

X Amplitude: amplitude of sine displacement along the X axis of the texture
Y Amplitude: amplitude of sine displacement along the Y axis of the texture.
Velocity: radial speed expressed in radian/seconds.
Channel: if set to -1, the mapping is calculated only for the default material. Otherwise it is processed on the specified channel.

Warning

- The initial UV (mapping coordinates) on the mesh for this texture are saved when the building block is attached to the mesh (that's why we can't target this building block to another mesh than the one the building block is applied to), therefore you needn't to put Initials Conditions to the mesh if you wish to recover the initial mapping of the texture.
- Beware, not all the building blocks work with this specification (eg: Texture Scroller need IC to recover the initials mapping).
- The "Texture Sine" BB is a time based building block (i.e. it will execute at the same speed what ever the frame rate is [this means you needn't to add a per second building block in front of it]).


Water Texture BB

 Water Texture
Categorized in Materials-Textures/Procedural Textures

Description

Apply to a TEXTURE.
Simulates a ripple effect.
Water Texture.cmo

Technical Information

In: activates the process.
Out: activates when the process is completed.

Damping: the larger the value, the bigger/longer lasting the ripples/waves. Valid values range from 0 to 8.
Border Color: color used for the borders of the water; this color also influences the behavior of ripples.

Remarks

Water Texture allows you to simulate the ripples that occur when an object drops into a volume of water. Use the Write In Texture BB to create a ripple that Water Texture then moves.

Note that Border Color influences how ripples act when they reach the edge of the texture: with a white border [255,255,255] ripples bounce against the edge of the Texture, with a black border [0,0,0] ripples are simply absorbed by the texture bounds. Intermediate values results in a an interpolation of these two reactions.


Write In Texture BB

 Write In Texture
Categorized in Materials-Textures/Texture

Description

Apply to a TEXTURE.
Write a colored pixel or a texture in the texture applied to.
Write In Texture.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

UV: the uv coordinates of the pixel to write.
Color: the color of the pixel to write.
Size: size of the point to draw.
Pen texture: texture used for drawing.
Write Mode: describes the way the writting is combined with the texture. See below.

Write Mode Description:
In Replace mode, the pen replaces the existing texture pixels.
In Blend mode, the pen combines equally with the existing texture pixels .
In Add Unsat mode, color cycling occurs (color component wise) when the color result color exceeds 255.
In Add Saturate mode, result of the pixel + texture sum is clamped to White.

Warning

- You can get UV coordinates from the "2d Picking" building block located in the category "Interfaces".
- This operation is destructive, you will lost your original texture unless you have set initial conditions on it.


Mesh Modifications

Basic

Get Nearest Vertex: Get the nearest vertex of a face of a given position.

Merge Mesh: Merge the owner mesh with the mesh of the given entity.

Precompute Lighting: Precompute the lighting of an object.

Set Face Count: Set the number of faces of a mesh.

Set Face Properties: Set the properties of a Face.

Set Vertex Count: Set the number of Vertexs of a mesh.

Set Vertex Properties: Set the properties of a vertex.

Creation

Create Decal: Create a decal (object+mesh) on the targeted object.

Deformation

Bend: Bends a mesh uniformly along an axis with an angle and a direction of bending.

Explode: Makes an object appear to explode by spreading out its faces from the barycenter of the object.

Mesh Morpher: Makes a mesh out of two (that must have the same number of vertices).

Multi Mesh Morpher: Transforms the current mesh so it matches the interpolation of other meshes (ie there vertice)

Noise: Displaces the vertices of the mesh with a random vector.

Set PatchMesh Steps: Sets number of steps used to render a PatchMesh.

Sine Deform: Applies a time-dependent sinusoidal deformation to each vertice of the mesh.

Skin Join: Deforms a join so it sticks on the objects it's joined.

Stretch: Stretches an object, equivalent to scaling it with a stretch factor along the selected axis and with the opposite factor along the two other axes.

Taper: Modifies the mesh by scaling one end of it and changes the amount of tapering and the curvature of the effect.

Twist: Twists an object around an axis. You can choose the angle of twisting and the bias, ranging from -100 to 100.

Local Deformation

Change Referential: Change the referential of a specified object, with another object referential.

Invert Winding: Inverse the orientation of the faces of a mesh.

Texture Displace: Displaces the vertices of the mesh, according to the luminosity of the texture mapped to this vertex.

Vertex Translate: Translates one or more vertices of the current mesh.

Multi Mesh

Add Mesh: Adds a mesh to the selected 3d Entity.

Remove Mesh: Removes a mesh from the selected 3d Entity.

Select Mesh: Selects which mesh should be used to represent the 3D entity.


Add Mesh BB

 Add Mesh
Categorized in Mesh Modifications/Multi Mesh

Description

Apply to a 3DOBJECT.
Adds a mesh to the selected 3d Entity.
Multi Mesh.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Mesh: mesh to be added.

Add as many meshes as you want to the selected 3d Entity and then, use 'Select Mesh' to select the displayed one.
Useful to choose between several different representation of an object at runtime (like a crushed car after a collision).

See Also: Select Mesh, Remove Mesh


Bend BB

 Bend
Version 2.00 - Virtools
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Bends a mesh uniformly along an axis with an angle and a direction of bending.
Bend.cmo

Technical Information

In: triggers the process.
Exit: is activated when the process is completed.

Angle: angle to bend from the vertical plane.
Direction: direction of the bend relative to the horizontal plane.
Axis: vector that specifies the axis that the object will bend along.
Reset Mesh: if TRUE, the mesh is reset to its initial conditions at activation.
Normal Recalculation: if TRUE, the mesh vertex normals are recalculated for the lightning of the bended mesh to be correct.

The model need to be somewhat facetted for a good result.


Change Referential BB

 Change Referential
Categorized in Mesh Modifications/Local Deformation

Description

Apply to a 3DOBJECT.
Change the referential of a specified object, with another object referential.
Change Referential.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Referential to match: the new referential (3D Entity) of the object to which this building block is applied.

With this building block, you can change the pivot of rotation of an object.


Create Decal BB

 Create Decal
Categorized in Mesh Modifications/Creation

Description

Apply to a 3DOBJECT.
Create a decal (object+mesh) on the targeted object.
Create Decal.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Frustum: Camera modelling the frustum of clipping of the decal.
Decal Material: Material to apply to the decal, once created.
Offset: Offset of the decal, in world coordinates, to avoid Z-fighting problems.
Backface Cull: Should the faces backfacing the camera direction support the decal too?.
Prelit: Should the decal mesh created in prelit?.
Whole Faces: Should the supporting faces taking entirely or clipped to the frustum, thus generating new faces (and a slower process).
Generate UVs: Should the decal mesh have texture coordinates, perspective mapped in the referential of the camera.

Dynamic: Enables the object and mesh created to be dynamic.

Decal: The decal created (visible by default).

This behavior allows you to create a blood spatter on the floor for example, without using channels. It will create an entity and a mesh, sticking to the shape of the floor, but only on the section defined by the frustum given, i.e a camera. This allow rendering of decals to take much less fillrate than using channels on big objects, causing the objects to be rendered as many times as channel passes.


Explode BB

 Explode
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Makes an object appear to explode by spreading out its faces from the barycenter of the object.
Explode.cmo

Technical Information

In: triggers the process
Loop In: triggers the next step in the process loop.

Out: is activated when the process is completed.
Loop Out: activates when the process needs to loop.

Duration (ms): how long the whole process should last.
Explosion Curve: allows you to adjust the effect's progression.
Max Distance Factor: determines how far the faces are spread (it is combined with the object radius to give the final distance) .
Spreading Direction: permits spreading the faces in a forced direction (in the local referential).
Rotation: determines if you want the faces to rotate.
Deformation: determines if you want the faces to be deformed.

Warning

Since this behavior modifies the mesh geometry you have to add initial conditions on you mesh if you want to store it. Moreover this behavior can be slow on objects with many faces.


Get Nearest Vertex BB

 Get Nearest Vertex
Categorized in Mesh Modifications/Basic

Description

Apply to a MESH.
Get the nearest vertex in a given face of a given position.
Get Nearest Vertex.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Face: index of the face where to locate the nearest vertex.
Local Position: position to test in the object's referential.

Vertex Index: nearest vertex index.


Invert Winding BB

 Invert Winding
Categorized in Mesh Modifications/Local Deformation

Description

Apply to a MESH.
Invert the orientation of the faces of a mesh.
Invert Winding.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This behavior also change the normals of the faces and the normal of the vertices.


Merge Mesh BB

 Merge Mesh
Categorized in Mesh Modifications/Basic

Description

Apply to a MESH.
Merge the owner's mesh with the mesh of a given entity to create a single object.
Merge Mesh.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

3D Object: object whose mesh should be merged to the target.


Mesh Morpher BB

 Mesh Morpher
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Makes a mesh out of two (that must have the same number of vertices).
Mesh Morpher.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Start Mesh: first mesh.
End Mesh: second mesh.
Effect Value: percentage value to determine which mesh takes precedence.
"0" the hybrid has the same form as the first, "100" the hybrid has the same form as the second. "50" is a even mix of the two meshes.
Calculate Vertex Normals: interpolates the vertices normals too if checked.
Calculate Face Normals: calculates the faces normals too if checked.

This behavior takes two meshes in parameter, creates an hybrid mesh of these two using linear interpolation on the vertices and sets it as the current mesh of the attached object. If the object is prelit, or if the geometry of the two mesh are quite similar, you can spare a lot of time by not calculating the vertex normals.
If you want to pick the object, make sure to check "Calculate Face Normals".

Warning

- the two meshes must have the same number of vertices, and the vertices index must be equal from a topology to an other. To do so in your 3d modeling software, make sure to build the different meshes by always deforming the same initial mesh.


Multi Mesh Morpher BB

 Multi Mesh Morpher
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Transforms the current mesh so it matches the interpolation of other meshes (ie their vertices)
Multi Mesh Morpher.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Mesh 1: first Mesh.
Coef 1: weighting of Mesh 1.
Mesh 2: second Mesh.
Coef 2: weighting of Mesh 2.
etc ...

Mesh Count: number of meshes to be used. Some pIns (input parameters) will be added or remove in order to match your needs.
ex: If "Mesh Count" = 2 then 4 pIns will available: "Mesh 1", "Coef 1", "Mesh 2" and "Coef 2".

Calculate Normals: if TRUE, the vertices normals will be re-computed after each morphing step (better result, but slower processing).

Use Relative Morphing: if TRUE, the morphing is done relatively to the first mesh ("Mesh 1").
"Mesh 1" is considered as the neutral shape, from which the final result is computed by adding all the shapes differences with all other meshes. Each coefficient stays for factor by which must be multiplied these shapes differences.
if FALSE (default), the "Multi Mesh Morpher" BB interpolates the vertice of the current mesh with other vertice of other meshes. Each coefficient stays for the influence of a mesh above another.

Typically, if you have to make a face expression using morphing, set "Use Relative Morphing" to TRUE, so you'll be able to combine expressions.
ex:
Mesh 1 = neutral expression. Coef = NA ('cause hidden when "Use Relative Morphing" is checked).
Mesh 2 = Smile with neutral eyes. Coef = 1 (full smile)
Mesh 3 = sad eyes with neutral mouth. Coef = 1 (full sad eyes)

The final result is a face with a big smile, and sad eyes.

Note: relative morphing is slower than standard morphing.

Warning

- Unlike the 'MeshMorpher' building block, no copy of the current mesh if made into memory ; therefore, if you want to morph between MeshA and MeshB but MeshA is already the current object mesh, you should make yourself a copy of MeshA ( Ctrl+C in Level View, or Dynamic Copy ).
- all meshes must have the same number of vertices, and the vertice indices must be equal from a topology to an other. To do so in your 3d modeling software, make sure to build the different meshes by always deforming the same initial mesh.
(refer to the MeshMorpher building block)


Noise BB

 Noise
Version 2.00 - Virtools
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Displaces the vertices of the mesh with a random vector.
Noise.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Seed: generates a random starting point from the number you set.
Scale: size of noise effect (not strength).
Axis: strength of the noise effect along each of three axes.
Reset Mesh: if TRUE, the mesh is reseted to its initial conditions at activation.


Precompute Lighting BB

 Precompute Lighting
Categorized in Mesh Modifications/Basic

Description

Apply to a 3DOBJECT.
Precompute the lighting of an object.
Precompute Lighting.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Specular: if TRUE, then specular effect is computed by vertex.

This building block precompute the lighting of an object when activated, setting its mesh as prelit, thus saving the lighting computation at each render frame.


Remove Mesh BB

 Remove Mesh
Categorized in Mesh Modifications/Multi Mesh

Description

Apply to a 3DOBJECT.
Removes a mesh from the selected 3d Entity.
Multi Mesh.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Mesh: mesh to remove.

Warning

- This buidling block removes only the reference to the inner mesh. It does not remove the mesh from the Level nor from the memory.


Select Mesh BB

 Select Mesh
Categorized in Mesh Modifications/Multi Mesh

Description

Apply to a 3DOBJECT.
Selects which mesh should be used to represent the 3D entity.
Multi Mesh.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Mesh: mesh to be displayed.
Add If Missing: if yes, the selected mesh will be added to the 3dEntity list of meshes (if it hadn't been yet added with 'AddMesh').

Warning

- If the selected mesh does not belong to the 3D Entity (i.e: if it hasn't been added with 'AddMesh') and if you don't want it to be added (setting Add if Missing to FALSE), then the mesh will not be displayed in the list of meshes in the 3D Entity setup.

- It is recommended that you set Add if Missing to FALSE if you need to use a temporary mesh and want to switch back to the regular mesh afterwards. This avoids the operation of adding it to the list of meshes of the 3D entity.


Set Face Count BB

 Set Face Count
Categorized in Mesh Modifications/Basic

Description

Apply to a MESH.
Set the number of faces of a mesh.
Set Face Count-Set Vertex Count.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Face Count: Number of faces of the mesh.


Set Face Properties BB

 Set Face Properties
Categorized in Mesh Modifications/Basic

Description

Apply to a MESH.
Set the properties of a Face.
Set Face Properties.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Face Index: index of the Face to modify.
Face Material: material to set to the face.
Face Vertex Indices: index of the vertex compositing the face.

Warning

- If you do not link one input parameter, it will not be affected.


Set PatchMesh Steps BB

 Set PatchMesh Steps
Categorized in Mesh Modifications/Deformation

Description

Apply to a PATCHMESH.
Sets number of steps used to render a PatchMesh.
Set PatchMesh Steps.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Steps: number of steps used to tesselate the mesh.


Set Vertex Count BB

 Set Vertex Count
Categorized in Mesh Modifications/Basic

Description

Apply to a MESH.
Set the number of Vertices of a mesh.
Set Face Count-Set Vertex Count.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Vertex Count: Number of Vertices of the mesh.


Set Vertex Properties BB

 Set Vertex Properties
Categorized in Mesh Modifications/Basic

Description

Apply to a MESH.
Set the properties of a vertex.
Set Vertex Properties.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Vertex Index: Index of the vertex to modify.
Vertex Position: New local position of the vertex.
Vertex Normal: New local normal of the vertex.
Vertex Color: New color of the vertex (only in Prelit mode).
Vertex Specular Color: New specular color of the vertex (only in Prelit mode).
Vertex UV: New texture coordinates of the vertex.
UV Channel: Texture Coordinates Channel to modify (-1 designates the mesh base material(s)).

Warning

If you do not link one input parameter, it will not be affected.


Sine Deform BB

 Sine Deform
Version 2.00 - Virtools
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Applies a time-dependent sinusoidal deformation to each vertice of the mesh.
Sine Deform.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Deform Axis: sets the amount of deformation on each local axis.
Magnitude: global amount of deformation.
Wave Length: wave length of the sine fonction.
Reset Mesh: if TRUE, the mesh is reset to its initial conditions at activation.

Loop this behavior to observe organic deformations.

Warning

- The initial Mesh is saved when the building block is attached to the 3dObject (that's why we can't applied this building block to another 3d Object than the one the building block is applied to), therefore you do not need to put Initials Conditions to the mesh if you wish to recover the initial mesh. - Beware, not all the building block works with this specification


Skin Join BB

 Skin Join
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Deforms a join so it sticks on the objects it's joined.
Skin Join.cmo

Technical Information

On: activates the behavior process.
Off: deactivates the behavior process.

Threshold: minimal 3d distance from which 2 vertices will be considered as being the same.
Object 1: first object to which the join will be glued.
Object 2: second object to which the join will be glued.
...

This building block is an easy way to simulate skins.
You first need to modelize the join that will take place between your object (eg: the neck between a head an the body).
Then load all the objects in Virtools, and Drag'n Drop the 'Skin Join' building block on the join object (eg: the neck).
Now, you need to specify a 'Threshold'. This parameter represents the minimal 3d distance from which 2 vertices will be considered as being the same.
If you give a too small 'Threshold' you will not have all the vertice-joints you would expect.
And if you give a too great 'Threshold', the inside vertice of your 'join object' will be considered has vertice-joints.
You can specify several object to be linked to the join ( just add Input Parameters ).

Warning

- Do not use several SkinJoins on the same object, but add input parameters.
- It is recommended to set Initial Conditions to the mesh of the join, so if the 'Skin Join' building block deforms your object, you'll always be able to come back to the initial topology of your object.
- If the 'Threshold' you gave doesn't match what you want, you'll have to change it by editing the 'Skin Join' building block.
- The vertices correspondence array is evaluated each time you edit the building block.


Stretch BB

 Stretch
Version 2.00 - Virtools
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Stretches an object, equivalent to scaling it with a stretch factor along the selected axis and with the opposite factor along the two other axes.
Stretch.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Stretch: base scale factor for all three axes. A value of 1.5 corresponds to a scale factor of 1.5+1=2.5, or 250%.
Amplify: change the scale factor applied to the minor axes. It can be a negative value.
Axis: axis along which the stretch will occur.
Reset Mesh: if TRUE, the mesh is reset to its initial conditions at activation.


Taper BB

 Taper
Version 2.00 - Virtools
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Modifies the mesh by scaling one end of it and changes the amount of tapering and the curvature of the effect.
Taper.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Amount: amount of the effect (maximum of 10). Positive amounts produce an outward taper, negative amounts an inward taper.
Curve: curve of the taper. Positive values produce an outward curve along the tapered sides, negative values an inward curve.
Axis: primary axis of the taper. The effect axis can be either of the two remaining axes, or their combination.
Symmetry: When True, produces a symmetrical taper around the primary axis.
Modify First Axis: When True, the taper modifies the first remaining axis.
Modify Second Axis: When True, the taper modifies the second remaining axis.
Reset Mesh: if TRUE, the mesh is reset to its initial conditions at activation.


Texture Displace BB

 Texture Displace
Version 2.00 - Virtools
Categorized in Mesh Modifications/Local Deformation

Description

Apply to a 3DOBJECT.
Displaces the vertices of the mesh, according to the luminosity of the texture mapped to this vertex.
Texture Displace.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Texture: texture to use for displacement displace.
Red Scale: Amount of displacement for red channel.
Green Scale: Amount of displacement for green channel.
Blue Scale: Amount of displacement for blue channel.
Alpha Scale: Amount of the displacement for alpha channel.
Min Texture Source Rectangle: specifies the region of the texture to be used (top-left point of a 2D rectangle).
Max Texture Source Rectangle: specifies the region of the texture to be used (bottom-right point of a 2D rectangle).
Reset Mesh: if TRUE, the mesh is reset to its initial conditions at activation.
Normal Recalculation: if TRUE, The vertex normals and the face normals are recalculated.

3D Displacement: if TRUE, all components (X Y and Z) of the vertex position will be changed. Otherwise only the Y component of the vertex position is changed.
Useful to create landscapes on the fly: apply this behavior to a plane object. The plane will be locally deformed according to the selected channel (R, G, B or A) values on the texture.


Twist BB

 Twist
Version 2.00 - Virtools
Categorized in Mesh Modifications/Deformation

Description

Apply to a 3DOBJECT.
Twists an object around an axis. You can choose the angle of twisting and the bias, ranging from -100 to 100.
Twist.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Angle: amount of twist around the axis.
Bias: causes the twist rotation to bunch up at either end of the object (-100 to 100).
Axis: axis along which the twist will occur.
Reset Mesh: if TRUE, the mesh is reset to its initial conditions at activation. Normal Recalculation: if TRUE, the vertices normals will be re-computed after each morphing step (better result, but slower processing).


Vertex Translate BB

 Vertex Translate
Categorized in Mesh Modifications/Local Deformation

Description

Apply to a 3DOBJECT.
Translates one or more vertices of the current mesh.
Vertex Translate.cmo

Technical Information

In: triggers the process.
Reset: put back the vertices in the position they have when the building block was attached.
Out: is activated when the process is completed.

Vertex Index Start: Index of the first vertex to move.
Vertex Count: Number of vertices to move.
Translation Vector: Direction in the World Referential of the translation.
Translation Referential: Referential to the translation vector.

Remarks

For patch meshes, the Vertex Index range is 0 to the "number of control points of the mesh - 1".


Narratives

Config

Read Config: Read Data in a user specific storage place.

Write Config: Write Data in a user specific storage place.

Files

Open File: Opens the file

Object Management

Delete Dynamic Objects: Deletes all the dynamic objects in memory

Get Texture Info: Gets informations (filename and priority) about a texture.

Movie Load: Loads a movie file into a texture or a Sprite.

Object Copy: Duplicates objects

Object Create: Creates an object

Object Delete: Deletes an object

Object Load: Loads a local file, containing one or more objects

Object Rename: Renames an object

Sound Load: Loads a sound file into a sound object

Sprite Load: Loads a sprite file into a sprite or a ABPosFinder.

Texture Load: Loads a texture file into a texture or a Sprite.

Scene Management

Add Object To Scene: Add an object to a specified scene.

Get Current Scene: Returns the scene that is currently being played.

Launch Scene: Launches a specified scene.

Remove Object From Scene: Remove an object from a specified scene.

Script Management

Activate Object: Activates all the scripts of an object, either in the state they were before deactivation or once reset.

Activate Script: Activates a script, either in the state it was before deactivation or once reset.

Attach Script: Attach a script on an entity.

Call Script: Calls immediatly a script.

Deactivate Object: De-activates all the scripts of an object in the current scene.

Deactivate Script: Deactivates a Script.

Execute Script: Executes a script.

States

Activate Global State: Enters the system in the given global state.

Deactivate Global State: Exit the system from the given global state.

Is Global State Active: Checks to see if the system is in a specified global state.

Read State: Read an object state.

Restore IC: Restores an object's Initial Condition for the scene being played.

Save State: Saves an object state.

Set IC: Saves an object's Initial Condition in the scene being played.

Streaming Recording

Synchro Player: Produce streaming events that match the one recorded with 'Synchro Recorder'.

Synchro Recorder: Records some input keys events by putting them in a data array which could used with 'Synchro Player' building block.


Activate Global State BB

 Activate Global State
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Enters the system in the given global state.
Global State.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

State: the global state name.

States are only boolean values belonging to Levels, and shared by every object and script.
Use 'Is Global State Active' to test if the system is in a specific global state.

See also: Is Global State Active, Deactivate Global State.


Activate Object BB

 Activate Object
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
Activates all the scripts of an object, either in the state they were before deactivation or once reset.
Activate Object.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object: object to be activated.
Reset?: if TRUE, the initial conditions of the object will be restored.
Activate All Scripts?: if TRUE, all scripts will be activated.
Reset Scripts?: if TRUE, all scripts will be reset before activation.

Remarks

If the "Reset?" option is used, Initial Conditions for the object are restored only if a change of state for the object is detected, i.e. if the object goes from the "Deactivate" to the "Activate" state. Initial conditions are not restored if the "Activate Object" BB is used on a object already active.

See Also: Deactivate Object.

Warning

The scripts will actually be re-activated in the next frame.


Activate Script BB

 Activate Script
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
Activates a script, either in the state it was before deactivation or once reset.
Activate Script.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Reset?: if TRUE, the script will be reset; if FALSE the script will carry on from the state it was in before being deactivated.
Script: script to be activated.

Awake Object: if TRUE, activate the object if it was inactive.

With this building block scripts can be divided up into several smaller scripts and re-activated as needed.
By adding input parameters, as many scripts as needed may be re-activated.
See Also: Deactivate Script.

Warning

- the activation will be done at the next frame.


Add Object To Scene BB

 Add Object To Scene
Categorized in Narratives/Scene Management

Description

Apply to a BEOBJECT.
Add an object to a specified scene.
Add To Scene-Remove From Scene.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Scene: the scene name. NULL means the current scene.


Attach Script BB

 Attach Script
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
Attach a script on an entity.
Attach Script.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Dynamic?: must the script be attached permanently or not.
Script: script to be attached.
Activate?: must the script be activated.
Reset?: must the script be reset.

See Also: Deactivate Script.


Call Script BB

 Call Script
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
'Calls' a script so that it is processed immediately.
Call-Execute Script.cmo

Technical Information

In: activates the process.
Out: is activated when the called script has been processed.

Reset?: if TRUE, the called script is reset before being processed; if FALSE, the called script is resumed from its previous state.
Script: script to process.
Wait For Completion?: if TRUE, the script is processed until completion; if FALSE the script is executed until a link delay of 1 or greater is reached.

Remarks

This BB 'calls' a script that is then processed immediately, stopping execution of the current script. This BB is particularly useful for processing scripts that return values (like functions in c++), but it is not suited for scripts that influence rendering, such as a script that rotates a cube.

If you select the Wait For Completion? check box, link delays in the called script are not taken into account and the whole script is processed within the current frame. If you do not select Wait For Completion?, the called script is processed until a link delay of 1 or greater is encountered, then processing of the called script stops, and processing of the calling script resumes.


Deactivate Global State BB

 Deactivate Global State
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Exit the system from the given global state.
Global State.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

State: global state that must be deactivate.

States are only boolean values belonging to Levels, and shared by every object and script.
Use 'Is Global State Active' to test if the system is in a specific global state.

See also: Is Global State Active, Activate Global State.


Deactivate Object BB

 Deactivate Object
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
De-activates all the scripts of an object in the current scene.
Deactivate Object.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object: object to be de-activated.

Warning

- the object will actually be de-activated in the next frame.


Deactivate Script BB

 Deactivate Script
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
Deactivates a Script.
Deactivate Script.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Script: script to be deactivated.

This building block allows scripts to be deactivated dynamically.
By adding input parameters, as many scripts as required may be deactivated.
See also: ActivateScript.

Warning

- the script will actually be de-activated in the next frame.


Delete Dynamic Objects BB

 Delete Dynamic Objects
Categorized in Narratives/Object Management

Description

Apply to a BEOBJECT.
Deletes all the dynamic objects in memory
Delete Dynamic Objects.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.


Execute Script BB

 Execute Script
Categorized in Narratives/Script Management

Description

Apply to a BEOBJECT.
Places a script in the behavioral stack to be processed at the next frame.
Execute Script.cmo
Call-Execute Script.cmo

Technical Information

In: activates the process.
Out: is activated when the executed script has finished processing.

Reset?: if TRUE, the script is reset before being processed; if FALSE the script is resumed from its previous state.
Script: script to process.

Remarks

The script is not processed in the current frame, but in the next frame.

See also: Activate Object BB, Activate Script BB, Call Script BB


Get Current Scene BB

 Get Current Scene
Categorized in Narratives/Scene Management

Description

Apply to a BEOBJECT.
Returns the scene that is currently being played.
Get Current Scene.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Scene: name of the scene currently being played.

See also: Launch Scene


Get Texture Info BB

 Get Texture Info
Categorized in Narratives/Object Management

Description

Apply to a TEXTURE.
Gets information useful for loading externalized Texture files.
Get Texture Info.cmo

Technical Information

In: activates the process.
Exists: activates if the Texture is present.
Empty: activates if the texture is is not present.

FileName: the name of the file containing the texture.
Priority: the priority associated to the Texture in the Level View.


Is Global State Active BB

 Is Global State Active
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Checks to see if the system is in a specified global state.
Global State.cmo

Technical Information

In: triggers the process.

True: The 3D Entity is in the given state.
False: The 3D Entity is not in the given state.

State: the global state name.

Global states are only boolean values belonging to Levels, and shared by every object and script.

See also: Activate Global State, Deactivate Global State.


Launch Scene BB

 Launch Scene
Categorized in Narratives/Scene Management

Description

Apply to a BEOBJECT.
Launches a specified scene.
Launch Scene.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Scene: the scene name.
Activity Options:
Scene Defaults: use the 'Activation' flag of the scene (the one that appear in the Level View).
Force activate: force the launched scene to be active.
Force deactivate: force the launched scene to be deactive.
Do nothing: the state of all the objects is kept as they were. Thus if you choose this option, the "Launch Scene" BB will only hide object that aren't in the scene, and show the ones that are in the scene.

Reset Options:
Scene Defaults: use the 'Reset at Start' flag of the scene (the one that appear in the Level View).
Force Reset: force the launched scene to be reset (restore initial conditions).
Do nothing: do not restore initial conditions.

Warning

- The scene will actually be launched next frame.


Movie Load BB

 Movie Load
Categorized in Narratives/Object Management

Description

Apply to a TEXTURE.
Loads the first slot of a movie file into the first slot of a Texture, ready to play.
Movie Load.cmo

Technical Information

On: activates the process.
Loaded: activated if loading is successfull.
Error: activated if loading failed.

Movie File: name of the local movie file.

Remarks

Movie Load prepares a file to play - it does not actually play the movie. For this, use the Movie Player BB.


Object Copy BB

 Object Copy
Categorized in Narratives/Object Management

Description

Apply to a BEOBJECT.
Duplicates objects.
Object Copy.cmo

Technical Information

In: activates the process
Out: is activated when the process is complete.

Dependency Options: copy options, sorted by object class.
Original: object(s) to copy. You can add pIns to copy several objects at the same time.

Copy: the copied object(s). If you added pIns, matching pOuts are created.

Dynamic: if selected, copied objects are dynamic, meaning they are deleted when the composition is reset.
Awake Object: if TRUE, copied objects are made 'active', even if the source object was inactive.

Remarks

Note that this BB enables you to duplicate all types of elements, not just BeObjects, but you will need to change the pType of the Original pIn - i.e. if you wanted to duplicate an animation, you would need to change the pType of the Original pIn from Behavioral Object to Animation. Note that to change the pType you must edit the pIn individually itself.

It is better to add pIns and so copy several objects with the same Object Copy BB that to use several instances of the BB even with a link delay of 0.

If the source object is inactive when copied, the new object will also be inactive unless you have selected the Awake Object pIn check box. You can activate objects with the Activate Object BB.

Warning

Note that prior to Dev 2.1, the Object Copy BB automatically made copied objects active, regardless of the source object's state. Files saved with versions of Dev prior to version 2.1 will therefore always result in copied objects that are active.


Object Create BB

 Object Create
Categorized in Narratives/Object Management

Description

Apply to a BEOBJECT.
Creates an object
Object Create-Rename.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Class: class of the object to create.
Name: name of the object to create.

Dynamic: specifies if the object created must be dynamics.


Object Delete BB

 Object Delete
Categorized in Narratives/Object Management

Description

Apply to a BEOBJECT.
Deletes an object
Object Delete.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Dependencies Options: options of deletion, sorted by object class.


Object Load BB

 Object Load
Categorized in Narratives/Object Management

Description

Apply to a BEOBJECT.
Loads a local file, containing one or more objects
Object Load.cmo

Technical Information

Load: loads the content of the given local filename.
Unload: unload what the behavior previously loaded.

Loaded: is activated when the behavior was triggered by the input Load.
Unloaded: is activated when the behavior was triggered by the input Unload.
Failed: is activated when the loading has failed.

File: name of the local file to read the objects from.
Master Object Name: name that should be seek into the loaded objects.
Filter Class: specific class the master object should derive from.
Add To Current Scene: if TRUE, the object is added to the current scene; if FALSE, the object is only added to the level scene.
Reuse Meshes: if TRUE, a meshes with the same name of a loading one and already existing in the composition will be reused instead.
Reuse Materials/Textures: if TRUE, the materials and textures, with the same name of loading ones, already existing in the composition will be reused instead.

Loaded Objects: Object Array containing all the objects loaded.
Master Object: Master object loaded, found with the Master Name and the Filter Class inputs, or only with the Filter Class input if no name was provided. If a 3D or 2D entity is desired, a root object is taken when no name are provided.

Dynamic: specifies if the objects loaded must be dynamic.


Open File BB

 Open File
Categorized in Narratives/Files

Description

Apply to a BEOBJECT.
Opens a file with an absolute or relative path.
Open File.cmo

Technical Information

In: Triggers the behavior.
Ok: Opening successful.
Error: Opening failed

File: Filename with absolute or relative path to the cmo file.


Object Rename BB

 Object Rename
Categorized in Narratives/Object Management

Description

Apply to a BEOBJECT.
Renames an object
Object Create-Rename.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Name: new name to give to the object.


Read Config BB

 Read Config
Categorized in Narratives/Config

Description

Apply to a BEOBJECT.
Reads data from a specific storage place (in Windows, the Virtools section of the Registry, e.g. HKEY_CURRENT_USER\Software\Virtools\UserConfig\.).
Write-Read Config.cmo

Technical Information

In: activates the process.
Out: activates if the section and the entry is found.
Out: activates if the section or the entry is not found.

Section: the name of the section holding the data ("Key" or "Subkey" in Windows).
State: the name of the entry that holds the data ("Value name" in Windows).

Data: the data ("Data value" in Windows) to retrieve from the entry; can be of any type expressible as a string.

You can use Read Config to retrieve user specific information, like the player name, high score etc. that you have previously stored using Write Config.

See also: Write Config.


Read State BB

 Read State
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Read an object state.
Save-Read State.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object State: state chunck containing a state of a compatible class id to read.


Remove Object From Scene BB

 Remove Object From Scene
Categorized in Narratives/Scene Management

Description

Apply to a BEOBJECT.
Remove an object from a specified scene.
Add To Scene-Remove From Scene.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Scene: the scene name. NULL means the current scene.


Restore IC BB

 Restore IC
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Restores an object's Initial Condition for the scene being played.
Save-Restore IC.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.


Save State BB

 Save State
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Saves an object state.
Save-Read State.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Object State: current state of the target, when the behavior is processed.


Set IC BB

 Set IC
Categorized in Narratives/States

Description

Apply to a BEOBJECT.
Saves an object's Initial Condition in the scene being played.
Set-Restore IC.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Remarks

Prior to Dev 2.5, this behavior was called Save IC.


Sound Load BB

 Sound Load
Categorized in Narratives/Object Management

Description

Apply to a WAVESOUND.
Loads a sound file into a sound object
Sound Load.cmo

Technical Information

In: triggers the process.

Out: is activated when the process is completed.
Failed: is activated when the process has failed.

File: name of the local file to read the sound from.
Streamed?: should the sound be streamed or enterily loaded in memory.

Use Asynchronized Loading: if selected, the composition loads the file in a new thread. A new bIn, Kill Thread is created.

Remarks

- if you need to load several sound files asynchronously (not at the same time), use the same instance of Sound Load BB and the same thread. To do this, select the setting Use Asynchronous Loading. The first time the BB is run, a new process (thread) is created to load the file. You can reuse this thread to load subsequent sound files. Once all files have been loaded, activate the "Kill Thread" input to stop the thread.

- if the sound files are on a web server, use the streaming option with the asynchronized loading option to avoid the behavioral process from "hanging" when the file loads or is being processed (i.e. connection to the server, buffering, file decompression etc.)


Sprite Load BB

 Sprite Load
Categorized in Narratives/Object Management

Description

Apply to a 2DSprite.
Loads a image file into a Sprite.
Sprite Load.cmo

Technical Information

In: triggers the process.

Out: is activated when the process is completed.
Error: is activated when the process has failed.

File: name of the local file to read the 2D Sprite from.
Slot: slot in which to load the 2D Sprite.

Use Thread: if selected, the composition loads the file in a new thread. A new bIn, Kill Thread is created.

Remarks

If you need to load several Texture files asynchronously (i.e. not at the same time), use the same instance of the Texture Load BB and the same thread. To do this, select the setting Use Thread. The first time the BB is run, a new process (thread) is created to load the file. You can reuse this thread to load subsequent Texture files. Once all files have been loaded, activate the "Kill Thread" input to stop the thread.


Synchro Player BB

 Synchro Player
Categorized in Narratives/Streaming Recording

Description

Apply to a BEOBJECT.
Produce streaming events that match the one recorded with 'Synchro Recorder'.
Synchro Recorder-Player.cmo

Technical Information

On: activates the behavior.
Off: deactivates the behavior.

End: activated when synchro data array has been parsed entirely. NB: just loop the 'End' output with the 'On' input if you want to constantly loop the whole sequence.
Impulse: activated each time the time a new synchro signal is found (refer to 'Synchro Recorder' building block documentation).

Synchro Array: data array which must has been produced with the 'Synchro Recorder' building block.
Refer to the 'Synchro Recorder' building block documentation to see what must be the array format.

Signal Amplitude: amplitude value recorded in the data array for the current signal.
Length: length recorded in the data array for the current signal, ie: Duration of key pressing (in milliseconds).

Keep Activated During Delay:if checked, the output signal 'Impulse' will stay active during 'Length' time.

Remarks

The Synchro Player BB parses the synchronized data array (Synchro Array), and activates the 'Impulse' every recorded synchronized time. In fact, all it does is reproduce the sequence recorded with the Synchro Recorder BB.

See Also: "Synchro Recorder" BB.

Warning

- Reaching the End of the array activates the 'End' output, and deactivates the building block process.


Synchro Recorder BB

 Synchro Recorder
Categorized in Narratives/Streaming Recording

Description

Apply to a BEOBJECT.
Records some input keys events by putting them in a data array which could used with 'Synchro Player' building block.
Synchro Recorder-Player.cmo

Technical Information

On: triggers the process (use [ESC] key to stop the synchro recording, or Reset Initial conditions).

Synchro Array Name: name of the created data array in which synchro informations are stored.
Min: lower end of the range covered by the input keys value.
Max: higher end of the range covered by the input keys value.
Key 0: first key of the synchroneous process.
Key 1: secind key of the synchroneous process.
...
Key N: ...

Remarks

Records some input keys events by putting them in a data array. [ESC] = stops synchro recording.
A new line is added in the created data array each time you press one of the keys specified as parameters.
Colums of the synchro array:
- Time: the time ellapsed between the ON activation and the key pressed.
- Amplitude: value between 'Min' and 'Max' depending on the key pressed. If 'Key 0'=E, 'Key 1'=R and 'Key 2'=T, then if Min=0 and Max=3, pressing 'E' value=1, pressing 'R' value=2, pressing 'T' value=3.
Of course, 'amplitude' value is a Float, therefore you can have non-integer values.
- Length: Duration of key pressing (in milliseconds).

See Also: Synchro Player BB.

Warning

- if [ESC] is not pressed at all, the last line (the one with a null amplitude ) is added when the RESET event occures.
- if you want to produce music synchronizations, you should make sure you didn't record your synchronization sequence with a Time Multiplication Factor different to 1.


Texture Load BB

 Texture Load
Categorized in Narratives/Object Management

Description

Apply to a TEXTURE.
Loads an image file into a Texture.
Texture Load.cmo

Technical Information

In: triggers the process.

Out: is activated when the process is completed.
Failed: is activated when the process has failed.

File: name of the local file to read the texture from.
Slot: slot in which to load the texture.

Use Thread: if selected, the composition loads the file in a new thread. A new bIn, Kill Thread is created.

Remarks

If you need to load several Texture files asynchronously (i.e. not at the same time), use the same instance of the Texture Load BB and the same thread. To do this, select the setting Use Thread. The first time the BB is run, a new process (thread) is created to load the file. You can reuse this thread to load subsequent Texture files. Once all files have been loaded, activate the "Kill Thread" input to stop the thread.


Write Config BB

 Write Config
Categorized in Narratives/Config

Description

Apply to a BEOBJECT.
Writes data to a specific storage place (in Windows, under the Virtools section of the Registry).
Write-Read Config.cmo

Technical Information

In: activates the process.
Out: activates if the section and the entry is found.
Out: activates if the section or the entry is not found.

Section: the name of the section in which to store data ("Key" or "Subkey" in Windows).
State: the name of the entry in which to store data ("Value name" in Windows).
Data: the data to store ("Value data" in Windows); can be of any type expressible as a string.

You can use Write Config to store user specific information, like the player name, high score etc. You can subsequently retrieve this information using Read Config.

See also: Read Config.


Optimizations

Level Of Detail

Get LOD Attribute: Get the LOD Attribute parameters applied to an object.

LOD Character Animation: Sets the level of detail for character animations.

LOD Manager Options: Set and Get information about the LOD Manager.

Set LOD Attribute: Set the LOD Attribute on an object.

Set Progressive Mesh Options: Sets the options of the progressive mesh.

Portals

Portal Management: Automatically hide places which can't be see through visible portals.

Set Portal: Defines a 3D Entity as a portal between 2 places.

System

DX8 Dependency: Add this BB to your Virtools composition to retrieve the DirectX8 rasterizer in the Virtools Web Player.

DX9 Dependency: Add this BB to your Virtools composition to retrieve the DirectX9 rasterizer in the Virtools Web Player.

Get Host Platform: Gets the host platform

Hardware Level: Activates output depending on the hardware acceleration level of the current driver

Statistics: Returns the needed statistics about the system.

Time Settings: Set All Time Settings


DX8 Dependency BB

 DX8 Dependency
Categorized in Optimizations/System

Description

Apply to a BEOBJECT.
Add this BB to your Virtools composition to retrieve the DirectX8 rasterizer in the Virtools Web Player.

Technical Information

This BB ensures that DirectX 8 is available for use in the Virtools Web Player, in order to support DX8 based optimizations.


DX9 Dependency BB

 DX9 Dependency
Categorized in Optimizations/System

Description

Apply to a BEOBJECT.
Add this BB to your Virtools composition to retrieve the DirectX9 rasterizer in the Virtools Web Player.

Technical Information

This BB ensures that DirectX 9 is available for use in the Virtools Web Player, and must be present to support Virtools Shader capabilities (in the Web Player).


Get Host Platform BB

 Get Host Platform
Categorized in Optimizations/System

Description

Apply to a BEOBJECT.
Gets the host platform.
Get Host Platform.cmo

Technical Information

On: activates process.
Exit On: activates when process completes.

Platform: Current platform (represented by an enum). The Platform can be: Windows, Mac, XBox, WinCE, Linux, PSX2.


Get LOD Attribute BB

 Get LOD Attribute
Categorized in Optimizations/Level Of Detail

Description

Apply to a CHARACTER.
Get the LOD Attribute of an Object.
LOD.cmo

Technical Information

See LOD general documentation to learn more about how virtools implement Level Of Detail.

In: triggers the process

LOD Attribute Found: is activated if the object owns a LOD Attribute.
LOD Attribute Not Found: is activated if the object doesn't owns any LOD Attribute.

Multiple Meshes: if TRUE, an algorithm performing mesh swaping according to the object's faces count will be added to the object's LOD process. Those meshes are taken from the object's mesh list. You needn't to order the object's mesh list. The algorithm will find the appropriated mesh amoung the object's mesh list.
Character Animation: if TRUE, an algorithm performing animation reduction will be added to the character's LOD process.
Note: this flag only affect a character and its animations.
As and when a character get smaller on the screen, only principal animated bodyparts will continue being animated. In most case, it is better to simply stop the animation of a character when it is too small on screen.
Patch Mesh: if TRUE, each time the object's current mesh is a Patch Mesh, an algorithm performing tesselation will be added to the object's LOD process, in order to reduce or increase its face count.
Alpha: if TRUE, an algorithm performing alpha transparency according to the object's screen size will be added to the object's LOD process. As this LOD technique has nothing to do with the above techniques, it needs its own controls: see "Screen Alpha Mag" and "Screen Alpha Min" parameters.
Screen Mag: a percentage value, describing the Magnification screen size. It is a proportionnal size of the screen. If the object 2D size (projected on screen) is greater than "Screen Mag", it means the objects is too close to the camera to suffer face reduction, thus a full resolution mesh will be drawn without any face reduction.
Beneath this proportion, the selected LOD techniques will be apply to the object in order to reduce its face count as it get smaller.
Screen Min: a percentage value, describing the Minimum screen size. It is a proportionnal size of the screen. If the object 2D size (projected on screen) is smaller than "Screen Min", it means the objects is too far to continue being reduced, thus no more details from the mesh will be removed, even if the object get smaller.
Above this proportion, the selected LOD techniques will be apply to the object in order to increase its face count as it get bigger.
Faces Mag: a percentage value, describing the maximum face proportion used when object's 2D size get greater than "Screen Mag". In most case this value is 100%. However, for a patch mesh, Faces Mag=100% means iteration=5, thus in order to get a higher tessellation you could use 200%, 500% or more.
Note: the "Faces Mag" value is not only used for faces, but can also be a relevant value if you have checked "Character Animation" parameter. In this case Faces Mag=100% means the animation of all body parts, 30% means the animation of most significant moving body parts, and 0% means the animation of the root and nothing else (except the "Floor Ref" if the character owns one).
Faces Min: a percentage value, describing the minimum face proportion used when object's 2D size get smaller than "Screen Min". For animations, you will typically set Faces Min=0% and use the same value for "Screen Mag" and "Screen Min" parameter in order to get a straight animation cut.
For patch meshes, progressive meshes or multiple meshes techniques, you would typically use a non-null percentage (2% to 10%).
Screen Alpha Mag: same definition than "Screen Mag" except this one is exclusively used for alpha transparency LOD technique.
Screen Alpha Min: same definition than "Screen Min" except this one is exclusively used for alpha transparency LOD technique.


Hardware Level BB

 Hardware Level
Categorized in Optimizations/System

Description

Apply to a BEOBJECT.
Checks the type of 3D graphics acceleration provided by the current video card driver.
Hardware Level.cmo

Technical Information

In: activates the process.

TL: activates if the current driver provides hardware Transform and Lighting acceleration.
Hardware: activates if the current driver provides hardware acceleration.
Software: activates if the current driver provides software acceleration.

Current Api: value of the current Virtools Rasterizer Driver Api.

Remarks

Rasterizer Api values are:

  • Unknown
  • OpenGL
  • DirectX5
  • DirectX7
  • DirectX8
  • DirectX9


Level Of Detail BB

 Level Of Detail
Categorized in Optimizations/Level Of Detail

Description

Apply to a 3DOBJECT.
OBSOLETE.

Chooses the mesh with the appropriate level of detail according to the distance of the camera to the object.

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Min Distance: minimum distance from which the most detailled mesh is displayed.
Max Distance: maximum distance after which the least detailled mesh is displayed.

The mesh with the highest level of detail will be shown when the nearest the object is. When moving away from the object, transitional meshes are swapped so that as distance increases, the level of detail decreases in order to save computational power.
Typically, you'll have to use the 'Add Mesh' behavior to add meshes to the object.
Therefore you'd be able to use the 'Level Of Detail' building block, which will choose between them all, to render the appropriate one, according to its remotness.

Warning

This building block is obsolete and is only included for backwards compatibility.


LOD Character Animation BB

 LOD Character Animation
Categorized in Optimizations/Level Of Detail

Description

Apply to a CHARACTER.
Sets the level of detail for character animations.
LOD Character.cmo

Technical Information

In: triggers the process.

Out: is activated when the process is complete.

Min Distance: minimum distance from which the most detailled mesh is displayed.
Max Distance: maximum distance after which the least detailled mesh is displayed.
Minimum: minimum percentage of animation processed, 0 means only the root and the floor ref (if available) get animated.


LOD Manager Options BB

 LOD Manager Options
Categorized in Optimizations/Level Of Detail

Description

Apply to a BEOBJECT.
Set and Get information about the LOD Manager.
LOD.cmo
LOD Character.cmo

Technical Information

See LOD general documentation to learn more about how virtools implement Level Of Detail.

In: triggers the process
Out: is activated when the process is completed.

Activate: if TRUE, the LOD manager is activated, otherwise it's deactivated.
Deactivating the LOD manager will stop LOD algorithms, and will restore the maximum level of details for each object.
Global LOD Factor: sets the LOD factor by which all faces count will be multiplied for LOD objects.
Build Normals For Progressive Meshes: if TRUE, when performing face reduction using progressive mesh technic the vertices normals are calculated.

Active: if TRUE, the LOD manager is active, otherwise it's not active.
Global LOD Factor: gets the LOD factor by which all faces count will be multiplied for LOD objects.
Build Normals For Progressive Meshes: if TRUE, vertice normal calculation is performed for progressive meshes.

Modify Parameters: check only the pIns that may be relevant to your use. All uncheck parameters won't be modified.


Look At Pos BB

 Look At Pos
Categorized in Optimizations/Portals

Description

Apply to a 3DENTITY.
OBSOLETE - please see 'Look At' instead.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Target Position: vector position to look at.
Following Speed: how fast the 3D Entity should take to look at the given position. The higher the percentage, the faster the 3D Entity will turn to look.
Hierarchy: if TRUE, then this behavior will also apply to the 3D Entity's children.

As you can do the same and better with 'LookAt' building block, the 'LookAtPos' building block is an obsolete one.
This building block needs to be looped if you want to constantly look at the target.

See also: Look At.

Warning

This building block is obsolete and is only included for backwards compatibility. Look At should be used instead.


Portal Management BB

 Portal Management
Categorized in Optimizations/Portals

Description

Apply to a BEOBJECT.
Automatically hide places which can't be see through visible portals.
Portals.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Debug Cameras: the group of cameras on which to apply the portal management, allowing a visual "debugging" of the portal management, when viewing from another camera.
NULL [which is the default value] means the portal management will be processed for the current camera.
Traversal Depth: number of places visible in depth from the current one. 0 means infinity.
This functionality is useful when you have a FOG impeding you to see further than 3 places for example. You would set the "Traversal Depth" pIn to 3 because even if more than three portals can be align from you point of view, the FOG won't let you see further than the third place, and you will save CPU processing.
TransPlace Objects: a group of objects that aren't attached to places (like enemies that goes from place to place) which you want visibility to be managed by the Portal Manager. We detect the places in which those objects are, and if the place is visible, and if the 2D extends by which the place is visible includes the object, then the object can also be visible. Otherwise, it is not rendered, saving a lot a rendering and process time.

Current Places: a collection of all places in which the camera is.
Rendered Places: a collection of all rendered places. Very useful feature if you want to deactivate some objects processing when their corresponding places aren't visible (like a particle systems standing for a torch attached to some wall).
Rendered TransPlace Objects: a collection of all rendered TransPlaces (sub-part of the given pIn "TransPlace Objects" group). Very useful feature if you want to deactivate some objects processing when they aren't rendered any more (like the enemy AI).

Automatically Create Portals: if TRUE, automatically creates all the portals between neighbouring places. Be sure to have shared point positions between places, so the process can find the correct portal bounding box. If points defining the portal area aren't close enough (something like 0.01 unit is the threshold distance) no portal will be created. if there's already a portal between two given places, no additional portal will be created.
This setting is a very useful feature, especially if your level is created on the fly (by some algorithm, or after being created by the player in some editing part of the composition).


Set LOD Attribute BB

 Set LOD Attribute
Categorized in Optimizations/Level Of Detail

Description

Apply to a CHARACTER.
Set the LOD Attribute on an object.
Set LOD Attribute.cmo

Technical Information

See LOD general documentation to learn more about how virtools implement Level Of Detail.

In: triggers the process
Out: is activated when the process is completed.

Multiple Meshes: if TRUE, an algorithm performing mesh swaping according to the object's faces count will be added to the object's LOD process. Those meshes are taken from the object's mesh list. You do not needn't to order the object's mesh list. The algorithm will find the appropriated mesh amoung the object's mesh list.
Character Animation: if TRUE, an algorithm performing animation reduction will be added to the character's LOD process.
Note: this flag only affect a character and its animations.
As and when a character get smaller on the screen, only principal animated bodyparts will continue being animated. In most case, it is better to simply stop the animation of a character when it is too small on screen.
Patch Mesh: if TRUE, each time the object's current mesh is a Patch Mesh, an algorithm performing tesselation will be added to the object's LOD process, in order to reduce or increase its face count.
Alpha: if TRUE, an algorithm performing alpha transparency according to the object's screen size will be added to the object's LOD process. As this LOD technique has nothing to do with the above techniques, it needs its own controls: see "Screen Alpha Mag" and "Screen Alpha Min" parameters.
Screen Mag: a percentage value, describing the Magnification screen size. It is a proportionnal size of the screen. If the object 2D size (projected on screen) is greater than "Screen Mag", it means the objects is too close to the camera to suffer face reduction, thus a full resolution mesh will be drawn without any face reduction.
Beneath this proportion, the selected LOD techniques will be apply to the object in order to reduce its face count as it get smaller.
Screen Min: a percentage value, describing the Minimum screen size. It is a proportionnal size of the screen. If the object 2D size (projected on screen) is smaller than "Screen Min", it means the objects is too far to continue being reduced, thus no more details from the mesh will be removed, even if the object get smaller.
Above this proportion, the selected LOD techniques will be apply to the object in order to increase its face count as it get bigger.
Faces Mag: a percentage value, describing the maximum face proportion used when object's 2D size get greater than "Screen Mag". In most case this value is 100%. However, for a patch mesh, Faces Mag=100% means iteration=5, thus in order to get a higher tessellation you could use 200%, 500% or more.
Note: the "Faces Mag" value is not only used for faces, but can also be a relevant value if you have checked "Character Animation" parameter. In this case Faces Mag=100% means the animation of all body parts, 30% means the animation of most significant moving body parts, and 0% means the animation of the root and nothing else (except the "Floor Ref" if the character owns one).
Faces Min: a percentage value, describing the minimum face proportion used when object's 2D size get smaller than "Screen Min". For animations, you will typically set Faces Min=0% and use the same value for "Screen Mag" and "Screen Min" parameter in order to get a straight animation cut.
For patch meshes, progressive meshes or multiple meshes techniques, you would typically use a non-null percentage (2% to 10%).
Screen Alpha Mag: same definition than "Screen Mag" except this one is exclusively used for alpha transparency LOD technique.
Screen Alpha Min: same definition than "Screen Min" except this one is exclusively used for alpha transparency LOD technique.

Modify Parameters: check only the pIns that may be relevant to your use. All uncheck parameters won't be modified.


Set Portal BB

 Set Portal
Categorized in Optimizations/Portals

Description

Apply to a 3DENTITY.
Defines a 3D Entity as a portal between 2 places.
Portals.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Place 1: first place.
Place 2: second place.
Auto Fit: if TRUE, the portal's position, orientation and scale is set so that it wraps as best as possible the common points between Place 1 and Place 2. Otherwise, the portal's matrix stay unchanged.
The "Auto Fit" parameter is a very useful functionality you can also find in the Place Setup (Popup Menu > Automatic Portal). It saves you a lot of time you would have taken in making the portal fit the corridor, or the doorway between two places.


Set Progressive Mesh Options BB

 Set Progressive Mesh Options
Categorized in Optimizations/Level Of Detail

Description

Apply to a MESH.
Sets the options of the progressive mesh.
LOD.cmo

Technical Information

See LOD general documentation to learn more about how virtools implement Level Of Detail.

In: triggers the process
Out: is activated when the process is completed.

Active: should the progressive mesh be active for this mesh.
GeoMorph: should the geomorphic transition be enabled.
GeoMorph Steps: geomorphic steps (0 means dichotomic transitions).

Activating the progressive mesh can take a long time, depending on the mesh complexity.


Statistics BB

 Statistics
Categorized in Optimizations/System

Description

Apply to a BEOBJECT.
Returns the needed statistics about the system.
Statistics.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Frame Rate: number of frame per second.
Interface Time: estimated time for windows and interface.
Processing Time: estimated time for processing since last frame.
Rendering Time: estimated time for rendering since last frame.
Parameter Operations Time: time taken by parametric operations since last frame.
Animation Management Time: during Behavior Execution time - Time taken in character animations processing.
IK Management Time: during Behavior Execution time - Time taken in IK solving.
Total Behavior Time: total behavior Execution time.
Behavior Execution Time: during Behavior Execution time - Time taken in by code execution of behaviors.
Active Object Executed: number of objects executed since last frame.
Behaviors Executed: number of behaviors executed since last frame.
Building Blocks Executed: number of building blocks executed since last frame.
Links Parsed: number of behavior links parsed since last frame.
Links Delayed: number of Behavior links that have been stored as active in N frames.
Faces Drawn: number of faces drawn in the current frame.
Lines Drawn: number of lines drawn in the current frame.
Points Drawn: number of points drawn in the current frame.
Objects Drawn: number of objects drawn in the current frame.
Vertices Processed: number of vertices transformed for the current frame.

This behavior gives access to several statistical informations as the frame rate, the CPU time... It can be used with the "Text Display" behavior to display these statistics.
Frame Rate: should the building block compute the frame rate ?
General Time: which time statistics should the behavior compute ?
Behavioral: which behavioral statistics should the behavior compute ?
Rendering: which renderal statistics should the behavior compute ?

/* warning: - When the "Statistics" building block stops, the profiler window will stop displaying informations. You'll need to close and open again to profiler to have it working.

Warning

- When the "Statistics" building block stops, the profiler window will stop displaying informations. You'll need to close and open again to profiler to have it working.


Time Settings BB

 Time Settings
Categorized in Optimizations/System

Description

Apply to a BEOBJECT.
Modifies the time settings for the current composition.
Time Settings.cmo

Technical Information

In: activates process.
Out: activates when process completes.

Frame Rate:

  • Free:
    The Frame rate is free, the rendering and behavior processing is called without any wait time.
  • Synchronize to Screen:
    The frame rate cannot be faster than the monitor refresh rate. The frame is rendered synchronously with the VBL to avoid tearing effects. In this mode if the scene is too complicated to be rendered in one frame, the frame rate will be an integer divider of the refresh rate.
  • Limit:
    if you select this option, you must specify a maximum permitted Frame Rate in frame per second. Useful if you want your composition adapted to a specific computer type or when authoring for the web, to free CPU time for other applications.

Frame Limit Value: max permitted frame rate, if limited.
Scale Time Value: increases or decreases scene speed.
Behavior Rate:

  • Linked to Frame Rate:
    If selected, then Behavior Rate will be linked to Frame Rate.
  • Limit:
    Selecting this will separate the Behavioral Rate. You must then select the maximum Behavioral rate in frame per second.

Behavior Limit Value: Limit value, if the behavior rate is limited.
Min Delta Time: Minimum Delta Time that will be passed to behaviors.
Max Delta Time: Maximum Delta Time that will be passed to behaviors.

Min and Max Delta time can be used to avoid large delta times on slow machines or small delta times on fast machines.

Remarks

Time Settings allows you to change the time settings (accessible by right-clicking Play) dynamically and without having to use the interface dialog box.


Particles

CubicParticleSystem: Emits particles from inside a cube

CurveParticleSystem: Emits particles from a curve

CylindricalParticleSystem: Emits particles from a cylinder

DiscParticleSystem: Emits particles from a disc

LinearParticleSystem: Emits particles from a line

ObjectParticleSystem: Emits particles from an object surface

PlanarParticleSystem: Emits particles from a plan

Point Particle System: Emits particles from a point

SphericalParticleSystem: Emits particles from a sphere

Cloth

Cloth System: Creates a cloth system (spring & mass system).


Cloth System BB

 Cloth System
Categorized in Particles/Cloth

Description

Apply to a 3DENTITY.
Creates a cloth system (spring & mass system).
Cloth System.cmo

Technical Information

On: triggers the process.
Off: Stops the process

Exit On: is activated when the process is trigerred.
Exit Off: is activated when the process is stopped.

Hang Array: Array containing the hang point for the cloth. The format of the array is :
Column 1 : [Object] typically a frame used as hang point. Column 2 : [Parameter/Vector2D] the absolute proportionnal position in the cloth (0 - 1.0) / (0 - 1.0) of the hang point. e.g. (0,0) means the top left corner. (1,0) means the top right corner.
Material: Material to be used for the cloth.
Point Mass: Mass of the points of the cloth.
Damping: Damping of the springs between the points.
Tightness: Tightness of the cloth.
Gravity: Vector representing the gravity.
Iterations: Number of iterations done in the constraint solving.

Grid Resolution: The resolution of the cloth, i.e. the number of vertices horizontally and vertically.
Grid Size: World size of the cloth.
Grid Mapping: Cloth mapping factor.
Back Material: Specify a back material if you want your cloth to be both-sided with different materials.

Remarks

The more iterations you give, the more stable your cloth system will be, but the more cpu it will consume.


CubicParticleSystem BB

 CubicParticleSystem
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from inside a cube
CubicParticleSystem.cmo

Technical Information

Particle System which emits particles from within a cube, defined in size by frame dimensions it is attached to. For a complete description of Particle Systems, click here.


CurveParticleSystem BB

 CurveParticleSystem
Categorized in Particles

Description

Apply to a CURVE.
Emits particles from a curve
CurveParticleSystem.cmo

Technical Information

Particle System which emits particles from a curve, in the Y local direction of it. For a complete description of Particle Systems, click here.


CylindricalParticleSystem BB

 CylindricalParticleSystem
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from a cylinder
CylindricalParticleSystem.cmo

Technical Information

Particle System which emits particles from a cylinder shape, oriented following the Z local direction of the frame it is attached to. For a complete description of Particle Systems, click here.


DiscParticleSystem BB

 DiscParticleSystem
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from a disc
DiscParticleSystem.cmo

Technical Information

Particle System which emits particles from a disc, oriented in the Z local direction of the frame it is attached to and defined in size by the X and Y frame dimensions. For a complete description of Particle Systems, click here.


LinearParticleSystem BB

 LinearParticleSystem
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from a line
LinearParticleSystem.cmo

Technical Information

Particle System which emits particles from a line, oriented in the X local direction of the frame it is attached to. For a complete description of Particle Systems, click here.


ObjectParticleSystem BB

 ObjectParticleSystem
Categorized in Particles

Description

Apply to a 3DOBJECT.
Emits particles from an object surface
ObjectParticleSystem.cmo

Technical Information

Particle System which emits particles from random faces of the object its attached to, following faces normal direction. For a complete description of Particle Systems, click here.


Particle Systems BB

 Particle Systems
Categorized in Particles

Description

This is the general documentation for all Particle System BBs.
All Particle System BBs apply to a 3DENTITY.

Technical Information

On: activates the behavior.
Off: disables the behavior.
Freeze: Freezes the particles, for a Matrix-like effect. Reentering by this input "de-freeze" the particles.
Exit On: is activated when the behavior's process is activated.
Exit Off: is activated when the behavior's process is disabled.
Exit Freeze: is activated when the behavior is entered by Freeze.

Emission Delay: Time (in ms) to wait before the next particles' emission. 0 means each frame.
Emission Delay Variance: Modification of the preceding parameter, +/- its value.
Yaw Variance: Max opening angle in the XZ plane. Particles will be given a direction having an angle in this plane between 0 and this value from the Z direction of the emitter.
Pitch Variance: Max opening angle in the ZY plane. Particles will be given a direction having an angle in this plane between 0 and this value from the Z direction of the emitter.
Speed: Speed of the particle representing the actual distance they cover in 1 ms.
Speed Variance: Modification of the preceding parameter, +/- its value.
Angular Speed: Angular Speed of the particle representing the actual angle in radians they cover in 1 ms. (used for Sprite and Object Rendering Mode.)
Angular Speed Variance: Modification of the preceding parameter, +/- its value.
Spreading: Multiplicative Factor applied to the length of the sprites. (used for Oriented Sprite only.)
Spreading Variation: Modification of the preceding parameter, +/- its value.
Lifespan: The lifespan of a particle (in ms).
Lifespan Variance: The random variance of the lifespan (in ms) of individual particles, +/- lifespan value. ie: With a lifespan of 100, a lifespan variance of 15 means a particle may have a lifespan anywhere from 85 to 115 ms.
Maximum Number: Maximum number of particles displayed in the same frame. This number is limited by the Total Number Allocated in the Settings (100 by default), and must be changed there if you wish to override it.
Emission: The number of particles launched at each emission.
Emission Variance: Modification of the preceding parameter, +/- its value.
Initial Size: The initial size of the Particle (used in (Orientable)Sprite and Object Rendering Mode).
Initial Size Variance: Modification of the preceding parameter, +/- its value.
Ending Size: The ending size of the Particle (used in (Orientable)Sprite and Object Rendering Mode).
Ending Size Variance: Modification of the preceding parameter, +/- its value.
Bounce: The bouncing factor of the Particle (used when Deflectors are present.).
Bounce Variance: Modification of the preceding parameter, +/- its value.
Weight: The weight of the Particle (used when Gravity Interactor is present.).
Weight Variance: Modification of the preceding parameter, +/- its value.
Surface: The surface of the Particle (used when Wind or Atmosphere Interactors are present.).
Surface Variance: Modification of the preceding parameter, +/- its value.
Initial Color: The initial Color of the Particle.
Initial Color Variance: Modification of the preceding parameter, +/- its value.
Ending Color: The ending Color of the Particle.
Ending Color Variance: Modification of the preceding parameter, +/- its value.
Texture: The texture (or texture suite) of the Particle.
Initial Texture Frame: The initial Texture animation frame of the Particle.
Initial Texture Frame Variance: Modification of the preceding parameter, +/- its value.
Texture Speed: The speed, in ms, at which the frames are proceeded in the animation.
Texture Speed Variance: Modification of the preceding parameter, +/- its value.
Texture Frame Count: The number of animation frames included in your texture (it must be disposed in 2x2, 3x3, etc... but you don't have to use all the space in the texture (a 7 frame animation will be included in a texture of 3x3 frames).
Texture Loop: Specifies how the animation progress. Looping or not, or Ping-Pong (back and forth)?.

Total Number: The total number of particles allocated in memory.
Particle Rendering: The rendering mode used for the particles.

Point: draw 1 pixel points at the particle place.
Line: draw 1 pixel thin line connecting current particle position to last frame particle position.
Sprite: render a 3D Sprite at the particle place.
Object: render a 3d object chosen randomly in the following group at the particle place.
Oriented Sprite: render a stretched 3d sprite connecting current particle position to last frame particle position.
Radial Sprite: render a stretched 3d sprite connecting the center of world to the current particle position.
Source Blend: The source blending mode of the sprite or object. see Materials/Basic/Set Src Blend.
Dest Blend: The destination blending mode of the sprite or object. see Materials/Basic/Set Src Blend.
Group of Objects: Group of 3D objects to render (in Object Rendering Mode).
Evolutions: This flags determine if you want the particles to evolve over the time, in Color, in Size or in Texture. Disabling unused evolutions make the system faster.
Variances: This flags determine if you want to take in account the variances for the following parameters: Speed, Angular Speed, Lifespan, Emission, Initial Size, Ending Size, Bounce, Weight, Surface, Initial Color, Ending Color, Initial Texture, Ending Texture.
Manage Deflectors: This flags determine which type of deflectors you wish to take into account for this particle system. See Deflectors sections below for a complete description of them.
Message To Deflectors: The message you wish to send to the deflectors touched (one message sent per object per frame maximum).
Manage Interactors: This flags determine which type of interactors you wish to take into account for this particle system. See Interactors sections below for a complete description of them.
Interactors/Deflectors Display: Choose if you want to see the Deflectors/Interactors line meshes.
Trail Count: If 0 or 1 = Standard rendering. If > 1 = Renders a trail for the following modes Line, Sprite, or Oriented Sprite. (Other modes are not affected by this setting.)
Visible On Pause: If checked, particles remain visible when the composition is paused.

Particle System Interactors

Interactors are object attributes that create an influence over particle systems. The first two interactors can be applied to any object you want, even a scene or a texture; otherwise they are applied to frames

Atmosphere: The atmosphere interactor is used to brake the particles, as if there was an air resistance. The equation used is:

(new particle direction) = (particle direction) - (particle direction)*atmosphereforce*(particle surface)
You are supposed to use only one atmosphere interactor per scene but if you use more than one, their effect will be cumulative...

Gravity: The gravity interactor simulates the earth attraction. The equation used is:

(new particle direction).y = (particle direction).y + gravityforce*(particle weight)
You'll have to use a negative number in the gravity force to make the particle fall down, but you can also reverse the gravity by using positive number. You are supposed to use only one gravity interactor per scene but if you use more than one, their effect will be cumulative...

The following interactors are to be used on frames only.

Global Wind: The Global Wind interactor simulates a wind blowing the particles away, from wherever they are in the Z local axis direction of the frame, ie the interactor owner. The equation used is:

(new particle direction) = (particle direction) + (wind Z direction)*windforce*(particle surface)
A negative wind force will make the particle go into the wind. You can use as many global wind attributes as you like, their effect will be cumulative...

Local Wind: The Local Wind interactor simulates a wind blowing the particles away, only when they are in the cylinder which have the X and Y axis of the interactor owner as basis, in the Z local axis direction of the interactor owner. The equation used is:

(new particle direction) = (particle direction) + attenuation*(wind Z direction)*windforce*(particle surface)
    with: attenuation = 1/(1+(particle distance form the emitter basis)*decayforce
A negative wind force will make the particle go back the wind direction. The higher the decay force, the less the particles will be affected by the interactor when they are away from it.

Magnet: The Magnet interactor simulates a magnet attracting (or repulsing) the particles away, according to their distance. The equation used is:

t = 1 + SquareDistance((particle position) - (magnet position))
    (new particle position) = (magnet position) + ((particle position) - (magnet position))*(t/(t+magnetforce))
The nearer are the particles, the faster they move. The greater the force is, the faster they move too. A negative magnet force will repulse the particle.

Vortex: The Vortex interactor simulates a vortex field making the particles turn on its axis, with their speed according to their distance. The equation used is:

t = 1/(1 + SquareDistance((particle position) - (vortex position)))
    (new particle position) = Rotate((particle position),(around vortex position),t*xforce,t*yforce,t*zforce)
The nearer are the particles from an axis, the faster they rotate. The greater the force is, the faster they rotate too. A negative force will make the particle turn counterclockwise.

Disruption Box: The Disruption Box interactor simulates a volume which disturb the particle direction.The equation used is:

if(particle in box) (new particle direction) = (particle direction) + boxdisruptionforce*(random point in box - (particle position))
The greater the force is, the faster the particles will move away.

Mutation Box: The Mutation Box interactor allows particle penetrating its volume to mutates in size, color and texture. You can also choose the speed at which it will mutate. The greater the speed is, the faster the particles will reach its new form.

Tunnel: The Tunnel interactor conduct particles nearby thru the tunnel, accelerating or decelerating them. You can set the velocity aimed by the particles travelling in the tunnel, the absorption radius of the tunnel, the attraction shape modifies the force of the attraction, the attraction speed, and finally the attraction direction which represent a force modifying the direction of the particle itself.

Projector: The Projector interactor transforms the color of the particles passing in front of it. You apply it on a sprite 3D which texture will be used for the projection. The attributes takes a vector which x means the field of view (in radian) of the projection, the y is the aspect ratio of the projection and the z is the back plane distance.

Particle System Deflectors

Deflectors are attributes applied to frames or objects that create obstacles for particle systems. For each particle, we test if between the last frame and the current frame, it touched an obstacle and, if so, we change its direction and position according to the following equation:

    dp = (particle direction).(impact normal)
    (new particle direction) = ( (particle direction)-(impact normal)*dp ) * (deflector friction) + (impact normal)*dp*(particle bounce)*(deflector response)

Object Deflector: The Object deflector attribute is to be applied on a 3DEntity with a mesh and define it as an obstacle for the particles. The more faces the object has, the slower the processing will be... So don't abuse it.

Other Deflectors: The Plane, Infinite Plane, Cylinder, Sphere, Box deflectors are applied to frames and can be geometrically changed by applying (non)uniform scale on the frame. A line mesh representing the deflectors shape is created to help you visualize it.

Output Impacts: When checking this flag a new input and a new output are created, as four output parameters. When a particle touches a deflector, it triggers the "Impact Loop Out" output, allowing you to retreive information on the collision such as the position and the normal of the impact (in world coordinates), the entity touched (must be a deflector) and the texture coordinates of the impact. If many impact occur at the same frame, you can iterate on all of them by re-entering by the "Impacts Loop In" input at the SAME frame (use link delay of 0).

Die On Impact: When checked, allow the particles touching a deflector to disappear (nevertheless they give impact information if Output Impacts is checked.)


PlanarParticleSystem BB

 PlanarParticleSystem
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from a plane
PlanarParticleSystem.cmo

Technical Information

Particle System which emits particles from a plane, which normal is the Z local direction of the frame it is attached to and defined in size by the X and Y frame dimensions. For a complete description of Particle Systems, click here.


Point Particle System BB

 Point Particle System
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from a point
Point Particle System.cmo

Technical Information

Particle System which emits particles from a point, in the Z local direction of the frame it is attached to. For a complete description of Particle Systems, click here.


SphericalParticleSystem BB

 SphericalParticleSystem
Categorized in Particles

Description

Apply to a 3DENTITY.
Emits particles from a sphere
SphericalParticleSystem.cmo

Technical Information

Particle System which emits particles from a sphere, which size is defined by the X,Y and Z frame dimensions. The particles directions are the normals at the point they are generated on the surface of the sphere. For a complete description of Particle Systems, click here.


Shaders

General

Build Tangent Space: Asks the mesh to build (or remove) tangent space (used for bump mapping for example).

Get Shader Capabilities: Gets shader capabilities of hardware.

Set Shader Parameters: Sets one or more parameters of the material's shader.

Set Shader Technique: Sets the shader material's technique.

Rendering

Combine RT Views: Combines one or more RT Views within a destination RT View using a shader.

Render Scene In RT View: Renders the scene into a RenderTarget View.


Build Tangent Space BB

 Build Tangent Space
Categorized in Shaders/General

Description

Apply to a MESH.
Asks the mesh to build (or remove) tangent space (used for bump mapping for example).

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Remove: removes the flag on the mesh if checked (see below).

This building block ensures that the mesh stores tangent space on each vertex. The tangent space is made up of three vectors (tangent, normal and binormal vector) and is equivalent to a referential (right, up and direction vector) stored on each vertex. This building block sets (or removes) a flag on the mesh to indicate if it should automatically compute this information. A vertex shader can then retrieve this data, which is send as two additional 3D texture coordinates.

//--- Bump Vertex Shader Function prototype
BumpVSOut BumpVS
   (
      float4 Pos : POSITION;
      float3 Norm : NORMAL;
      float2 TexCoord : TEXCOORD0;
      float3 Tangent : TEXCOORD1;
      float3 Binorm : TEXCOORD2;
   )
{

....

}

Note: when a mesh owns tangent spaces, TEXCOORD0, TEXCOORD1 and TEXCOORD2 are reserved to TexCoord, Tangent, and Binormal UV sets. So if an additional channel is applied to the mesh, it will be accessed through TEXCOORD3.


Combine RT Views BB

 Combine RT View
Categorized in Shaders/Rendering

Description

Apply to a BEOBJECT.
Renders a 2D rectangle into a RT View using a Shader to combine up to 8 RT Views.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Dest RT View: defines the destination RT View in which the shader will render the combined rectangle.
A RenderTarget View is identified by a texture in which the rendering will take place along with the rectangle in which the rendering should be done. If the texture is set to NULL the rendering takes place directly on the screen.
An invalid rectangle (i.e. a rectangle for which left component is greater than or equal to the right component, and for which the top component is greater than or equal to the top), refer to the full texture rectangle.
Render Options: render flags:
Background Sprites: background 2D Sprites are to be rendered.
Foreground Sprites: foreground 2D Sprites are to be rendered.
Use Camera Ratio: render context size is automatically set using current camera aspect ratio and Window Rectangle (Horizontal Size has priority).
Clear ZBuffer: clears ZBuffer.
Clear Back Buffer: clears Back Buffer.
Clear Stencil Buffer: clears Stencil Buffer.
Buffer Swapping: swap back to front buffers.
Clear Only Viewport: do not clear entire device, only viewport (device=window, viewport=subpart in window where 3d objects are rendered [for instance think about 16/9 rendering]).
Vertical Sync: Wait for Vertical Blank before blitting (transfer image). This option is only available when rendering to the screen (destination RT view is NULL), not when rendering to a texture
Disable Rendering: do not draw 3D scene or 2D sprites.
Disable 3D Only: do not draw 3D scene (draw only 2D sprites).
Background Color: background color used when clearing the render target.
Shader: name of the shader to be used to render the rectangle.
Technique: name of the technique to use to render the rectangle (taken from the list of the shader above).

View 0: RT View standing for the TEXTURE0 semantic, and which rectangle stands for the first UV set.
View 1: RT View standing for the TEXTURE1 semantic, and which rectangle stands for the second UV set.
...
View n: RT View standing for the TEXTUREn semantic, and which rectangle stands for the Nth UV set.

Add...: input parameters can be added manually using the BB's construct contextual menu. Each parameter name and type must exactly correspond to the name and type of the exposed manual variable that gets the value in the vertex or pixel shader source. See the Set Shader Parameters BB for more details on adding parameters.

View Count: defines how many RT View pIns must be created. The shader will receive as many UV sets as there is RT View pIns exposed in the building block. There can be up to 8 exposed RT View pIns.
Viewports are Homogeneous: if TRUE, the rectangle coordinates given by the user are supposed to be homogeneous. It means that a (1, 1) coordinate points to the texture's bottom-right corner and a (0.5, 0.5) coordinate points to the texture's center.

Build Exposed Params: check this flag and validate to see all exposed manual variables appear as pIns of this building block. Valid pIns (those which name matches an exposed parameter of the shader) will not be destroyed, while pIns which name cannot be recognized as an exposed parameter of the shader will be destroyed.
Note: once the job is done, this setting is reset to FALSE, so you can check it later to update the building block's pIns.

Combine RT View building block draws a rectangle into a RT View (can be the screen). The rectangle acts like a mesh made up of N channels, where N is the number of RT Views exposed in the building block as pIns. The way those pseudo-channels are combined and mixed together is defined by the Shader and Technique pIns.

Many Post-Processing effects are achieved using the Combine RT Views building block, see the Technical Samples in the Virtools Minisite for more information.

Please refer also to the shader's documentation (particularly the shader building blocks part).


Get Shader Capabilities BB

 Get Shader Capabilities
Categorized in Shaders/General

Description

Apply to a BEOBJECT.
Gets shaders related hardware capabilities.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Platform: Current platform on which the application is running.
DX Version: DirectX version of the current rasterizer. 0 if the rasterizer in not DirectX based.
VS Version: Supported Vertex Shader version (1.1, 2.0, ...etc).
PS Version: Supported Pixel Shader version (1.1,1.2,1.3,1.4,2.0, ...etc).

This building block returns information about the shader capabilities of the current graphics device. Current shader implementation supports only the DirectX 9 Rasterizer. This building block can be used to check for the availability of a specific version of vertex or pixel shaders.


Render Scene in RT View BB

 Render Scene
Categorized in Shaders/Rendering

Description

Apply to a BEOBJECT.
Renders the scene into a RenderTarget View

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Target View: A RenderTarget View is identified by a texture in which the rendering will take place along with the rectangle in which the rendering should be done. Render Scene BB does not allow NULL textures.
An invalid rectangle (i.e. a rectangle for which left component is greater than or equal to the right component, and for which the top component is greater than or equal to the top), refer to the full texture rectangle.
Render Options: render flags:
Background Sprites: background 2D Sprites are to be rendered.
Foreground Sprites: foreground 2D Sprites are to be rendered.
Use Camera Ratio: render context size is automatically set using current camera aspect ratio and Window Rectangle (Horizontal Size has priority).
Clear ZBuffer: clears ZBuffer.
Clear Back Buffer: clears Back Buffer.
Clear Stencil Buffer: clears Stencil Buffer.
Buffer Swapping: swap back to front buffers.
Clear Only Viewport: do not clear entire device, only viewport (device=window, viewport=subpart in window where 3d objects are rendered [for instance think about 16/9 rendering]).
Vertical Sync: Wait for Vertical Blank before blitting (transfer image). This option is only available when rendering to the screen (destination RT view is NULL), not when rendering to a texture
Disable Rendering: do not draw 3D scene or 2D sprites.
Disable 3D Only: do not draw 3D scene (draw only 2D sprites).
Background Color: background color used when clearing the render target.
Background Texture: background texture used when clearing the render target.
Camera: camera from which the image should be rendered.
(CubeMap) Render Face by Face: if TRUE, render to a different cube map face each time the building block is triggered. If false render to all 6 cubemap faces.
Update System Memory: if TRUE, transfers the rendering to the texture system memory (used for procedural texture update, screenshot saving,...).
Overriding Material: forces the rendered objects of the scene to be drawn as if they all had the same material (used for example to render depth pixels for Depth Of Field). if NULL this pIn has no effect on the building block.

This building block renders the scene into a texture. It is very similar to the Texture Render BB but adds the capacity to render in a sub-part of the texture, as well as the capacity to render the objects as if they all had the same material.

Please refer also to the shader's documentation (particularly the shader building blocks part).

Warning

- If you use the RenderTarget texture on a mesh which UV tilling mode is set to Border or Clamp, you may not be able to see anything if the mesh's UV aren't bound to [0,1] range.
- On XBox a RenderTarget texture is force to be linear, and linear texture cannot tile (so you'd better map the mesh within [0,1] ranges).


Set Shader Parameters BB

 Set Shader Parameters
Categorized in Shaders/General

Description

Apply to a MATERIAL.
Sets one or more parameters of the material's shader.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Add...: input parameters can be added manually using the BB's construct contextual menu. Each parameter name and type must exactly correspond to the name and type of the exposed manual variable that gets the value in the vertex or pixel shader source.

Build Exposed Params: check this flag and validate to see all exposed manual variables appear as pIns of this building block. Valid pIns (those which name matches an exposed parameter of the shader) will not be destroyed, while pIns which name cannot be recognized as an exposed parameter of the shader will be destroyed.
Note: once the job is done, this setting is reset to FALSE, so you can check it later to update the building block's pIns.

 This building block can be used to set the material shader parameters value just as it can be done in the Material Setup.

For instance to set the parameter light0, you have to add a parameter name "light0" of type Vector to the Set Shader Parameter BB:


Set Shader Technique BB

 Set Shader Technique
Categorized in Shaders/General

Description

Apply to a MATERIAL.
Sets the shader material technique.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Technique: Name of the technique to use for the given material.
Find Next Valid Technique: When the chosen technique is not valid on the current rendering device, this parameter can be set to TRUE so that the engine searches for the next valid technique to use for the shader.

Set Shader Technique building block can be used to set the material shader technique value just as it can also be done in the Material Setup (below).


Sounds

3D Properties

Position Sound: Attaches a sound to an object.

Set Sound Cone Values: Control the cone shape of the 3D sound.

Set Sound Range: Control the range of the 3D sound.

Audio CD

CD Player: Plays soundtracks from an audio CD (v2).

Basic

Play Sound Instance: Plays the totality of a sound once, optionally attaching it to an object.

Wave Player: Plays a Wave Sound File, with possible fade in and/or fade out; the fades values are done in seconds;

Control

Panning Control: Sets the panning for a sound, regardless of whether it is playing or not.

Pitch Control: Sets the pitch frequency for a sound, regardless of whether it is playing or not.

Volume Control: Controls the volume of a sound, either it is playing or not.

Global

Set Listener: Sets the listener of the sound.

Set Listener Properties: Controls the listener properties.

Midi

Midi Player: Plays/Stops a MIDI sound.

Properties

Set Sound Type: Tells if a sound is to be render in background or in 3d space.


CD Player BB

 CD Player
Categorized in Sounds/Audio CD

Description

Apply to a BEOBJECT.
Plays soundtracks from an audio CD (v2).
CD Player.cmo

Technical Information

Play: starts the CD Player.
Stop: stops the CD Player.
Pause/Resume: pauses or resumes playback.

First track: number of the first track to be played.
Last track: number of the last track to be played.
Starting Time: time on the first track when playback should start.
Ending Time: time before the end of the last track when playback should end.

The first track of a CD is numbered 1, and not 0 (zero).
To play track 1, from beginning to end, the parameters would be as follows:
First Track = 1
Last Track = 1
Starting Time = 0
Ending Time = 0


Fade In BB

 Fade In
Categorized in Sounds/Global

Description

Apply to a BEOBJECT.
OBSOLETE

Fades in sound(s).

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Fade Delay: time in milliseconds during which the sound(s) are to be faded in.

Elapsed Time: time elapsed in miliseconds since the start of the fade in.

This behavior should be used in conjunction with another building block, such as Wave Player.

Warning

This building block is obsolete and is only included for backwards compatibility.


Fade Out BB

 Fade Out
Categorized in Sounds/Global

Description

Apply to a BEOBJECT.
OBSOLETE

Fades out sound(s).

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Fade Delay: time in milliseconds during which the sound(s) are to be faded out.

Elapsed Time: time elapsed in miliseconds since the start of the fade out.

This behavior should be used in conjunction with another building block, such as Wave Player.

Warning

This building block is obsolete and is only included for backwards compatibility.


Get Sound Spectrum BB

 Get Sound Spectrum
Categorized in Sounds/Processing

Description

Apply to a WAVESOUND.
Performs sound spectrum analysis.
Get Sound Spectrum.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Start Frequency: Start of the requested frequency range.
End Frequency: End of the requested frequency range.

Value: Average sound volume for frequency range.

Band Count: The number of bands used to perform spectrum analysis.

Use this behavior building block to perform frequency analysis on a digital sound.


Midi Player BB

 Midi Player
Categorized in Sounds/Midi

Description

Apply to a MIDISOUND.
Plays/Stops a MIDI sound.
Midi Player.cmo

Technical Information

Play: Starts playback.
Stop: Stops playback.
Pause/Resume: Pause the playback if it is playing, pauses it otherwise.

Out Play: is activated when the Play input is triggered.
Out Stop: is activated when the Stop input is triggered.
Out Pause/Resume: is activated when the Pause/Resume input is triggered.


Panning Control BB

 Panning Control
Categorized in Sounds/Control

Description

Apply to a WAVESOUND.
Sets the panning for a sound, regardless of whether it is playing or not.
Panning Control.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Position: range is between -100 (left) and 100 (right), with 0 (zero) being the center.


Pitch Control BB

 Pitch Control
Categorized in Sounds/Control

Description

Apply to a WAVESOUND.
Sets the pitch frequency for a sound, regardless of whether it is playing or not.
Pitch Control.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Frequency: pitch frequency, in a normal range between 0.5 and 2.0, with 1.0 being the default frequency.


Play Sound Instance BB

 Play Sound Instance
Categorized in Sounds/Basic

Description

Apply to a WAVESOUND.
Plays the totality of a sound once, optionally attaching it to an object.
Play Sound Instance.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

2D: is the sound is to be played in 2D. If so, the subsequent input will be of no use.
Object: object to which the sound is to be attached.
Position: position of the sound.
Direction: direction of the sound.
Min Delay(ms): minimum delay between twice the same sound.
Volume: controls the volume. 100% means full volume.

This behavior allows a new instance of the same sound to be played whilst the original sound is still playing, making the two sounds overlap.
Th position and direction are in the referential of the attached object, or in the world if no object is attached.
This building block is typically used for repeated sounds, such as an echo or gun shots.

Warning

The sound to be played must not be streamed.


Position Sound BB

 Position Sound
Categorized in Sounds/3D Properties

Description

Apply to a WAVESOUND.
Attaches a sound to an object.
Position Sound.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Object: object to which the sound will be attached (NULL = world).
Position: position of the sound, in the referential of the attached object, or in the world.
Direction: direction of the sound, in the referential of the attached object, or in the world.

If the object is different from NULL, the sound will follow it.


Set Listener Properties BB

 Set Listener Properties
Categorized in Sounds/Global

Description

Apply to a BEOBJECT.
Controls the listener properties.
Set Listener Properties.cmo

Technical Information

In: triggers the process
Out: activates when the process completes.

Global Gain: sets the global volume of the sound system, in a range of 0.0 to 1.0, with 1.0 being the highest.
RollOff Factor: Rolloff is the amount of attenuation that is applied to sounds, based on the listener's distance from the sound source. Virtools Sound System can ignore rolloff, exaggerate it, or give it the same effect as in the real world, depending on a variable called the rolloff factor. The rolloff factor can range from 0.0 to 10.0 A value of 0.0 means no rolloff is applied to a sound. Every other value represents a multiple of the real-world rolloff. 1.0 is the default.
Doppler Factor: Virtools Sound System automatically creates Doppler shift effects for any buffer or listener that has a velocity. Effects are cumulative: if the listener and the sound buffer are both moving, the system automatically calculates the relative velocity and adjusts the Doppler effect accordingly. The Doppler factor can range from 0.0 to 10.0. A value of 0.0 means no Doppler shift is applied to a sound. Every other value represents a multiple of the real-world Doppler shift. 1.0 is the default.
Distance Factor: Virtools Sound System (DirectSound) uses meters as the default unit of distance measurements. If your content does not use meters, it can set a distance factor, which is the number of meters in a vector unit. If you want to work in feet, set 0.3048 to this value. The distance factor can range from 0 to 10. 1 is the default.


Set Listener BB

 Set Listener
Categorized in Sounds/Global

Description

Apply to a BEOBJECT.
Sets the listener of the sound.
Set Listener.cmo

Technical Information

In: activates the process.

Out: is activated when the process is completed.

Listener: specifies the listener of the sound. NULL sets it to the current camera.


Set Priority BB

 Set Priority
Categorized in Sounds/Properties

Description

Apply to a WAVESOUND.
OBSOLETE.

Controls the Priority of a sound, either it is playing or not.

Technical Information

In: activates the process.
Out: is activated when the process is completed.

Priority: Controls the Priority. [0.0 - 1.0] with 1.0 being the higher priority.

Warning

This building block is obsolete and is only included for backwards compatibility.


Set Sound Cone Values BB

 Set Sound Cone Values
Categorized in Sounds/3D Properties

Description

Apply to a WAVESOUND.
Control the cone shape of the 3D sound.
Set Sound Cone Values.cmo

Technical Information

In: triggers the process
Out: activates when the process completes.

Inside Angle: This is the angle within which the sound is at its normal volume.
Outside Angle: This is the angle outside of which the sound is at its outside volume.
Outside Cone Volume: Cone outside volume for this sound.


Set Sound Range BB

 Set Sound Range
Categorized in Sounds/3D Properties

Description

Apply to a WAVESOUND.
Controls the range of the 3D sound.
Set Sound Range.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Min Distance: Distance from the listener below which the sound is at full volume.
Max Distance: Distance from the listener after which the sound is at zero volume.


Set Sound Type BB

 Set Sound Type
Categorized in Sounds/Properties

Description

Apply to a WAVESOUND.
Sets the Sound Type to Background (2D) or Point (3D).
Set Sound Type.cmo

Technical Information

In: activates the process
Out: is activated when the process is complete.

RenderMode: Sound Type to use when playing the sound:
- Background: the sound is played the same regardless of the listener's position or orientation.
- Point: the sound is played from a specific position in 3D space.

Remarks

This BB is often used when loading sounds into a composition at run-time - the CreateObject BB creates a WaveSound object, you set the type with this BB and finally you load the sound file with the Sound Load BB.

Warning

The sound type for a sound cannot be changed at run-time for a sound that has already been loaded; you will need to reload the sound as described above. Note that if you try to change the sound type when a sound is actually playing, playback of the sound stops.


Sound Manager Setup BB

 Sound Manager Setup
Categorized in Sounds/Global

Description

Apply to a BEOBJECT.
OBSOLETE.

Control the sound projection cone of the 3D sound.

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Distance Factor: Virtools Sound System (DirectSound) uses meters as the default unit of distance measurements. If your content does not use meters, it can set a distance factor, which is the number of meters in a vector unit. If you want to work in feet, set 0.3048 to this value. The distance factor can range from 0 to 10. 1 is the default.
RollOff Factor: Rolloff is the amount of attenuation that is applied to sounds, based on the listener's distance from the sound source. Virtools Sound System (DirectSound) can ignore rolloff, exaggerate it, or give it the same effect as in the real world, depending on a variable called the rolloff factor. The rolloff factor can range from 0 to 10. A value of 0 means no rolloff is applied to a sound. Every other value represents a multiple of the real-world rolloff. 1 is the default.
Global Tone: sets the tonal equalization for the sound system, in a range of 0.0 to 1.0, with 1.0 being the highest.
Global gain: sets the global volume of the sound system, in a range of 0.0 to 1.0, with 1.0 being the highest.
Doppler Factor: Virtools Sound System (DirectSound) automatically creates Doppler shift effects for any buffer or listener that has a velocity. Effects are cumulative: if the listener and the sound buffer are both moving, the system automatically calculates the relative velocity and adjusts the Doppler effect accordingly. The Doppler factor can range from 0 to 10. A value of 0 means no Doppler shift is applied to a sound. Every other value represents a multiple of the real-world Doppler shift. 1 is the default.

Warning

This building block is obsolete and is only included for backwards compatibility.


Volume Control BB

 Volume Control
Categorized in Sounds/Control

Description

Apply to a WAVESOUND.
Controls the volume of a sound, either it is playing or not.
Volume Control.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Volume: controls the volume. 100% means full volume.


Wave Player BB

 Wave Player
Categorized in Sounds/Basic

Description

Apply to a WAVESOUND.
Plays a Wave Sound File, with optional fade in and/or fade out (in milliseconds).
Wave Player.cmo

Technical Information

Play: starts playing the sound file.
Stop: stops playing the sound file.
Pause/Resume: pauses/resumes the playback of the sound file.

Start Playing: activated when the sound starts playing.
Stop Playing: activated when the sound stops playing.
Paused/Resumed: activated when the sound is paused or resumed.

Fade In: fade in time, in milliseconds.
Fade Out: fade out time, in milliseconds.
Loop: if selected, the sound is looped.

Remarks

Fade In is used only when Play is activated, and Fade Out when Stop is activated.


Visuals

2D

Change Sprite Slot: Changes the current slot of the Sprite.

Display Progression Bar: Displays a progression bar.

Edit 2D Entity: Changes the 2d entity parameters.

Gauge: Displays a progression bar.

Set 2D Material: Sets the material of a 2D Entity.

Set 2D Parent: Sets the Parent of a 2D Entity.

Set 2D Position: Set the position of a 2D Entity

Set Color Key 2D: Sets the transparent transparence color key for a sprite.

Set Rectangles: Set the destination and/or source rectangles of a 2DEntity

FX

Blink: Blinks the 3D Entity (alternates between show and hide).

Global Blur: Apply a global blur on all the objects rendered.

Make Transparent: Makes a Render Object (3D or 2D Entity) Transparent.

Mark System: Creates marks (single or continuous) on surfaces.

Motion Blur: Performs a Motion Blur when the 3D Entity is moving.

Planar Filter: Sets an filter color and an additionnal color to recover all the scene.

Planar Reflection: Creates a reflection on a plane of objects in a group.

Render Curve: Renders the curve with a specific material.

Replace Rendering: Replace the rendering of a mesh's material just before it's rendering.

Set Render Order: Tells the object to be displayed FIRST, LAST, or in a normal way.

Set Z Buffer: Change the way the object read and write into the ZBuffer.

Solid Trail: Create a Solid Trail following the 3D Entity when it's moving.

Texture Render: Render an image in the texture of a 3D Entity.

Use Z information: Hides the object but uses its Z information during rendering

Vertex Render: Renders the object with a specific sprite at the vertices positions.

Volumetric Fog: Volumetric Fog.

Shadows

Planar Shadow: Display planars shadows of selected objects projected from a light.

ShadowCaster: Projects a shadow of the target object.

ShadowStencil: Use the stencil buffer to create a shadow volume that cast on objects using the ShadowStencil attribute.

Simple Shadow: Display a little soft shadow on floors beneath the object.

Show-Hide

Hide: Hides a 2D/3D Entity, a Mesh or a Group

Hide Hierarchy: Hides hierarchically an entity

Show: Shows a 2D/3D Entity, a Mesh or a Group

Show Mouse Cursor: Show/Hide the mouse cursor.

Show Object Information: Shows the bounding box and the normals of a 3D Entity.

Sprite

Set 3DSprite Mode: Sets the orientation mode of the 3D Sprite.

Sprite Movie Player: Plays a movie in a 2d Sprite (avi)

Sprite Multi Angle: Replaces the 3D Entity by a 3D sprite.


Blink BB

 Blink
Categorized in Visuals/FX

Description

Apply to a 3DENTITY.
Blinks the 3D Entity (alternates between show and hide).
Blink.cmo

Technical Information

In: activates the behavior.
Out: is activated when the process is completed.

Hidden Frames: number of frames the 3D Entity remains hidden (not rendered).
Shown Frames: number of frames the 3D Entitity is shown (rendered).

This behavior needs to be looped.


Change Sprite Slot BB

 Change Sprite Slot
Categorized in Visuals/2D

Description

Apply to a SPRITE.
Changes the current slot of the Sprite.
Change Sprite Slot.cmo

Technical Information

In: activates the behavior.
Out: is activated when the process is completed.

Slot Index: index of the new Sprite slot.

Slots are simply different images contained in a Sprite.
See the Setup View for Sprites.


Display Progression Bar BB

 Display Progression Bar
Categorized in Visuals/2D

Description

Apply to a BEOBJECT.
Displays a progression bar.
Display Progression Bar.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates if the BB is activated by the On bIn.
Exit Off: activates if the BB is deactivated by the Off bOut.

X: horizontal position of the first progression bar (Empty Bar ()).
Y: vertical position of the first progression bar (Empty Bar ()).
Bar Progression: amount of progression bar to show (between 0 and 100%).

Empty Bar (): the 2D Sprite to use to represent the 'Empty Bar' (the container)
Full Bar (): the 2D Sprite to use to represent the 'Full Bar' (the content)

Remarks

The 2D Sprite specified in the Empty Bar () setting is always displayed, with all or a part of the 2D Sprite specified in the Full Bar displayed on top. The amount of the the Full Bar () 2D Sprite depends on the percentage given by the Bar Progression pIn. You do not have to specify an 'Empty Bar' if you don't need one. This BB should only be used to display horizontal progression bars.


Display Score BB

 Display Score
Categorized in Visuals/2D

Description

Apply to a BEOBJECT.
OBSOLETE

Displays a score in 2d

Technical Information

On: Activates the Score Display.
Off: Deactivates the Score Display.

Exit On: This output is activated after entering by 'On'.
Exit Off: This output is activated after entering by 'Off'.

X: Horizontal Position of the first score digits.
Y: Vertical Position of the first score digits.
Score: Score to be displayed (eg: 100, 300 or even 100000 !).

- All the digits must be loaded in the system memory (you don't have to load them in the card memory like the other textures). To do so Drag'n Drop the image in the 3d view with the Shift Key.
- The digits have to contain the corresponding index. (eg: score_0, score_1, score_2, ... etc or 0score, 1score, 2score). - You don't have to specify all the digits ... just give the name of the first sprite (the Zero one) in the settings of 'Display Score'.

Warning

This building block is obsolete and is only included for backwards compatibility.


Edit 2D Entity BB

 Edit 2D Entity
Categorized in Visuals/2D

Description

Apply to a 2DENTITY.
Changes the 2d entity parameters.
Edit 2D Entity.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Pos X: Horizontal position of the 2d Entity.
Pos Y: Vertical position of the 2d Entity.
Z Order: display order relatively to the other 2d entity.
Background: Checked = Behind every object of the scene, Not Checked = (Foreground) In front of every object of the scene.
Pickable: Checked = The sprite can be picked.
Clip To Parent: Checked = The sprite will be clipped to the extents of its parent.
Stick Left, Right, Top, Bottom: Checked = Stick to chosen borders of the parent at the current distance.

Edited Components: position, background, pickable, parent alignment, z ordering, size, clip to parent. Select which components you want to modify through the building block.


FPS BB

 FPS
Categorized in Visuals/FX

Description

Apply to a BEOBJECT.
OBSOLETE - see Statistics BB.

Writes in the output the FPS (Frames Per Second).

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Fps: number of frames par second.
This behavior can be used with the "Text Display" behavior to display the current frame rate.

Warning

This building block is obsolete and is only included for backwards compatibility.


Gauge BB

 Gauge
Categorized in Visuals/2D

Description

Apply to a 2DENTITY.
Changes the size of a 2DEntity in any direction according to a percentage.
Gauge.cmo

Technical Information

On: activates the process.
Off: deactivates the process.
Exit On: activates when the process activates.
Exit Off: activates when the process deactivates.

Bar Progression: how much the target should stretch. At 50% the target is half it's full size; at 100% the target is full size.
Orientation: direction to stretch the target. By default this is to the right.
Stretch: if selected, the bitmap associated to the target can stretch (and so be at more than 100% of its full size).

Remarks

The Gauge BB allows you to display the status of a value visually. For example, you could create a variable that represents life and paste a shortcut to Bar Progression, so that you can constantly display the status of that variable.

Warning

If the target is a 2D Sprite, Stretch is not selected and Bar Progression >100%, the bitmap will not repeat. However the bitmap does repeat with 2D Frames.


Global Blur BB

 Global Blur
Categorized in Visuals/FX

Description

Apply to a BEOBJECT.
Apply a global blur on all the objects rendered.
Global Blur.cmo

Technical Information

On: enables the global blurring.
Off: disables it.

Material: Clearing Material.

Warning

- This behaviors works well only if you do not have a background, but objects floating in space. In fact, all it does is prevent the screen clear at each frames, and draw a transparent frame on top using the given material, or the background material if none is given before the render of the next frame.
- This behavior will work better in 32bits because of colors imprecision in 16bits.


Hide 2D Entity BB

 Hide 2D Entity
Categorized in Visuals/Show-Hide

Description

Apply to a 2DENTITY.
OBSOLETE - replaced by Hide BB.

Hides a 2D Entity

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Warning

This building block is obsolete and is only included for backwards compatibility.


Hide 3D Entity BB

 Hide 3D Entity
Categorized in Visuals/Show-Hide

Description

Apply to a 3DENTITY.
OBSOLETE. Replaced by Hide.

Hides a 3D Entity

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.


Hide BB

 Hide
Categorized in Visuals/Show-Hide

Description

Apply to a BEOBJECT.
Hides a 2D/3D Entity, a Mesh or a Group.
Show Hide.cmo

Technical Information

In: activates the process
Out: activates when the process completes.

Hierarchy: if TRUE, then this building block will also apply to the 2D/3D element's children.

Remarks

Hide replaces Hide 2D Entity and Hide 3D Entity.

See Also: Show, Hide Hierarchy.


Hide Hierarchy BB

 Hide Hierarchy
Categorized in Visuals/Show-Hide

Description

Apply to a BEOBJECT.
Hides hierarchically an entity
Show Hide.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

This behavior will hide the object and all its children in one operation. This makes the rendering faster than hiding each object in the hierarchy separately, like the behavior Hide with the hierarchy flag does.

See Also: Show.


Make Transparent BB

 Make Transparent
Categorized in Visuals/FX

Description

Apply to a RENDEROBJECT.
Makes a Render Object (3D or 2D Entity) Transparent.
Make Transparent.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Source Blend: see 'Set Blend Modes' for detailed information on blending factors.
Destination Blend: see 'Set Blend Modes' for detailed information on blending factors
Alpha: amount of opacity for the transparence.
Hierachy: when checked, the behavior applies to the children in the hierarchy of the 3D Entity.

"Make Transparent" BB simplifies the process of rendering an object with transparence (blending transparence).
"Make Transparent" BB works also with prelit meshes.

Warning

- Make Transparent BB render all materials applied to the 3d entity transparent, so other objects using the same material will also be rendered with transparence.
- The materials are set to be transparent, but the transparency flag is only put on the meshes of the selected 2D or 3D Entity. Therefore, other objects using the same material will also be rendered with transparence, but the transparency flag won't be put on these other meshes (You'd have some Z sorting problems...). If you want these other meshes to be render correctly, you should use on them the 'Set transparent' building block.


Mark System BB

 Mark System
Categorized in Visuals/FX

Description

Apply to a BEOBJECT.
Creates marks (single or continuous) on surfaces.
Mark System.cmo

Technical Information

On: activates the building block.
Off: deactivates the building block.
Mark: creates a new mark.
End Mark: ends a mark band. (only available for continuous marks)

Exit On: is activated when On is activated.
Exit Off: is activated when Off is activated.
Exit Mark: is activated when Mark is activated.
Exit End Mark: is activated when End Mark is activated. (only available for continuous marks)

Position: position of the mark.
Normal: normal of the mark.
Referential: referential in which the position and normal are provided.
Color and Alpha: color and alpha of the mark.
Size: size of the mark.
Material: material used by the marks (not considering the colors).
Lifespan: life span of the marks (in ms). 0 means the mark remains permanently.
Fading Time: time span of the fadeout (in ms).
UVs: texture coordinates of the mark (allows several marks in one texture, for rendering efficincy purposes). (0,0,0,0) means the whole texture.
Position Offset: position offset of the marks in the "Normal" direction. Useful to attenuate z-buffer fighting issues between the marks and the obstacle on which they lay.
Texture Factor: texture mapping factor. (only available for continuous marks)
Whole Faces: (only relevant for decal marks) True means the supporting faces are considered in their entirety. False means that the supporting faces will be clipped by the mark size. Note: if set to true, your material's texture address mode will need to be set to Clamp.

Maximum Marks: maximum number of simultaneous marks.
Continuous Marks: should the mark be continuous or not (it adds inputs and parameters).
Supporting Entity: this entity, if given, will support the rendering of the marks, if you don't want them to be rendered after every objects in the scene (for example if you observe artefacts with particles).
Decal Marks: apply mark on the faces of the given referential. The referential can't be NULL in that case..
Random Orientation: should the mark have a random orientation or not.

If a referential is given, the mark will follow it, and will be drawn only if the referential is visible. If no referential is given, the marks will continue to be rendered (even if they are not currently onscreen).
When marks reach their life time minus their fading time, they start to fade.
The material of the mark must have SRCALPHA for the source blend mode to effectively observe a fading out of the mark.
Continuous marks and decal marks are not compatible.


Motion Blur BB

 Motion Blur
Categorized in Visuals/FX

Description

Apply to a 3DOBJECT.
Performs a Motion Blur when the 3D Entity is moving.
Motion Blur.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Number of Trails: number of trails that can be seen behind the 3D entity when it's moving.

Motion blur is an effect you will see in photographs of scenes where objects are moving. It is mostly noticeable when the exposure is long, or if objects in the scene are moving rapidly.


Planar Filter BB

 Planar Filter
Categorized in Visuals/FX

Description

Apply to a BEOBJECT.
Sets a filter color and an additionnal color to recover all the scene.
Planar Filter.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Filtering Color: color by which the texture colors are multiplied... e.g: to see red components of the texture, set filtering color to (255, 0, 0, 128).
Alpha component is the fourth member of the filtering color.

Additional Color: This is the color which is added to the texture color.
Texture: texture that will be used in the filter Source Blend: This is the mode for source blending. (see 'SetSrcBlend' for more details on blending mode)
Dest Blend: This is the mode for destination blending. (see 'SetDestBlend' for more details on blending mode)
Texture Mag Mode: Texture Filtering Mode when it is magnified
Texture Min Mode: Texture Filtering Mode when it is minimized

Useful to simulate infrared glasses or fade in/fade out effects.
This Behavior doesn't need loop.


Planar Reflection BB

 Planar Reflection
Categorized in Visuals/FX

Description

Apply to a 3DENTITY.
Creates a reflection on a plane of objects in a group.
Planar Reflection.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Reflection Group(s): Groups of objects effectively reflected.
Plane Normal: Normal of the plane to reflect from.

Discard Off Mirror Reflection: reflected objects parts that can be seen without looking through the mirror are hidden if this flag is set to TRUE (set to TRUE by default)

The objects must have the "Reflected Object" attribute to be taken into account by this behavior. The group will determine on which plane the objects will reflect and the mesh will be used for reflection, if provided. Otherwise, it will reflect the entire hierarchy with their current meshes.


Planar Shadow BB

 Planar Shadow
Categorized in Visuals/Shadows

Description

Apply to a 3DENTITY.
Projects planar shadows from a specific Light for selected 3D Entities.
Planar Shadow.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the BB is activated.
Exit Off: is activated if the BB is deactivated.

Shadow Group(s): Groups of objects that are to have shadows.
Light: Light from which shadows are projected.
Color: Color of the shadows.
Plane Normal: Normal of the plane to cast the shadow to.

Discard Off Plane Shadow: if selected, shadows are not drawn beyond the plane on which they are projected.

Remarks

Only elements that have the Planar Shadow Object Attribute are taken into account by this BB, and furthermore elements are only taken into account if they are in the same groups as specified by the Shadowing Group(s) pIn.

The Planar Shadow Object Attribute also allows you to select a mesh for rendering the shadow. If no mesh is selected, the entire hierarchy is shadowed using the elements' current meshes.

The shadow is projected in perspective with Point and Spot Light Types, and projected parallel with Directional Light Types.


Render Curve BB

 Render Curve
Categorized in Visuals/FX

Description

Apply to a CURVE.
Renders the curve with a specific material.
Render Curve.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Material: Material to use to render.
Size: Size of the shape to render.
Texture Scale: Scale of the texture coordinates.
Texture Offset: Starting offset of the texture coordinates.
Up: Vector defining the up of the shape.
Tube Lighting: Should the tube be lighted?.
Tube Tesselation: Tesselation of the round shape of the tube.

Render Mode: render curve plane shaped (face 1 sided), cross shaped, tube shaped, 2D shaped (kind of plane but always in front of the camera), line shaped.

In Line rendering mode, the curve is rendered using the diffuse color of the material. If no material is specified, the curve will be white.


Replace Rendering BB

 Replace Rendering
Categorized in Visuals/FX

Description

Apply to a 3DOBJECT.
Replaces an an element's material before rendering that element.
Replace Rendering.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates when the process is activated.
Exit Off: activates when the process is deactivated.

In Material: Material to replace.
Out Material: replacing Material.

Per Object: if the target shares the same Mesh with other 3D Entities, selecting this setting ensures only the Material for the target is replaced, and not the Material of any other 3D Entities.

Remarks

This BB allows you to change the Material of a 3D Object that is currently sharing a Mesh (and so sharing the same Material) with other 3D Objects.

This BB can also be useful for example when you want an opaque object to be rendered at the same time as a transparent object. Let it use a transparent material, and use an opaque material when it is rendered. Or you could use this BB if you need a transparent object to be rendered at the same time as opaque objects, and before transparent ones (and so before any effect taking place after opaque objects rendering [like a shadow caster...]).


Set 2D Material BB

 Set 2D Material
Categorized in Visuals/2D

Description

Apply to a 2DENTITY.
Sets the material of a 2D Entity.
Set 2D Material.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Material: Material to be set on the 2DEntity.


Set 2D Parent BB

 Set 2D Parent
Categorized in Visuals/2D

Description

Apply to a 2DENTITY.
Sets the Parent of a 2D Entity.
Set 2D Parent.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Parent: 2D Entity to be set as parent. Use NULL to 'deparent' the entity (which means parenting it to the world).

Warning

- This building block sets a state on the object. Which means, once it is activated, the state will be kept as it is until a 'Set2DParent' is called on the child (this can also occur when reseting IC).
Therefore, if you want initial hierarchy to be reseted as it was before activating this building block, you'll need to put Initial Conditions (IC) on the child.


Set 2D Position BB

 Set 2D Position
Categorized in Visuals/2D

Description

Apply to a 2DENTITY.
Set the position of a 2D Entity
Set 2D Position.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Position: Position of the 2D entity, absolute or relative to a referential.
Referential: Referential in wich the position is given (NULL means the screen).


Set 3DSprite Mode BB

 Set 3DSprite Mode
Categorized in Visuals/Sprite

Description

Apply to a SPRITE3D.
Sets the orientation mode of the 3D Sprite.
Set 3DSprite Mode.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Mode:
BILLBOARD (completely attached to the camera, and therefore always facing it).
XROTATE (always facing when camera rotates around the X local axis of the 3D Sprite)
YROTATE (always facing when camera rotates around the Y local axis of the 3D Sprite)
ORIENTABLE (completely independent)


Set Color Key 2D BB

 Set Color Key 2D
Categorized in Visuals/2D

Description

Apply to a SPRITE.
Sets the transparent transparence color key for a sprite.
Set Color Key 2D.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Translucent Color: color expressed in RGBA.
Transparent: activates or deactivates the the translucent mode.


Set Rectangles BB

 Set Rectangles
Categorized in Visuals/2D

Description

Apply to a 2DENTITY.
Sets the destination and/or source rectangles for a 2D Entity.
Set Rectangles.cmo

Technical Information

In: activates the process.
Out: is activated when the process is completed.

Destination: destination rectangle on the screen of the 2D entity (in screen coordinates).
Source: source rectangle on the texture of the 2D entity (in homogeneous UV coordinates). Note that for this pIn to have any effect, the UVMapping parameter in the 2D Frame setup of the element must be set to activate.


Set Render Order BB

 Set Render Order
Categorized in Visuals/FX

Description

Apply to a 3DENTITY.
Tells the object to be displayed FIRST, LAST, or in a normal way.
ZBuffer.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Display First: boolean value to check if you want the 3dobject to be render FIRST in the rendering process.
Display Last: boolean value to check if you want the 3dobject to be render LAST in the rendering process.
Rendering Priority: integer value relative to other object's rendering priority, that rules the rendering order of this object against others.
An object with a greater priority will be rendered before any other object which a priority is smaller. However, this value is subject to some rules:
- Opaque objects are always rendered before transparent objects.
- The Rendering Priority value rules the rendering order of opaque objects between themselves, and rules the transparent objects between themselves, but doesn't rule the rendering order of opaque objects against transparent objects.
- The Rendering Priority value rules the rendering order of objects which hierarchy level is the same.
- The Rendering Priority value of a child influence (in a less significant way) its parent rendering priority of its parent.
- Transparent objects use their rendering priority only if the 3d engine cannot distinguish which object is to be render before the oder one. Thus you should use this value only to solve rendering order issues between transparent objects.

Useful to tell an object as to be rendered first (as a sky plane), or last (as an inventory object), or to solve rendering order problems that could occur for transparent objects. Note that render priority can be edited in Level View or Hierarchy Manager.

Warning

- This building block sets a flag in the object state, therefore, as for 'set diffuse' or building block like that, once it's done, the object will remain in the new state.


Set Z Buffer BB

 Set Z Buffer
Categorized in Visuals/FX

Description

Apply to a 3DENTITY.
Change the way the object read and write into the ZBuffer.
ZBuffer.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Read: boolean value to check if you want to enable the 3dobject to read into the zbuf when it draws itself.
Write: boolean value to check if you want to enable the 3dobject to write into the zbuf when it draws itself.

Warning

- This building block sets a flag in the object state, therefore, as for 'set diffuse' or building block like that, once it's done, the object will remain in the new state.
- This building block does not work on a 3D sprite (you can directly modify the 3D sprite material using Set Material Z Buffer).


ShadowCaster BB

 ShadowCaster
Categorized in Visuals/Shadows

Description

Apply to a 3DENTITY.
Projects a shadow all the objects visible in the scene
ShadowCaster.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

ight: Light from which the shadow must be casted. If the light is directionnal, the projection will be orthogonal, else it will be in perspective.
Min Light Distance: distance beneath which the shadow is fully black. Between this min and the max distance, the shadow continuously fades to transparent.
Max Light Distance: distance beyond which no more shadow is projected.
Soft Shadow: apply a vertical gradient to the shadow to simulate light distance fading.

Shadow Resolution Size: size of the texture in which the shadow will be rendered. The greater the sharper the shadow will be.

The target object and all its hierarchy is rendered into the shadow, so you can use this building block on a character.
Objects that must receive the shadow must have the Visuals FX/Shadow Caster Receiver attribute. For a good effect, these objects need to be well tesselated.


ShadowStencil BB

 ShadowStencil
Categorized in Visuals/Shadows

Description

Apply to a LIGHT.
Generates stencil buffer shadows from a specific Light for all elements that have the Shadow Stencil Caster Attribute.
ShadowStencil.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates when the process is activated.
Exit Off: activates when the process is deactivated.

Shadow Range Factor: length of the shadow. Unless you are sure of the maximum length of a shadow volume, start with a high value (e.g. 200 or even 1000) and work down. The lower the this value the better to save processing time.
Shadow Material: the Material to use when rendering shadows. In most cases you will use a black transparent material. Playing with opacity and the blending modes for a Material can generate nice effects.
Show Shadow Volumes: if selected, the shadow volume is no longer rendered in the stencil buffer, but directly in the frame buffer so that shadow volumes are visible.
Camera Can Penetrate Shadow: if selected, the shadow stencil is inverted when the Camera penetrates a shadow volume so that the shadow effect is still correct. If the Camera never penetrates a shadow volume, it's better to keep the Camera Can Penetrate Shadow check box clear to save processing time.
Note: if your Camera can penetrate a shadow volume, you should reduce the Camera's Near Clipping Plane parameter in order to reduce the shadow clipping effect when your Camera is on the edge of a surface of your shadow volume.

Light Occluders Count: if you select the Camera Can Penetrate Shadow check box, Light Occluders Count is the number of objects between the light and the Camera occluding the Light.

Remarks

ShadowStencil applies to an omni Light, and renders the shadows of all objects that have the Shadow Stencil Caster Attribute. The generated shadows are the shadows generated by the omni light. Shadows can apply to objects casting the shadow (self-shadowing).

For Characters, the Shadow Stencil Caster Attribute must be applied to all Bodyparts that are supposed to cast shadows and not the Character itself. For skin Characters, you only need to apply the Shadow Stencil Caster Attribute to the skin Bodypart, not the individual Bodyparts.

If your Camera can penetrate shadow volumes, select Camera Can Penetrate Shadow and reduce the near clipping plane of your Camera. This minimizes the shadow Camera clipping when your Camera is on the shadow volume surface.

Warning

ShadowStencil only works with 3D graphics cards that have stencil buffers, and only if the rendering mode is set to display 32 bit color.


Show 2D Entity BB

 Show 2D Entity
Categorized in Visuals/Show-Hide

Description

Apply to a 2DENTITY.
OBSOLETE - see Show BB.

Shows a 2D Entity

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Warning

This building block is obsolete and is only included for backwards compatibility.


Show 3D Entity BB

 Show 3D Entity
Categorized in Visuals/Show-Hide

Description

Apply to a 3DENTITY.
OBSOLETE. Replaced by Show.

Shows a 3D Entity

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Hierarchy: if TRUE, then this building block will also apply to the 3D Entity's children.


Show BB

 Show
Categorized in Visuals/Show-Hide

Description

Apply to a BEOBJECT.
Shows a 2D/3D Entity, a Mesh or a Group.
Show Hide.cmo

Technical Information

In: activates the process
Out: activates when the process completes.

Hierarchy: if TRUE, then this building block will also apply to the element's children.

Remarks

Show replaces Show 2D Entity and Show 3D Entity.

See Also: Hide, Hide Hierarchy.


Show Mouse Cursor BB

 Show Mouse Cursor
Categorized in Visuals/Show-Hide

Description

Apply to a BEOBJECT.
Show/Hide the mouse cursor.
Show Mouse Cursor.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Show: True shows the cursor, False hides it.

Warning

- If you hide the cursor three times, you'll have to show it three times to actually have it back.


Show Object Information BB

 Show Object Information
Categorized in Visuals/Show-Hide

Description

Apply to a 3DENTITY.
Shows the bounding box and the normals of a 3D Entity.
Show Object Information.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Show Bounding Box: shows or hides the bounding box.
Bounding Box Color: color in RGBA.
Local: specifies the local box or the world box.
Hierarchical Box: specifies if hierarchical box is to be shown.
Show Vertex Normals: shows or hides the vertices normals.
Vertices Normals Colors: color in RGBA.
Vertices Normals Size: size of the normals drawn, in world coordinates.
Show Face Normals: shows or hides the faces normals.
Face Normals Colors: color in RGBA.
Face Normals Size: size of the normals drawn, in world coordinates.
Show Bounding Sphere: shows or hides the bounding sphere.
Bounding Sphere Color: color in RGBA.

Vertex Normal Material: material used to render vertex normals
Face Normal Material: material used to render face normals

Warning

- You have to loop this behavior if you want the object information to be draw for several frames.


Simple Shadow BB

 Simple Shadow
Categorized in Visuals/Shadows

Description

Apply to a 3DOBJECT.
Display a little soft shadow on floors beneath the object.
Simple Shadow.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Texture: the shadow's texture of your object. This texture should be symmetrical and from black to white (e.g.: just the under given texture: 'soft_shadow.jpg')
Size Scale: the shadow's size according to the object basis size.
Maximum Height: the height above which the shadow stops being projected on the floor(s). It means that if the distance between the bottom plane of the object's world bounding box, and the top plane of the floor(s) bounding box is greater than "Maximum Height", the shadow won't be render any more.
If you design your content in such a way that 2 floors can stand one up on the other (ex: a bridge above a terrain) then, giving a proper value to the "Maximum Height" parameter could solve the shadow to appear twice (on the bridge but also on the beneath terrain).

Warning

- The "Simple Shadow" BB needs declared FLOORS to apply the soft shadow texture.(use "Declare Floors" or set the Floor Attribut to the objects you want to cast the shadow)
- The Y axis of your floors referential should always be oriented in the world UP direction.
- The shadow will be applied on all the floors just under the object.
- The shadow won't be applied on floors that stand above the object. In fact, for performance purpose, a floor will be consider as being above the object if the top plane of the object's world bounding box is below the bottom plane of the floor's world bounding box.


Solid Trail BB

 Solid Trail
Categorized in Visuals/FX

Description

Apply to a 3DOBJECT.
Create a Solid Trail following the 3D Entity when it's moving.
Solid Trail.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: is activated if the building block is activated.
Exit Off: is activated if the building block is deactivated.

Width Attenuation: percentage determining how fast the trail shrinks (10 or 20 are nice value).
Length: length of the trail (10% is a short trail, 100% is the longest trail supported).
Color: color of the trail expressed in RGBA.
Frame Delay: frame delay between trail polygons generation.

Useful for swords or pools moving fast. Use "flashy" colors for better results.
The trail is composed of dynamically created polygons. The frame delay parameter determines how often these polygons are created. Therefore a 1 frame delay will result in a short smooth trail, whereas a 5 frame delays creates a long rough trail.
Concerning 'Attenuation', negative value makes the trail expand instead of shrinking (typical values are -10 or -20). High value makes the trail cross over and over (typically 100 or 110). This behavior doesn't need looping.


Sprite Movie Player BB

 Sprite Movie Player
Categorized in Visuals/Sprite

Description

Apply to a SPRITE.
Plays a movie in a 2d Sprite (avi)
Sprite Movie Player.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Slot Complete: activates each time a slot change.
Movie Complete: activates each time a sequence has been completed.

Duration: how long the whole process should last.
Loop: tells wether or not the movie has to loop.
Starting Slot: the starting frame of the movie.
Ending Slot: the ending frame of the movie ( this frame will not be played !!! )

Current Slot: the current frame being played.

By default, 'Starting Slot'=0 and 'Ending Slot'=0, which means the movie has to be played from front to end.


Sprite Multi Angle BB

 Sprite Multi Angle
Categorized in Visuals/Sprite

Description

Apply to a 3DENTITY.
Replaces the 3D Entity by a 3D sprite.
Sprite Multi Angle.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Scale X: scaling factor along the X axis of the 3D Sprite.
Scale Y: scaling factor along the Y axis of the 3D Sprite.
Translucent: 'True' allows color keying.
Color Key: color set to be transparent, expressed in RGBA ('Translucent' must be 'True').
Mirroring: set to 'True' to use multiple sprites (see below).
Sprite Texture: texture to use as a 3D Sprite.

Preferably, apply this building block on a frame.
You can use this building block to create 3D sprites.
You can also simulate a 3D object by using a whole set of textures, representing the object seen from different angles. To do so, add input parameters for each new texture. You can use as many textures as needed. The first one should be a texture of the object seen from the front, the next been taken from the left, and so on.
If the 3D object you want to simulate has a simetry, set 'Mirroring' to 'True. All the textures you provide will then be used to simulate the left side of the object, while the right side will use mirrored textures. For example, you can provide a FrontTexture, LeftTexture, BackTexture, and set 'Mirrored' to 'True' so that the RightTexture will be automatical


Texture Render BB

 Texture Render
Version 2.00 - Virtools
Categorized in Visuals/FX

Description

Apply to a TEXTURE.
Render an image in the texture of a 3D Entity.
Texture Render.cmo

Technical Information

In: triggers the process.
Reset: You need to reset this behavior when you have new objects entering your scene and you want them to be seen in the texture renderer. (Anyway you must reset this behavior at least one time.)
Out: is activated when the process is completed.

Camera: camera from which the image should be rendered.
Background Color: background color of the rendering in RGBA.
Background Texture: name of the texture to use for the background of the rendering.

Render Options: render flags...
Background Sprites: background 2D Sprites are to be rendered.
Foreground Sprites: foreground 2D Sprites are to be rendered.
Use Camera Ratio: render context size is automatically set using current camera aspect ratio and Window Rectangle (Horizontal Size has priority).
Clear ZBuffer: clear ZBuffer.
Clear Back Buffer: clear Back Buffer.
Clear Stencil Buffer: clear Stencil Buffer (stencil buffer has not been yet implemented).
Clear Only Viewport: do not clear entire device, only viewport (device=window, viewport=subpart in window where 3d objects are rendered [for instance think about 16/9 rendering]).
Disable 3D Only: do not draw 3D scene (only 2d sprites).
Vertical Sync: Wait for Vertical Blank before blitting (transfer image).
Buffer Swapping: Swap front and back buffers.
Disable Rendering: Do not draw the scene (both 3D and 2D objects).
(CubeMap) Render Face by Face: If true, render to a different cube map face each time the building block is trigerred. If false render to all 6 cubemap faces.
Update System Memory: Transfer the rendering to the texture system memory (used for procedural texture update, screenshot saving,...)

Warning

- You must apply this behavior on a textured object.
- The UVs of a mesh using a render target must be between 0 and 1..


Use Z information BB

 Use Z information
Categorized in Visuals/FX

Description

Apply to a BEOBJECT.
Hides the object but uses its Z information during rendering
Use Z information.cmo

Technical Information

Clear Background: Sprite to be displayed on the background.

This behavior has neither 'Inputs' nor 'Outputs'. It only changes the rendering mode of a 3D Entity that has the ZInfo attribute.
The Object is then totally translucent, but it is always displayed in the Z-Buffer.
You Should use this behavior when rendering a scene with a fixed camera, and a complex 3d graphics image on the background. Then apply this behavior on a fixed object which represents the outline of a background part (drawing of some complex object). A character (or anything else) will then be able to get behind this object just like if it really exists.

Warning

- You should apply only one "Use Z Information" BB to per level (or scene).
- You can write into Z Buffer only by changing the properties of a material (see Material Setup), But this building block is usefull because you can to it to whole object (ie to all its material at the same time), and it does not alter the material properties of other object that use the same material.


Vertex Render BB

 Vertex Render
Categorized in Visuals/FX

Description

Apply to a 3DOBJECT.
Renders the object with a specific sprite at the vertices positions.
Vertex Render.cmo

Technical Information

On: activates the building block.
Off: deactivates the building block.

Out (Loop): is activated when one behavior's process is completed.

Light Texture: name of the texture used as the sprite.
Light Size: float, 1.0 = actual size.
Enable Fog Influence: specify whether the rendering of each little light should be influenced by the fog values or not.

Use Vertex Color: specify whether the sprite color should use the vertex color of the mesh.
Use Vertex Weights: specify whether the sprite size should be multiplied by the weight of the vertex of the mesh.

If 'Light Size' is set to 1.0, it means the original size of the texture. 2.0 means double size ...etc.
This behavior works best with small textures.
Textures should always be square.

Warning

- If you want to change either the 'Light Texture' or the 'Ligt Size' at each frame, you'll need to loop this behavior. Otherwise you needn't.
- These building blocks replace the object's rendering function. Therefore if you'd like to stop this type of rendering, you'll have to activate the 'OFF' input.
- In Fact the 'ON' and 'OFF' switch from both objet's rendering mode.


Volumetric Fog BB

 Volumetric Fog
Categorized in Visuals/FX

Description

Apply to a 3DENTITY.
Creates a volumetric fog effect for a given Group of 3D Entities.
Volumetric Fog.cmo

Technical Information

On: activates the process.
Off: deactivates the process.

Exit On: activates when the process is activated.
Exit Off: activates when the process is deactivated.

Material: Material to use for the fog effect. This Material will be applied to all objects beneath the fog referential. The UVs of these objects will be changed so that a vertex deeper in the fog will be more influenced by the fog material than other ones. Deeper vertices have greater V coordinate on the Texture.
In most case it's better to put the fog color in the Material emissive component, and to use a gray gradient Texture (from white at the bottom to black at the top) as the Texture of the Material.
Fog Density: percentage for the fog density (use small values between 0% and 5%). 0% means no visible fog effect.
Group: the group of 3D Objects to which the fog material will be added to simulate a volumetric fog. A channel with the given material will be added to all those objects and blended with the existing material using ONE as source blend mode and INVSRCCOLOR as destination blend mode.

Remarks

The target of Volumetric Fog is the fog referential. The target can be a 3D Frame, or a real geometric object (like a plane). Volumetric Fog affects all the members specified in Group laying under the fog referential's XZ plane. The best thing to do is to cut walls into 2 parts. One upon the fog plane, and another beneath the fog plane, so that there's a clear frontier, and UVs on the fog material can be different. However if you need to change the fog altitude at at run-time, don't cut your objects (walls), but if you don't need to, it will be faster to have a real object separation.

To add a cloudy effect on the fog, you can use a textured grid plane as your fog referential (the target of Volumetric Fog), and make its UVs constantly change in a smoothing motion.

Volumetric fog sample:

Volumetric fog Texture:
         Cloudy Texture applied on the fog referential:


VSL

Run VSL: Run a VSL script


 Run VSL
Categorized in VSL

Description

Apply to a BEOBJECT.
Runs a VSL script.

Technical Information

In: activates the process.

Out: is activated when the process is complete.

Runtime Script Change: By default, Run VSL executes a specific VSL script. This setting allows you to create a pIn that will allow you to specify a VSL script to use during runtime, and these VSL scripts must be stored in strings.

Remarks

For more information, see the VSL (Virtools Scripting Language) pages.


Web

Navigation

Back: Performs a back in the Web Browser

Forward: Performs a Forward in the Web Browser

GetUrl: Gets the current URL

Go To Web Page: Performs a Navigate in the Web Browser

Home: Performs a Home in the Web Browser

Navigate: Performs a Navigate in the Web Browser

Search: Performs a Search in the Web Browser

Scripting

BrowserScript: Executes a script in the Web Browser

Fire Virtools Event: Performs a Fire Event in the Web Browser

Server

Web Download: Download a file from a webserver.

Web Get Data: Gets data associated with an URL.


Back BB

 Back
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Performs a back in the Web Browser
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Back go to back to the previous page, if the content is hosted in a web browser.

See Also: Web Behaviors.


BrowserScript BB

 BrowserScript
Categorized in Web/Scripting

Description

Apply to a BEOBJECT.
Executes a script in the Web Browser
BrowserScript.cmo + BrowserScript.htm

Technical Information

In: triggers the behavior's process.
Out: is activated when the behavior's process is completed.
Script: script to be executed.
Language: langage used for the script : JSCRIPT,JAVASCRIPT or VBSCRIPT (with Netscape browser only JAVASCRIPT is available).

This building block execute the specified script (JSCRIPT,JAVASCRIPT or VBSCRIPT) on the web page containing the Virtools Web Player. With Netscape browser only JAVASCRIPT is available.
See Also : Web Behaviors.


Fire Virtools Event BB

 Web Virtools Event
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Performs a Fire Event in the Web Browser
Fire Virtools Event.cmo + FireVirtoolsEvent.htm

Technical Information

In: triggers the behavior's process.
Out: is activated when the behavior's process is completed.
Event Name: name of the event.
Event Data: data to be send with the event.

This building block fire an event that can be catched by the host application.
This function isn't avaible with Netscape broswers.
See Also : Web Behaviors.


Forward BB

 Forward
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Performs a Forward in the Web Browser
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block to go to Forward to the previous page, if the content is hosted in a web browser.
See Also: Web Behaviors.


GetURL BB

 GetURL
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Returns the URL of the current web page
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the behavior's process.
Out: is activated when the behavior's process is completed.
URL: the current URL as a string.
This building block get the current URL, if the content is hosted in a web browser.
See Also : Web Behaviors.


Go To Web Page BB

 Go To Web Page
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Opens the default Internet browser and navigates to the given location
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

URL: URL that will be passed to the browser.

See Also: Web Behaviors.


Home BB

 Home
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Performs a Home in the Web Browser
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block to go to Home to the previous page, if the content is hosted in a web browser.
See Also: Web Behaviors.


Navigate BB

 Navigate
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Performs a Navigate in the Web Browser
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block to go to Navigate to the specified URL, if the content is hosted in a web browser.
Or it opens the URL in the default web browser if the content host is not a web browser. See Also: Web Behaviors.


Search BB

 Search
Categorized in Web/Navigation

Description

Apply to a BEOBJECT.
Performs a Search in the Web Browser
Navigation.cmo + Navigation.htm

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

This building block to go to Search to the previous page, if the content is hosted in a web browser.
See Also: Web Behaviors.


Web Download BB

 Web Download
Categorized in Web/Server

Description

Apply to a BEOBJECT.
Downloads a file from a webserver.
Web Download.cmo

Technical Information

Start: starts downloading the specified file.
Stop: stops the current download.

Finished: activates when the file has finished downloading.
Stopped: the download has been stopped.
Incoming: activates each time a new packet is received; the Current pOut is updated at the same time.
Failed: activates if downloading the file fails; the error pOut is updated at the same time.

URL: the internet address of the file to download. (e.g. http://www.mydomain.com/myfile.nmo).
Relative to URL ?: if TRUE, the URL of the downloadable file is built using the URL of the current vmo played in the Virtools Web Player. For example if the current vmo played in the Virtools Web Player is "http://www.mydomain.com/myapp.vmo" and you set this pIn to TRUE, to reference "http://www.mydomain.com/myfile.nmo" you simply have to set URL pIn to "myfile.nmo".
Proxy Login: Login used to be authentified by the client proxy. By default leave it empty and check Error (Proxy need authentication) to known if a proxy need the user to be authentified.
Proxy Password: Password used to be authentified by the client proxy. By default leave it empty and check Error (Proxy need authentication) to known if a proxy need the user to be authentified.
Server Login: Login used to be authentified by the server. By default leave it empty and check Error (Server need authentication) to known if the server need the user to be authentified.
Server Password: Password used to be authentified by the server proxy. By default leave it empty and check Error (Server need authentication) to known if the server need the user to be authentified.
Extension: File extension to use for the local filename name (see Filename). Leave Extension empty to use the default extension specified by URL. This pIn is very useful is following example: If URL pIn points to a php script that generates a png file (e.g. http://www.mydomain.com/generate_png.php) - and you leave the Extension pIn empty, the local filename will have "php" as its file extension. Since the php script generates a png file, you need to set the Extension pIn to "png" (so that Virtools' PNG loader will be able to load the downloaded file).

Error: error code.
Filename: the file name and absolute file path on the local hard drive, used to load the file into the Virtools Web Player after downloading using Object Load BB (nmo), Texture Load BB or Sound Load BB.
Current: number of bytes already downloaded, updated when a new packet arrives.
Max: the size of file downloading, in bytes.

Block Size: maximum size of packets downloaded, in bytes. A value between 10000 and 20000 bytes is recommended.

Remarks

Error codes are listed below:

  • OK: no error
  • Cannot get tmp path: the manager failed to generate a temporary filename to store the download file.
  • Network error: the network connection failed.
  • Cannot create thread: the manager failed to create a thread to download the file.
  • Invalid URL: the URL pIn is invalid.
  • Stopped: the download has been stopped.
  • Cannot read request: the network connection failed.
  • Cannot initialize request: the network connection failed.
  • Not authorized: the current user cannot access the current URL.
  • Cannot get manager: the manager is not accessible.
  • Internal error: an internal error occurred.
  • Array invalid: the array used to store data (Web Get Data BB) is invalid (ie bad format).
  • Proxy need authentication: the client system is configured to use a proxy. The proxy request an user authentication. Set Proxy Login and Proxy Password and restart Web Download BB.
  • Server need authentication: the server request an user authentication. Set Server Login and Server Password and restart Web Download BB.

See Also: Web Get Data.


Web Get Data BB

 Web Get Data
Categorized in Web/Server

Description

Apply to a BEOBJECT.
Retrieves the content of a web page associated with a URL (and optionally sends data to the URL).
Web Get Data.cmo

Technical Information

In: Triggers the behavior's process.

Succeed: Activates when the data has been retrieved.
Failed: Activates if process fails; the errorpOut is updated at the same time.

URL: The URL processed to retrieve the data.
Proxy Login: Login used to be authentified by the client proxy. By default leave it empty and check Error (Proxy need authentication) to known if a proxy need the user to be authentified.
Proxy Password: Password used to be authentified by the client proxy. By default leave it empty and check Error (Proxy need authentication) to known if a proxy need the user to be authentified.
Server Login: Login used to be authentified by the server. By default leave it empty and check Error (Server need authentication) to known if the server need the user to be authentified.
Server Password: Password used to be authentified by the server proxy. By default leave it empty and check Error (Server need authentication) to known if the server need the user to be authentified.
Post: This pIn is available if Post? setting is TRUE. This pIn represents the data (as a string) to be posted to the URL.
Array: This pIn is available if Result As Array? setting is TRUE. This pIn represents the array to store the result of the process in (instead of the Data pOut).

Error: Error code.
Data: This pOut is available if Result As Array? setting is FALSE. This pIn represents the string containing the result of the process if Succeed has been activated.

Post?: Should data be sent to the URL using the post method? (read remarks below).
Result As Array?: Should data be retrieved as an array or a string?

Remarks

The Post? setting:

This BB is used to retrieve the content of a web page (associated with a URL) that can be a simple HTML file or most likely a script file (PHP, ASP, JSP, CGI, etc.) that may (or may not) provide an access to a database. This BB is can also send data using the GET or the POST method.

For example, let's say you have a script called "score.php3" which need a parameter called id to display a string like "score=5". This parameter is the identifier of the player you want to know the score of your game.

The score.php3 file would looks something like this:

<?php
// PHP code to retrieve the value from a database
// or supply the array like the one shown below
    $array_scores[0] = 2;
    $array_scores[1] = 3;
    $array_scores[2] = 4;
    $array_scores[3] = 5;
    $array_scores[4] = 6;
    $array_scores[5] = 7;
    $array_scores[6] = 8;
    $array_scores[7] = 9;
    $array_scores[8] = 10;
    $array_scores[9] = 11;
    // here $id is the parameter needed by the script.
       printf("score=%d\n",$array_scores[$id]);
?>

Note: instead of filling an array, in most cases, a data base connection is made instead.

If you want to retreive the result of the script with Virtools you can proceed in two ways:

  1. using the GET method:
    • set URL to http://www.mydomain.com/score.php3?id=3 for example (where 3 is the id of the current player).
    • set Post ? and Result As Array ? to FALSE.
    • execute the BB and you should get a string like "score=5" in the Data pOut.
  2. using the POST method:
    • set URL to http://www.mydomain.com/score.php3
    • set Post ? to TRUE and set set Post to "id=3" (where 3 is the id of the current player).
    • set Result As Array ? to FALSE.
    • execute the BB and you should get a string like "score=5" in the Data pOut.

In ASP, thes same script would look like this:

<%
' ASP code to retrieve the value from a database
' or supply the array like the one shown below
    Dim array_scores(10)
    array_scores(0) = 2
    array_scores(1) = 3
    array_scores(2) = 4
    array_scores(3) = 5
    array_scores(4) = 6
    array_scores(5) = 7
    array_scores(6) = 8
    array_scores(7) = 9
    array_scores(8) = 10
    array_scores(9) = 11
    ' here id is the parameter needed by the script.
    id = Request.QueryString("id")
    Response.Write("score=")
    Response.Write(array_scores(id))
%>
The Result As Array ? setting:

With this BB you can store data in an array instead of a string. You have to set the Result As Array? setting to TRUE and set the new pIn Array to the array in Dev.

This array and the HTML table must have matching formats. The BB looks for the first table in the HTML format at the URL specified. Note: your table must begin with the tag TABLE, each line must begin with TR and each row with TD. For example, a table formated like this will be recognized:

<table>
 <tr>
  <td>0</td>
  <td>2</td>
 </tr>
 <tr>
  <td>1</td>
  <td>3</td>
 </tr>
 <tr>
  <td>2</td>
  <td>4</td>
 </tr>
 <tr>
  <td>3</td>
  <td>5</td>
 </tr>
 <tr>
  <td>4</td>
  <td>6</td>
 </tr>
 <tr>
  <td>5</td>
  <td>7</td>
 </tr>
 <tr>
  <td>6</td>
  <td>8</td>
 </tr>
 <tr>
  <td>7</td>
  <td>9</td>
 </tr>
 <tr>
  <td>8</td>
  <td>10</td>
 </tr>
 <tr>
  <td>9</td>
  <td>11</td>
 </tr>
</table>
Very important: Your array in Dev must also have a type format that matches the data in your HTML table. I.E. If a cell of the HTML table has a string like "this is a sample" and the type of row in the array is Integer the BB will fail because "this is a sample" cannot be converted to an integer. Also note that the data will need to respect Dev's rules of notation. eg vectors must be written as "1,1,1"

Error code are:
  • OK: no error
  • Cannot get tmp path: the manager failed to generate a temporary filename to store the download file.
  • Network error: the network connection failed.
  • Cannot create thread: the manager failed to create a thread to download the file.
  • Invalid URL: the URL pIn is invalid.
  • Stopped: the download has been stopped.
  • Cannot read request: the network connection failed.
  • Cannot initialize request: the network connection failed.
  • Not authorized: the current user cannot access the current URL.
  • Cannot get manager: the manager is not accessible.
  • Internal error: an internal error occurred.
  • Array invalid: the array used to store data (Web Get Data BB) is invalid (ie bad format).
  • Proxy need authentication: the client system is configured to use a proxy. The proxy request an user authentication. Set Proxy Login and Proxy Password and restart Web Download BB.
  • Server need authentication: the server request an user authentication. Set Server Login and Server Password and restart Web Download BB.

See Also: Web Download.


World Environments

Background

Clouds Around: Creates a cloud and fog effect in a scene using a 6 textured cube, colors and a blending mode.

Set Background Color: Sets a background color.

Set Background Image: Places a background image.

Set Background Material: Sets the Background Material

Sky Around: Simulates a Sky Effect on the Scene using 6 textures in a cube; This behavior doesn't need loop.

Sky Around(CubeMap): Simulates a Sky Effect on the Scene using a cube map texture on a cube; This behavior doesn't need loop.

Global

Set Ambient Light Color: Sets the ambient light color.

Set Fog: Sets the Atmospheric Fog.

Set Render Options: Set the flags of the render context.


Clouds Around BB

 Clouds Around
Categorized in World Environments/Background

Description

Apply to a BEOBJECT.
Creates a cloud and fog effect in a scene using a 6 textured cube, colors and a blending mode.
Clouds Around.cmo

Technical Information

On: activates the behavior.
Off: deactivates the behavior.

Out: is activated when the process is completed.

Back Texture: texture to be used at back of fog-cube.
Right Texture: texture to be used at right of fog-cube.
Front Texture: texture to be used at front of fog-cube.
Left Texture: texture to be used at left of fog-cube.
Up Texture: texture to be used at top of fog-cube.
Down Texture: texture to be used at bottom of fog-cube.

Distortion: increases the sky field of view, combined with the camera fov.
Filtering Color: RGBA values specifying which colors should be seen. For a red filter allowing only the red components of textures to be seen for example, the filter values would be (255, 0, 0, 128).
Additionnal Color: color expressed in RGBA which is to be added to the textures' colors.
Source Blend: mode for source blending (see "Set Src Blend" for more details on blending mode).
Dest Blend: mode for destination blending. (see "Set Dest Blend" for more details on blending mode).
Orientation Obect: object serving as reference point for the orientation of the Clouds Around cube. If no object is chosen, the default value is the scene root, with the result that the clouds will not move.

It is not necessary to loop this behavior.
This environment requires 6 rendered images with a FOV of 90 degrees in each direction.
[in 3ds Max (90 degrees camera), Bryce (112.5 degrees camera) or Terragen (Zoom = 1) for instance].


Set Ambient Light Color BB

 Set Ambient Light Color
Categorized in World Environments/Global

Description

Apply to a BEOBJECT.
Sets the ambient light color.
Set Ambient Light Color.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Color: ambient light color in RGBA.

This behavior can be applied to any object in a scene.


Set Background Color BB

 Set Background Color
Categorized in World Environments/Background

Description

Apply to a BEOBJECT.
Sets a background color.
Set Background Color.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Background Color: background color in RGBA.

This behavior can be applied to any object in a scene.


Set Background Image BB

 Set Background Image
Categorized in World Environments/Background

Description

Apply to a BEOBJECT.
Places a background image.
Set Background Image.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Background Texture: texture to be used as the background image.


Set Background Material BB

 Set Background Material
Categorized in World Environments/Background

Description

Apply to a BEOBJECT.
Sets the Background Material
Set Background Material.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Background Material: material to use as the background material.

Use this buiding block to easly put in background the same material than the one applied to a 3D Entity. This behavior can be applied to any object in the enviroment.


Set Fog BB

 Set Fog
Categorized in World Environments/Global

Description

Apply to a BEOBJECT.
Sets the Atmospheric Fog.
Set Fog.cmo

Technical Information

In: triggers the process.
Out: is activated when the process is completed.

Fog Mode: the fog calculation of gradation (None, Exponential, Exponential Squared, Linear).
Fog Start: distance from the viewpoint at which the fog effect starts.
Fog End: distance from the viewpoint at which the fog effect ends.
Fog Density: density of the fog.
Fog Color: fog color in RGBA.

This behavior can be applied to any object in the enviroment.
Trick: If you put the 'Fog End' to 30.0 (for example) you'll then be able to save rendering time by reducing the Far Clipping Plane of the camera to 30.0 (because none of the object behind this limit will be visible).


Set Render Options BB

 Set Render Options
Version 0.00 - Virtools
Categorized in World Environments/Global

Description

Apply to a BEOBJECT.
Set the flags of the render context.
Set Render Options.cmo

Technical Information

In: triggers the process
Out: is activated when the process is completed.

Render Options: render flags...
Background Sprites: background 2D Sprites are to be rendered.
Foreground Sprites: foreground 2D Sprites are to be rendered.
Use Camera Ratio: render context size is automatically set using current camera aspect ratio and Window Rectangle (Horizontal Size has priority).
Clear ZBuffer: clear ZBuffer.
Clear Back Buffer: clear Back Buffer.
Clear Stencil Buffer: clear Stencil Buffer.
Back To Front: enable Buffers Swapping.
Clear Only Viewport: do not clear entire device, only viewport (device=window, viewport=subpart in window where 3d objects are rendered [for instance think about 16/9 rendering]).
Wait VBL: wait for Vertical Blank before blitting.
Disable 3D: do not draw 3D scene (only 2d sprites).

Global Shade Mode: the shade mode, that applies to every 3d objects drawn in the current render context.
Wireframe: 3d objects are drawn using wireframe shading.
Flat: 3d objects are drawn using flat shading.
Gouraud: 3d objects are drawn using gouraud shading.
Materials Default: 3d objects are drawn using their own materials shading mode.

Use Textures: if TRUE, textures are rendered, otherwise, no texture rendering is perform.
Add Wireframe Layer: if TRUE, a wireframe layer will be added to all objects rendering.

This building block sets the flags of the current render context.
You can use it to save a time while rendering your scene by setting the Clear Back Buffer=FALSE, if you're sure your 3d environments covers all your rendering view (it clear the back buffer's viewport if the "Clear Viewport" is set to TRUE, and the all device if not).


Sky Around(CubeMap) BB

 Sky Around(CubeMap)
Version 1.00 - Virtools
Categorized in World Environments/Background

Description

Apply to a BEOBJECT.
Simulates a sky effect using a cube map texture; this behavior doesn't need to loop.
Sky Around(CubeMap).cmo

Technical Information

On: activates the process.
Off: deactivates the process.
Exit On: activates when the process is activated.
Exit Off: activates when the process is deactivated.

Cube Map Material: Material to use, which should be using a cube map texture containing the six faces of the sky-cube.
Distance: the cube size used to render the sky box; different sizes can be used to render more than one sky box.
Distortion: increases the sky Field of View, combined with the camera FOV.
Filtering Color: color to multiply the Texture colors. If you wanted to see only the red components of the Texture, you would put (255, 0, 0, 128) as the Filtering Color. Note that the alpha component is the fourth member of the Filtering Color.
Additional Color: color to add to the Texture Color.

Use 6 rendered images of the environment, with a FOV of 90 degrees in each direction.
[in 3ds Max (90 degrees camera), Bryce (112.5 degrees camera) or Terragen (Zoom = 1) for instance].


Sky Around BB

 Sky Around
Categorized in World Environments/Background

Description

Apply to a BEOBJECT.
Simulates a Sky Effect on the Scene using 6 textures in a cube; This behavior doesn't need loop.
Sky Around.cmo

Technical Information

On: enables the behavior.
Off: disables the behavior.
Exit On: is activated when the process is activated by On.
Exit Off: is activated when the process is activated by On.

Back Texture: texture to use as back texture of the sky-cube.
Right Texture: texture to use as right texture of the sky-cube.
Front Texture: texture to use as front texture of the sky-cube.
Left Texture: texture to use as left texture of the sky-cube.
Up Texture: texture to use as up texture of the sky-cube.
Down Texture: texture to use as down texture of the sky-cube.
Distortion: Increases the sky field of view, combined with the camera fov.
Filtering Color: This is the color by which the texture colors are multiplied... e.g: if you'd like just to see red coponents of the the texture, you should put (255, 0, 0, 128) as filtering color.
Note that the alpha component is the fourth member of the filtering color
Additional Color: This is the color which is added to the texture color.
Use 6 rendered images of the environment, with a FOV of 90 degrees in each direction.
[in 3ds Max (90 degrees camera), Bryce (112.5 degrees camera) or Terragen (Zoom = 1) for instance].


Parameters and Attributes

  • Parameter Types (pTypes)

  • Parameter Operations (paramOps)

  • Attributes and the Attributes Manager


Parameter Types

Parameter Types (pTypes)

Overview

The type of a parameter defines the kind of data that a parameter can hold. Parameters can be broadly grouped as:

  1. References or Pointers (CKObject Containers)
    The parameter identifies an object instantiated from the Virtools Class hierarchy (e.g. a 3D Entity, an Animation, a Script, etc.), most often from the Behavioral Object branch.

  2. Values (Base Parameters)
    The parameter contains a data value (e.g. a Color, a Keyboard Key, an Integer, etc.).

  3. Enumerations
    The parameter’s value is constrained to a range of predefined values (e.g. there are two options for the Fill Mode of a Material: Flat or Gouraud; the choice of Binary Operators (used for example by Mini Calculator (Logics/Calculator)) is constrained to +, -, /, *).

  4. Special (Flags and Structures)
    The parameter does not fit in the prior categories.
For a more detailed description of parameters and parameter types, see the SDK documentation.

References or Pointers (CKObject Containers)

These parameters identify an object instantiated from the CKClass hierarchy, most often from the Behavioral Object branch.

  • 2D Entity
  • 3D Entity
  • 3D Object
  • 3D Sprite
  • Animation
  • Array
  • Basic Object
  • Behavior
  • Behavioral Object
  • Body Part
  • Camera
  • Character
  • Critical Section
  • Curve
  • Curve Point
  • Group
  • Kinematic Chain
  • Level
  • Light
  • Material
  • Mesh
  • Midi Sound
  • Object Animation
  • Patch Mesh
  • Place
  • Render Object
  • Scene
  • Scene Object
  • Script
  • Sound
  • Sprite
  • Sprite Text
  • State
  • Synchronization Object
  • Target Camera
  • Target Light
  • Texture
  • Wave Sound

Values (Base Parameters)

The parameter contains a data value (e.g. a Color, a Keyboard Key, an Integer, etc.).

  • 2D Curve
  • Angle
  • Attribute
  • Boolean
  • Box
  • Collection
  • Color
  • Copy Dependencies
  • Delete Dependencies
  • Euler Angles
  • Float
  • Integer
  • Keyboard Key
  • LOD Options
  • Matrix
  • Message
  • None
  • Percentage
  • Quaternion
  • Rectangle
  • Replace Dependencies
  • Save Dependencies
  • State Chunk
  • String
  • Time
  • Vector
  • Vector 2D

Enumerations

The parameter’s value is constrained to a range of predefined values (listed in brackets).

  • 3DSprite Mode (Billboard , XRotate , YRotate , Orientable)
  • Address Mode (Wrap , Mirror , Clamp , Border)
  • Alignment (Top-Left , Top , Top-Right , Left , Center , Right , Bottom-Left , Bottom , Bottom-Right)
  • Array Column Type (Integer , Float , String , Object , Parameter)
  • Behavioral Rate (Linked to Frame Rate , Limit)
  • Binary Operator (+ , - , * , /)
  • Blend Factor (Zero , One , Source Color , Inverse Source Color , Source Alpha , Inverse Source Alpha , Destination Alpha , Inverse Destination Alpha , Destination Color , Inverse Destination Color , Source Alpha Saturation , Both Source Alpha , Both Inverse Source Alpha)
  • Comparison Operator (Equal , Not Equal , Less than , Less or equal , Greater than , Greater or equal)
  • Curve Rendering (Plane , Cross , Tube , 2D , Line)
  • Direction (X , -X , Y , -Y , Z , -Z)
  • Fill Mode (Point , WireFrame , Solid , OnlyZ)
  • Filter Mode (Nearest , Linear , MipNearest , MipLinear , LinearMipNearest , LinearMipLinear , Anisotropic)
  • Flow Alignment (Left , Center , Right)
  • Flow Direction (Left/Right , Up/Down , Rear/Front)
  • Flow Support (Front , In , Rear)
  • Fog Mode (None , Exponential , Exponential Squared , Linear)
  • Follow Mode (Step Follow , Simple Follow , Delayed Follow , Smooth Follow)
  • Font Name (depends on fonts available on client machine)
  • Font Resolution (128x128 , 256x256 , 512x512 , 1024x1024)
  • Font Type (No Font)
  • Font Weight (THIN , EXTRALIGHT , LIGHT , NORMAL , MEDIUM , DEMIBOLD , BOLD , EXTRABOLD , HEAVY)
  • Frame Rate (Free , Synchronize to Screen , Limit)
  • Geometry (Faces , Bounding Box)
  • Geometry Precision (Behavioral) (Automatic , BoundingBox , Faces)
  • Global Shade Mode (Wireframe , Flat , Gouraud , Material Default)
  • Intersection Precision Level (Bounding Box , Face)
  • Layer Square Type (Integer , Linker)
  • Layer Type (- default -)
  • Light Type (Point , Spot , Directional)
  • Linker (None , Start , End , Start/End , Door)
  • Lit Mode (Prelit , Lit)
  • Loop Mode (No Loop , Loop , To and Fro)
  • Mouse Button (Left , Middle , Right)
  • Mouse Pointers (Normal Select , Busy , Move , Link Select)
  • Path Type (Path ID , List of Point , Curve )
  • Projection Mode (Perspective , Orthographic)
  • Registered Class (2D Entity , 3D Entity , 3D Object , 3D Sprite , Animation , Array , Basic Object , Behavior IO , Behavior Link , Behavior , Behavioral Object , Body Part , Camera , Character , Critical Section , Curve Point , Curve , Grid Layer , Grid , Group , Keyed Animation , Kinematic Chain , Level , Light , Material , Mesh , Midi Sound , Object Animation , Parameter In , Parameter Local , Parameter Operation , Parameter Out , Parameter , Patch Mesh , Place , Render Context , Render Object , Scene Object , Scene , Sound , Sprite Text , Sprite , State , Synchronization Object , Target Camera , Target Light , Texture , VirtoolsInterfaceObject , Wave Sound , )
  • Registered Parameter (NA)
  • RGB Component (Red , Green , Blue)
  • Scene Activity Options (Scene Defaults , Force activate , Force deactivate , Do nothing)
  • Scene Reset Options (Scene Defaults , Force Reset , Do nothing)
  • Sets Operator (Union , Intersection , Subtraction)
  • Shade Mode (Flat , Gouraud)
  • Sound Type (Background , Point)
  • Sprite Text Alignment (Center , Left , Right , Top , Bottom , VCenter , HCenter)
  • Text Alignment (Left , Right , Center)
  • Texture Blend Mode (Decal , Modulate , DecalAlpha , ModulateAlpha , DecalMask , ModulateMask , Copy , Add)
  • Texture Video Format (32 bits ARGB 8888 , 32 bits RGB 888 , 24 bits RGB 888 , 16 bits RGB 565 , 16 bits RGB 555 , 16 bits ARGB 1555 , 16 bits ARGB 4444 , 8 bits RGB 332 , 8 bits ARGB 2222 , Compressed DXT1 , Compressed DXT3 , Compressed DXT5 , V8U8 BumpMap , L6V5U5 BumpMap)
  • Wrap Mode (None , V Looping , U Looping , UV Looping)
  • Z Compare Function (Never , Less , Equal , Less Equal , Greater , Not Equal , Greater Equal , Always)

Special (Flags and Structures)

The parameter type does not easily fit into any of the other categories.

  • BumpMap Parameters
  • Button Events
  • Collision
  • Combine 2 Textures
  • Combine 3 Textures
  • Filter
  • Floor
  • Keyboard Section
  • Obstacle
  • Render Options
  • Tex coords gen+Referential


Parameter Operations

Parameter Operations (paramOps)

You can see paramOps listed by result, operation type and the pIn (first or second). More information on paramOps in the concepts book and in the scripts book.

  • By Result
  • By Operation
  • By pIn 1
  • By pIn 2

    • Comments


Parameter Operations by Result Type

To see Parameter Operations listed differently, click column headers.

Result | Operation | Input 1 | Input 2 |
2D Entity | Get Parent | 2D Entity | None |
3D Entity | Get Parent | 3D Entity | None |
3D Entity | Get Root | Character | None |
3D Entity | Get Target | Target Camera | None |
3D Entity | Get Target | Target Light | None |
Animation | Get Animation | Character | String | retrieves a character's animation; Character's name contains the specified string
Basic Object | Get Element | Collection | Integer |
Basic Object | Get Element | Group | Integer |
Basic Object | Dynamic Cast | Basic Object | None | filters elements: ensures a BB that requires a specific CKClass only receives inputs of this type (e.g. in the case of iterating a Group, the elements can be of different classes, using this op only elements of the right CKClass are passed to the BB)
Basic Object | Convert | String | None | useful to cast a Group element (retrieved by Group Iterator BB for example) into a specific type
Basic Object | Get Object By Name | String | None |
Body Part | Get BodyPart | Character | String |
Boolean | Is Child Of | 3D Entity | 3D Entity |
Boolean | Is Collision | 3D Entity | 3D Entity |
Boolean | Is Collision | Box | 3D Entity |
Boolean | Is In | Vector | 3D Entity |
Boolean | Is Content Equal | Array | Array |
Boolean | Equal | Basic Object | Basic Object |
Boolean | Is Derived From | Basic Object | Basic Object | finds the parent type of the specified object (e.g. a 3D Object is derived from a 3D Entity)
Boolean | Not Equal | Basic Object | Basic Object |
Boolean | Addition | Collection | Basic Object |
Boolean | Is In | Collection | Basic Object |
Boolean | Subtraction | Collection | Basic Object |
Boolean | And | Boolean | Boolean |
Boolean | Equal | Boolean | Boolean |
Boolean | Not Equal | Boolean | Boolean |
Boolean | Or | Boolean | Boolean | Boolean inclusive logic operation (e.g. 0 Or 1=1; 1 Or 0=1; 0 Or 0=0; 1 Or 1=1)
Boolean | Xor | Boolean | Boolean | Boolean exclusive logic operation (e.g. 0 XOr 1=1; 1 XOr 0=1; 0 XOr 0=0; 1 XOr 1=0)
Boolean | Is Collision | Box | Box |
Boolean | Is Body Part Of | Body Part | Character |
Boolean | Equal | Collection | Collection |
Boolean | Equal | Color | Color |
Boolean | Not Equal | Color | Color |
Boolean | Equal | Euler Angles | Euler Angles |
Boolean | Not Equal | Euler Angles | Euler Angles |
Boolean | Equal | Float | Float |
Boolean | Inferior | Float | Float |
Boolean | Inferior or Equal | Float | Float |
Boolean | Not Equal | Float | Float |
Boolean | Superior | Float | Float |
Boolean | Superior or Equal | Float | Float |
Boolean | Equal | Integer | Float |
Boolean | Inferior | Integer | Float |
Boolean | Inferior or Equal | Integer | Float |
Boolean | Not Equal | Integer | Float |
Boolean | Superior | Integer | Float |
Boolean | Superior or Equal | Integer | Float |
Boolean | Equal | Multiuser Time | Float |
Boolean | Inferior | Multiuser Time | Float |
Boolean | Inferior or Equal | Multiuser Time | Float |
Boolean | Not Equal | Multiuser Time | Float |
Boolean | Superior | Multiuser Time | Float |
Boolean | Superior or Equal | Multiuser Time | Float |
Boolean | Is Content Equal | Group | Group |
Boolean | Inferior | Float | Integer |
Boolean | Inferior or Equal | Float | Integer |
Boolean | Superior | Float | Integer |
Boolean | Superior or Equal | Float | Integer |
Boolean | Equal | Integer | Integer |
Boolean | Inferior | Integer | Integer |
Boolean | Inferior or Equal | Integer | Integer |
Boolean | Is Note Active | Integer | Integer | checks if the specified note is activated or not (specific to the Midi Controller BB)
Boolean | Not Equal | Integer | Integer |
Boolean | Superior | Integer | Integer |
Boolean | Superior or Equal | Integer | Integer |
Boolean | Equal | Matrix | Matrix |
Boolean | Not Equal | Matrix | Matrix |
Boolean | Equal | Multiuser Time | Multiuser Time |
Boolean | Inferior | Multiuser Time | Multiuser Time |
Boolean | Inferior or Equal | Multiuser Time | Multiuser Time |
Boolean | Not Equal | Multiuser Time | Multiuser Time |
Boolean | Superior | Multiuser Time | Multiuser Time |
Boolean | Superior or Equal | Multiuser Time | Multiuser Time |
Boolean | Is Visible | 2D Entity | None |
Boolean | Is Visible | 3D Entity | None |
Boolean | Is Active | Behavioral Object | None |
Boolean | Not | Boolean | None |
Boolean | Opposite | Boolean | None |
Boolean | Convert | Float | None |
Boolean | Convert | Integer | None |
Boolean | Random | None | None |
Boolean | Is Active | Script | None |
Boolean | Is Looping | Wave Sound | None |
Boolean | Is Paused | Wave Sound | None |
Boolean | Is Playing | Wave Sound | None |
Boolean | Is Streaming | Wave Sound | None |
Boolean | Equal | Quaternion | Quaternion |
Boolean | Not Equal | Quaternion | Quaternion |
Boolean | Equal | Rectangle | Rectangle |
Boolean | Not Equal | Rectangle | Rectangle |
Boolean | Contain String | String | String |
Boolean | Equal | String | String |
Boolean | Is Collision | Box | Vector |
Boolean | Equal | Vector | Vector |
Boolean | Not Equal | Vector | Vector |
Boolean | Equal | Vector 2D | Vector 2D |
Boolean | Not Equal | Vector 2D | Vector 2D |
Box | Addition | Box | Box |
Box | Subtraction | Box | Box |
Box | Get Bounding Box | 3D Entity | None | World Bounding Box
Box | Get Hierarchical Bounding Box | 3D Entity | None |
Box | Get Bounding Box | Mesh | None | Local Bounding Box
Box | Convert | String | None |
Character | Get Character | 3D Entity | None | retrieves the Character who owns the specified 3D Entity (BodyPart)
Collection | And | Collection | Collection |
Collection | Or | Collection | Collection |
Collection | Subtraction | Collection | Collection |
Collection | Get Children | 3D Entity | None | retrieves a 3D Entity's children; 3D Entity's name must contain the specified string
Collection | Get Mesh List | 3D Entity | None |
Collection | Get Animation | Character | None | retrieves a Character's animations; Character's name must contain the specified string
Collection | Get BodyParts | Character | None | retrieves a Character's BodyParts; Character's name must contain the specified string
Collection | Get Material List | Mesh | None |
Collection | Get Portals | Place | None |
Collection | Get Portals | Place | Place |
Color | Addition | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Color | Subtraction | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Color | Multiplication | Float | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Color | Set Alpha | Color | Float |
Color | Set Blue | Color | Float |
Color | Set Green | Color | Float |
Color | Set Red | Color | Float |
Color | Rainbow Color | Float | Float | get the associated color (RGBA) from two floats (Hue and Luminosity) between 0 and 1
Color | Get Vertex Color | Mesh | Integer |
Color | Get Vertex Specular Color | Mesh | Integer |
Color | Inverse | Color | None |
Color | Get Color | Light | None |
Color | Get Ambient Color | Material | None |
Color | Get Diffuse Color | Material | None |
Color | Get Emissive Color | Material | None |
Color | Get Specular Color | Material | None |
Color | Random | None | None |
Color | Convert | String | None |
Curve Point | Get Curve Point | Curve | Integer |
Encrypted String | Convert | Percentage | None |
Encrypted String | Convert | Time | None |
Euler Angles | Get Euler Angles | 3D Entity | 3D Entity |
Euler Angles | Set X | Euler Angles | Float |
Euler Angles | Set Y | Euler Angles | Float |
Euler Angles | Set Z | Euler Angles | Float |
Euler Angles | Convert | Matrix | None |
Euler Angles | Convert | Quaternion | None |
Euler Angles | Convert | String | None |
Float | Get Distance | 2D Entity | 2D Entity |
Float | Get Distance | 3D Entity | 3D Entity |
Float | Get Length | Curve | Curve Point |
Float | Get Y | 2D Curve | Float |
Float | Addition | Float | Float |
Float | Arc Tangent 2 | Float | Float | gets the sine and cosine corresponding to the specified value
Float | Division | Float | Float |
Float | Max | Float | Float |
Float | Min | Float | Float |
Float | Multiplication | Float | Float |
Float | Random | Float | Float |
Float | Subtraction | Float | Float |
Float | Division | Integer | Float |
Float | Subtraction | Integer | Float |
Float | Addition | Float | Integer |
Float | Division | Float | Integer |
Float | Max | Float | Integer |
Float | Min | Float | Integer |
Float | Multiplication | Float | Integer |
Float | Subtraction | Float | Integer |
Float | Get Vertex Weight | Mesh | Integer | gets the weight of the specified vertex
Float | Get Length | 2D Curve | None |
Float | Get Radius | 3D Entity | None |
Float | Get X | 3D Entity | None |
Float | Get Y | 3D Entity | None |
Float | Get Z | 3D Entity | None |
Float | Get Length | Animation | None | number of animation frames expressed as a Float
Float | Convert | Boolean | None |
Float | Get Far Clip | Camera | None |
Float | Get Field Of View | Camera | None | note: you can specify Angle instead of Float as the result
Float | Get Near Clip | Camera | None |
Float | Get Orthographic Zoom | Camera | None |
Float | Get Alpha | Color | None |
Float | Get Blue | Color | None |
Float | Get Green | Color | None |
Float | Get Red | Color | None |
Float | Get Length | Curve | None |
Float | Get X | Euler Angles | None |
Float | Get Y | Euler Angles | None |
Float | Get Z | Euler Angles | None |
Float | Absolute Value | Float | None |
Float | Arc Cosine | Float | None |
Float | Arc Sine | Float | None |
Float | Cosine | Float | None |
Float | Degree To Radian | Float | None |
Float | Inverse | Float | None |
Float | Opposite | Float | None |
Float | Per Second | Float | None |
Float | Radian To Degree | Float | None |
Float | Sine | Float | None |
Float | Square Root | Float | None |
Float | Tangent | Float | None |
Float | Convert | Integer | None |
Float | Inverse | Integer | None |
Float | Get Range | Light | None |
Float | Get Specular Color Power | Material | None |
Float | Convert | Multiuser Time | None |
Float | Get W | Quaternion | None |
Float | Get X | Quaternion | None |
Float | Get Y | Quaternion | None |
Float | Get Z | Quaternion | None |
Float | Convert | String | None |
Float | Get Magnitude | Vector | None | gets the length of a vector
Float | Get X | Vector | None |
Float | Get Y | Vector | None |
Float | Get Z | Vector | None |
Float | Get Magnitude | Vector 2D | None |
Float | Get X | Vector 2D | None |
Float | Get Y | Vector 2D | None |
Float | Get Distance | Wave Sound | None |
Float | Get Gain | Wave Sound | None |
Float | Get Length | Wave Sound | None |
Float | Get Pan | Wave Sound | None |
Float | Get Pitch | Wave Sound | None |
Float | Dot Product | Vector | Vector |
Float | Get Angle | Vector | Vector |
Float | Get Distance | Vector | Vector |
Float | Dot Product | Vector 2D | Vector 2D |
Float | Get Angle | Vector 2D | Vector 2D |
Float | Get Distance | Vector 2D | Vector 2D |
Integer | Addition | Integer | Float |
Integer | Division | Integer | Float |
Integer | Max | Integer | Float |
Integer | Min | Integer | Float |
Integer | Multiplication | Integer | Float |
Integer | Subtraction | Integer | Float |
Integer | Division | Float | Integer |
Integer | Subtraction | Float | Integer |
Integer | Addition | Integer | Integer |
Integer | And | Integer | Integer | converts to Boolean before adding (e.g. 7 And 3 = 3, but 8 And 3 = 0)
Integer | Division | Integer | Integer |
Integer | Max | Integer | Integer |
Integer | Min | Integer | Integer |
Integer | Modulo | Integer | Integer |
Integer | Multiplication | Integer | Integer |
Integer | Or | Integer | Integer |
Integer | Random | Integer | Integer |
Integer | Subtraction | Integer | Integer |
Integer | Xor | Integer | Integer |
Integer | Get Channel By Material | Mesh | Material |
Integer | Get Height | 2D Entity | None |
Integer | Get Width | 2D Entity | None |
Integer | Get Animation Count | 3D Entity | None |
Integer | Get Column Count | Array | None |
Integer | Get Count | Array | None |
Integer | Get Row Count | Array | None |
Integer | Get Script Count | Behavioral Object | None |
Integer | Convert | Boolean | None |
Integer | Get Count | Collection | None |
Integer | Get Count | Curve | None |
Integer | Convert | Float | None |
Integer | Inverse | Float | None | 1 / x
Integer | Get Count | Group | None |
Integer | Absolute Value | Integer | None |
Integer | Opposite | Integer | None |
Integer | Get Channel Count | Mesh | None |
Integer | Get Face Count | Mesh | None |
Integer | Get Material Count | Mesh | None |
Integer | Get Vertex Count | Mesh | None |
Integer | Get Height | None | None |
Integer | Get Mouse X | None | None |
Integer | Get Mouse Y | None | None |
Integer | Get Width | None | None |
Integer | Get Current | Sprite | None |
Integer | Get Slot Count | Sprite | None |
Integer | Convert | String | None |
Integer | Get Length | String | None | length of "hello" = 5
Integer | Get PM Rendered Vertices Coun | t Mesh | None |
Integer | Get Current | Texture | None |
Integer | Get Height | Texture | None |
Integer | Get Slot Count | Texture | None |
Integer | Get Width | Texture | None |
Integer | Get Sampling Rate | Wave Sound | None |
Layer Type | Get Layer By Name | String | None |
Level | Get Current | None | None |
Material | Get Face Material | Mesh | Integer |
Material | Get Material | Mesh | Integer |
Material | Get Material | 2D Entity | None |
Material | Get Material | 3D Sprite | None |
Matrix | From Rotation | Vector | Angle |
Matrix | Multiplication | Matrix | Float |
Matrix | Addition | Matrix | Matrix |
Matrix | Division | Matrix | Matrix |
Matrix | Multiplication | Matrix | Matrix |
Matrix | Subtraction | Matrix | Matrix |
Matrix | Set Position | Vector | Matrix |
Matrix | Set X | Vector | Matrix |
Matrix | Set Y | Vector | Matrix |
Matrix | Set Z | Vector | Matrix |
Matrix | Get Local Matrix | 3D Entity | None |
Matrix | Get World Matrix | 3D Entity | None |
Matrix | Convert | Euler Angles | None |
Matrix | Inverse | Matrix | None |
Matrix | Convert | Quaternion | None |
Matrix | Convert | String | None |
Matrix | Convert | Vector | Vector |
Mesh | Get Current | 3D Entity | None |
Message | Convert | String | None |
Multiuser Session State | Get Session State | Integer | None |
Multiuser Time | Addition | Multiuser Time | Float |
Multiuser Time | Multiplication | Multiuser Time | Float |
Multiuser Time | Subtraction | Multiuser Time | Float |
Multiuser Time | Subtraction | Float | Multiuser Time |
Multiuser Time | Addition | Multiuser Time | Multiuser Time |
Multiuser Time | Subtraction | Multiuser Time | Multiuser Time |
Multiuser Time | Convert | String | None |
Object Animation | Get Animation | 3D Entity | Integer |
Object Animation | Get Animation | 3D Entity | String | retrieves an object's animation; object's name must contain the specified string
Physics Constraint | Convert | Percentage | None |
Physics Constraint | Convert | Time | None |
Physics Motor | Convert | Percentage | None |
Physics Motor | Convert | Time | None |
Physics Spring | Convert | Percentage | None |
Physics Spring | Convert | Time | None |
Physics Surface | Convert | Percentage | None |
Physics Surface | Convert | Time | None |
Place | Get Referential Place | 3D Entity | None | gets the Place containing the 3D Entity
Quaternion | From Rotation | Vector | Angle |
Quaternion | Set W | Quaternion | Float |
Quaternion | Set X | Quaternion | Float |
Quaternion | Set Y | Quaternion | Float |
Quaternion | Set Z | Quaternion | Float |
Quaternion | Convert | Euler Angles | None |
Quaternion | Convert | Matrix | None |
Quaternion | Convert | String | None |
Quaternion | Division | Quaternion | Quaternion |
Quaternion | Multiplication | Quaternion | Quaternion |
Rectangle | Set Bottom | Rectangle | Float |
Rectangle | Set Height | Rectangle | Float |
Rectangle | Set Left | Rectangle | Float |
Rectangle | Set Right | Rectangle | Float |
Rectangle | Set Top | Rectangle | Float |
Rectangle | Set Width | Rectangle | Float |
Rectangle | Get Bounding Box | 2D Entity | None |
Rectangle | Get Bounding Box | 3D Entity | None |
Rectangle | Get View Rect | None | None |
Rectangle | Get Rect | RenderTarget View | None |
Rectangle | Get Texture Rect | RenderTarget View | None |
Rectangle | Convert | String | None |
Rectangle | Transform | Rectangle | Rectangle |
Rectangle | Set Geometric Center | Rectangle | Vector 2D |
Rectangle | Transform | Rectangle | Vector 2D |
Registered Class | Get Type | Basic Object | None | returns the CK ClassID of the element
Registered Class | Get Group Type | Group | None | gets the CKClass of the elements of a specified Group (returns the common CKClass in the case of different element CKClasses)
Render Object | Pick Object | Integer | Integer |
Render Object | Pick Object | Vector 2D | None |
RenderTarget View | Set RTView | Texture | Rectangle |
Scene | Get Current | None | None |
Script | Get Script | Behavioral Object | Integer |
Script | Get Script | Behavioral Object | String | retrieves an element's script; the element's name must contain the specified string
Shader | Convert | Percentage | None |
Shader | Convert | Time | None |
Shader Pass | Convert | Percentage | None |
Shader Pass | Convert | Time | None |
Shader Technique | Convert | Percentage | None |
Shader Technique | Convert | Time | None |
String | Convert | Angle | None |
String | Convert | Attribute | None |
String | Get Name | Basic Object | None |
String | Convert | Boolean | None |
String | Convert | Color | None |
String | Convert | Float | None |
String | Convert | Integer | None |
String | Convert | Message | None |
String | Convert | Multiuser Time | None |
String | Convert | Rectangle | None |
String | Get Text | Sprite Text | None |
String | Convert | Vector | None |
String | Convert | Vector 2D | None |
String | Get Sound file Name | Wave Sound | None |
String | Addition | String | String | hello+" world" = "hello world"
Texture | Get Texture | Material | None |
Time | Get Played Time | Wave Sound | None |
Vector | Get Distance | 3D Entity | 3D Entity | returns vector distance (useful to get a direction)
Vector | Get Position | 3D Entity | 3D Entity | a 3D Entity's referential
Vector | Inverse Transform | Vector | 3D Entity | transforms a 3D Entity's position expressed in the World's co-ordinate system into a position expressed in its referential
Vector | Inverse Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector expressed in the World's co-ordinate system into a vector expressed in its referential
Vector | Transform | Vector | 3D Entity | transforms a 3D Entity's position in its referential to the World's co-ordinate system
Vector | Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector in its referential to the World's co-ordinate system
Vector | Get Curve Position | Float | Curve |
Vector | Get Curve Tangent | Float | Curve |
Vector | Spheric To Cartesian | Float | Float | do a conversion from spheric referential coordinates to cartesian referential coordinates (latitude and longitude (can be specified with angles))
Vector | Division | Vector | Float |
Vector | Multiplication | Vector | Float |
Vector | Set X | Vector | Float |
Vector | Set Y | Vector | Float |
Vector | Set Z | Vector | Float |
Vector | Transform | Vector 2D | Float |
Vector | Get Face Normal | Mesh | Integer |
Vector | Get Face Vertex Indices | Mesh | Integer |
Vector | Get Vertex Normal | Mesh | Integer |
Vector | Get Vertex Position | Mesh | Integer |
Vector | Multiplication | Vector | Matrix |
Vector | Multiplication | Vector | Multiuser Time |
Vector | Get Dir | 3D Entity | None | Z Vector
Vector | Get Geometric Center | 3D Entity | None |
Vector | Get Position | 3D Entity | None | in the World co-ordinate system
Vector | Get Right | 3D Entity | None | X Vector
Vector | Get Scale | 3D Entity | None |
Vector | Get Up | 3D Entity | None | Y Vector
Vector | Get Geometric Center | Box | None |
Vector | Get Scale | Box | None |
Vector | Max | Box | None |
Vector | Min | Box | None |
Vector | Get In Tangent | Curve Point | None |
Vector | Get Out Tangent | Curve Point | None |
Vector | Get Position | Matrix | None |
Vector | Get Scale | Matrix | None |
Vector | Get X | Matrix | None |
Vector | Get Y | Matrix | None |
Vector | Get Z | Matrix | None |
Vector | Random | None | None | between [0,0,0] and [1,1,1]
Vector | Convert | String | None |
Vector | Inverse | Vector | None |
Vector | Normalize | Vector | None |
Vector | Opposite | Vector | None |
Vector | Per Second | Vector | None |
Vector | Get Cone | Wave Sound | None |
Vector | Get Relative Direction | Wave Sound | None |
Vector | Get Relative Position | Wave Sound | None |
Vector | Get Velocity | Wave Sound | None |
Vector | Addition | Vector | Vector |
Vector | Cross Product | Vector | Vector | Cross Product is given by the formula c = ab
Vector | Division | Vector | Vector |
Vector | Max | Vector | Vector |
Vector | Min | Vector | Vector |
Vector | Multiplication | Vector | Vector |
Vector | Reflect | Vector | Vector | find the reflected vector from the specified vector axis referential
Vector | Subtraction | Vector | Vector |
Vector | Symmetry | Vector | Vector |
Vector | Convert | Vector | Vector 2D |
Vector 2D | Get Curve Position | Float | 2D Curve |
Vector 2D | Transform | Vector | 3D Entity | projects a 3D vector expressed in the 3D Entity's referential into the screen plane
Vector 2D | Convert | Float | Float |
Vector 2D | Division | Vector 2D | Float |
Vector 2D | Multiplication | Vector 2D | Float |
Vector 2D | Set X | Vector 2D | Float |
Vector 2D | Set Y | Vector 2D | Float |
Vector 2D | Convert | Integer | Integer |
Vector 2D | Get Vertex UVs | Mesh | Integer | get the UVs of the specified vertex
Vector 2D | Get Position | 2D Entity | None |
Vector 2D | Get Size | 2D Entity | None |
Vector 2D | Get Mouse Position | Boolean | None |
Vector 2D | Get Aspect Ratio | Camera | None |
Vector 2D | Get Mouse Position | None | None |
Vector 2D | Get Screen Origin | None | None |
Vector 2D | Random | None | None |
Vector 2D | Get Bottom-Right Corner | Rectangle | None |
Vector 2D | Get Geometric Center | Rectangle | None |
Vector 2D | Get Position | Rectangle | None |
Vector 2D | Get Size | Rectangle | None |
Vector 2D | Get Texel Size | RenderTarget View | None |
Vector 2D | Convert | String | None |
Vector 2D | Convert | Vector | None |
Vector 2D | Inverse | Vector 2D | None |
Vector 2D | Opposite | Vector 2D | None |
Vector 2D | Get Min Max | Wave Sound | None |
Vector 2D | Addition | Vector 2D | Vector 2D |
Vector 2D | Division | Vector 2D | Vector 2D |
Vector 2D | Max | Vector 2D | Vector 2D |
Vector 2D | Min | Vector 2D | Vector 2D |
Vector 2D | Multiplication | Vector 2D | Vector 2D |
Vector 2D | Subtraction | Vector 2D | Vector 2D |
Vector 2D | Symmetry | Vector 2D | Vector 2D |
Vector 4D | Convert | Vector | Float |
VSL Script | Convert | Percentage | None |
VSL Script | Convert | Time | None |


Parameter Operations by Operation Type

To see Parameter Operations listed differently, click column headers.

Result | Operation | Input 1 | Input 2 |
Float | Absolute Value | Float | None |
Integer | Absolute Value | Integer | None |
Boolean | Addition | Collection | Basic Object |
Box | Addition | Box | Box |
Color | Addition | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Float | Addition | Float | Float |
Float | Addition | Float | Integer |
Integer | Addition | Integer | Float |
Integer | Addition | Integer | Integer |
Matrix | Addition | Matrix | Matrix |
Multiuser Time | Addition | Multiuser Time | Float |
Multiuser Time | Addition | Multiuser Time | Multiuser Time |
String | Addition | String | String | hello+" world" = "hello world"
Vector | Addition | Vector | Vector |
Vector 2D | Addition | Vector 2D | Vector 2D |
Boolean | And | Boolean | Boolean |
Collection | And | Collection | Collection |
Integer | And | Integer | Integer | converts to Boolean before adding (e.g. 7 And 3 = 3, but 8 And 3 = 0)
Float | Arc Cosine | Float | None |
Float | Arc Sine | Float | None |
Float | Arc Tangent 2 | Float | Float | gets the sine and cosine corresponding to the specified value
Boolean | Contain String | String | String |
Basic Object | Convert | String | None | useful to cast a Group element (retrieved by Group Iterator BB for example) into a specific type
Boolean | Convert | Float | None |
Boolean | Convert | Integer | None |
Box | Convert | String | None |
Color | Convert | String | None |
Encrypted String | Convert | Percentage | None |
Encrypted String | Convert | Time | None |
Euler Angles | Convert | Matrix | None |
Euler Angles | Convert | Quaternion | None |
Euler Angles | Convert | String | None |
Float | Convert | Boolean | None |
Float | Convert | Integer | None |
Float | Convert | Multiuser Time | None |
Float | Convert | String | None |
Integer | Convert | Boolean | None |
Integer | Convert | Float | None |
Integer | Convert | String | None |
Matrix | Convert | Euler Angles | None |
Matrix | Convert | Quaternion | None |
Matrix | Convert | String | None |
Matrix | Convert | Vector | Vector |
Message | Convert | String | None |
Multiuser Time | Convert | String | None |
Physics Constraint | Convert | Percentage | None |
Physics Constraint | Convert | Time | None |
Physics Motor | Convert | Percentage | None |
Physics Motor | Convert | Time | None |
Physics Spring | Convert | Percentage | None |
Physics Spring | Convert | Time | None |
Physics Surface | Convert | Percentage | None |
Physics Surface | Convert | Time | None |
Quaternion | Convert | Euler Angles | None |
Quaternion | Convert | Matrix | None |
Quaternion | Convert | String | None |
Rectangle | Convert | String | None |
Shader | Convert | Percentage | None |
Shader | Convert | Time | None |
Shader Pass | Convert | Percentage | None |
Shader Pass | Convert | Time | None |
Shader Technique | Convert | Percentage | None |
Shader Technique | Convert | Time | None |
String | Convert | Angle | None |
String | Convert | Attribute | None |
String | Convert | Boolean | None |
String | Convert | Color | None |
String | Convert | Float | None |
String | Convert | Integer | None |
String | Convert | Message | None |
String | Convert | Multiuser Time | None |
String | Convert | Rectangle | None |
String | Convert | Vector | None |
String | Convert | Vector 2D | None |
Vector | Convert | String | None |
Vector | Convert | Vector | Vector 2D |
Vector 2D | Convert | Float | Float |
Vector 2D | Convert | Integer | Integer |
Vector 2D | Convert | String | None |
Vector 2D | Convert | Vector | None |
Vector 4D | Convert | Vector | Float |
VSL Script | Convert | Percentage | None |
VSL Script | Convert | Time | None |
Float | Cosine | Float | None |
Vector | Cross Product | Vector | Vector | Cross Product is given by the formula c = ab
Float | Degree To Radian | Float | None |
Float | Division | Float | Float |
Float | Division | Integer | Float |
Float | Division | Float | Integer |
Integer | Division | Integer | Float |
Integer | Division | Float | Integer |
Integer | Division | Integer | Integer |
Matrix | Division | Matrix | Matrix |
Quaternion | Division | Quaternion | Quaternion |
Vector | Division | Vector | Float |
Vector | Division | Vector | Vector |
Vector 2D | Division | Vector 2D | Float |
Vector 2D | Division | Vector 2D | Vector 2D |
Float | Dot Product | Vector | Vector |
Float | Dot Product | Vector 2D | Vector 2D |
Basic Object | Dynamic Cast | Basic Object | None | filters elements: ensures a BB that requires a specific CKClass only receives inputs of this type (e.g. in the case of iterating a Group, the elements can be of different classes, using this op only elements of the right CKClass are passed to the BB)
Boolean | Equal | Basic Object | Basic Object |
Boolean | Equal | Boolean | Boolean |
Boolean | Equal | Collection | Collection |
Boolean | Equal | Color | Color |
Boolean | Equal | Euler Angles | Euler Angles |
Boolean | Equal | Float | Float |
Boolean | Equal | Integer | Float |
Boolean | Equal | Multiuser Time | Float |
Boolean | Equal | Integer | Integer |
Boolean | Equal | Matrix | Matrix |
Boolean | Equal | Multiuser Time | Multiuser Time |
Boolean | Equal | Quaternion | Quaternion |
Boolean | Equal | Rectangle | Rectangle |
Boolean | Equal | String | String |
Boolean | Equal | Vector | Vector |
Boolean | Equal | Vector 2D | Vector 2D |
Matrix | From Rotation | Vector | Angle |
Quaternion | From Rotation | Vector | Angle |
Float | Get Alpha | Color | None |
Color | Get Ambient Color | Material | None |
Float | Get Angle | Vector | Vector |
Float | Get Angle | Vector 2D | Vector 2D |
Animation | Get Animation | Character | String | retrieves a character's animation; Character's name contains the specified string
Collection | Get Animation | Character | None | retrieves a Character's animations; Character's name must contain the specified string
Object Animation | Get Animation | 3D Entity | Integer |
Object Animation | Get Animation | 3D Entity | String | retrieves an object's animation; object's name must contain the specified string
Integer | Get Animation Count | 3D Entity | None |
Vector 2D | Get Aspect Ratio | Camera | None |
Float | Get Blue | Color | None |
Body Part | Get BodyPart | Character | String |
Collection | Get BodyParts | Character | None | retrieves a Character's BodyParts; Character's name must contain the specified string
Vector 2D | Get Bottom-Right Corner | Rectangle | None |
Box | Get Bounding Box | 3D Entity | None | World Bounding Box
Box | Get Bounding Box | Mesh | None | Local Bounding Box
Rectangle | Get Bounding Box | 2D Entity | None |
Rectangle | Get Bounding Box | 3D Entity | None |
Integer | Get Channel By Material | Mesh | Material |
Integer | Get Channel Count | Mesh | None |
Character | Get Character | 3D Entity | None | retrieves the Character who owns the specified 3D Entity (BodyPart)
Collection | Get Children | 3D Entity | None | retrieves a 3D Entity's children; 3D Entity's name must contain the specified string
Color | Get Color | Light | None |
Integer | Get Column Count | Array | None |
Vector | Get Cone | Wave Sound | None |
Integer | Get Count | Array | None |
Integer | Get Count | Collection | None |
Integer | Get Count | Curve | None |
Integer | Get Count | Group | None |
Integer | Get Current | Sprite | None |
Integer | Get Current | Texture | None |
Level | Get Current | None | None |
Mesh | Get Current | 3D Entity | None |
Scene | Get Current | None | None |
Curve Point | Get Curve Point | Curve | Integer |
Vector | Get Curve Position | Float | Curve |
Vector 2D | Get Curve Position | Float | 2D Curve |
Vector | Get Curve Tangent | Float | Curve |
Color | Get Diffuse Color | Material | None |
Vector | Get Dir | 3D Entity | None | Z Vector
Float | Get Distance | 2D Entity | 2D Entity |
Float | Get Distance | 3D Entity | 3D Entity |
Float | Get Distance | Wave Sound | None |
Float | Get Distance | Vector | Vector |
Float | Get Distance | Vector 2D | Vector 2D |
Vector | Get Distance | 3D Entity | 3D Entity | returns vector distance (useful to get a direction)
Basic Object | Get Element | Collection | Integer |
Basic Object | Get Element | Group | Integer |
Color | Get Emissive Color | Material | None |
Euler Angles | Get Euler Angles | 3D Entity | 3D Entity |
Integer | Get Face Count | Mesh | None |
Material | Get Face Material | Mesh | Integer |
Vector | Get Face Normal | Mesh | Integer |
Vector | Get Face Vertex Indices | Mesh | Integer |
Float | Get Far Clip | Camera | None |
Float | Get Field Of View | Camera | None | note: you can specify Angle instead of Float as the result
Float | Get Gain | Wave Sound | None |
Vector | Get Geometric Center | 3D Entity | None |
Vector | Get Geometric Center | Box | None |
Vector 2D | Get Geometric Center | Rectangle | None |
Float | Get Green | Color | None |
Registered Class | Get Group Type | Group | None | gets the CKClass of the elements of a specified Group (returns the common CKClass in the case of different element CKClasses)
Integer | Get Height | 2D Entity | None |
Integer | Get Height | None | None |
Integer | Get Height | Texture | None |
Box | Get Hierarchical Bounding Box | 3D Entity | None |
Vector | Get In Tangent | Curve Point | None |
Layer Type | Get Layer By Name | String | None |
Float | Get Length | Curve | Curve Point |
Float | Get Length | 2D Curve | None |
Float | Get Length | Animation | None | number of animation frames expressed as a Float
Float | Get Length | Curve | None |
Float | Get Length | Wave Sound | None |
Integer | Get Length | String | None | length of "hello" = 5
Matrix | Get Local Matrix | 3D Entity | None |
Float | Get Magnitude | Vector | None | gets the length of a vector
Float | Get Magnitude | Vector 2D | None |
Material | Get Material | Mesh | Integer |
Material | Get Material | 2D Entity | None |
Material | Get Material | 3D Sprite | None |
Integer | Get Material Count | Mesh | None |
Collection | Get Material List | Mesh | None |
Collection | Get Mesh List | 3D Entity | None |
Vector 2D | Get Min Max | Wave Sound | None |
Vector 2D | Get Mouse Position | Boolean | None |
Vector 2D | Get Mouse Position | None | None |
Integer | Get Mouse X | None | None |
Integer | Get Mouse Y | None | None |
String | Get Name | Basic Object | None |
Float | Get Near Clip | Camera | None |
Basic Object | Get Object By Name | String | None |
Float | Get Orthographic Zoom | Camera | None |
Vector | Get Out Tangent | Curve Point | None |
Float | Get Pan | Wave Sound | None |
2D Entity | Get Parent | 2D Entity | None |
3D Entity | Get Parent | 3D Entity | None |
Float | Get Pitch | Wave Sound | None |
Time | Get Played Time | Wave Sound | None |
Integer | Get PM Rendered Vertices Coun | t Mesh | None |
Collection | Get Portals | Place | None |
Collection | Get Portals | Place | Place |
Vector | Get Position | 3D Entity | 3D Entity | a 3D Entity's referential
Vector | Get Position | 3D Entity | None | in the World co-ordinate system
Vector | Get Position | Matrix | None |
Vector 2D | Get Position | 2D Entity | None |
Vector 2D | Get Position | Rectangle | None |
Float | Get Radius | 3D Entity | None |
Float | Get Range | Light | None |
Rectangle | Get Rect | RenderTarget View | None |
Float | Get Red | Color | None |
Place | Get Referential Place | 3D Entity | None | gets the Place containing the 3D Entity
Vector | Get Relative Direction | Wave Sound | None |
Vector | Get Relative Position | Wave Sound | None |
Vector | Get Right | 3D Entity | None | X Vector
3D Entity | Get Root | Character | None |
Integer | Get Row Count | Array | None |
Integer | Get Sampling Rate | Wave Sound | None |
Vector | Get Scale | 3D Entity | None |
Vector | Get Scale | Box | None |
Vector | Get Scale | Matrix | None |
Vector 2D | Get Screen Origin | None | None |
Script | Get Script | Behavioral Object | Integer |
Script | Get Script | Behavioral Object | String | retrieves an element's script; the element's name must contain the specified string
Integer | Get Script Count | Behavioral Object | None |
Multiuser Session State | Get Session State | Integer | None |
Vector 2D | Get Size | 2D Entity | None |
Vector 2D | Get Size | Rectangle | None |
Integer | Get Slot Count | Sprite | None |
Integer | Get Slot Count | Texture | None |
String | Get Sound file Name | Wave Sound | None |
Color | Get Specular Color | Material | None |
Float | Get Specular Color Power | Material | None |
3D Entity | Get Target | Target Camera | None |
3D Entity | Get Target | Target Light | None |
Vector 2D | Get Texel Size | RenderTarget View | None |
String | Get Text | Sprite Text | None |
Texture | Get Texture | Material | None |
Rectangle | Get Texture Rect | RenderTarget View | None |
Registered Class | Get Type | Basic Object | None | returns the CK ClassID of the element
Vector | Get Up | 3D Entity | None | Y Vector
Vector | Get Velocity | Wave Sound | None |
Color | Get Vertex Color | Mesh | Integer |
Integer | Get Vertex Count | Mesh | None |
Vector | Get Vertex Normal | Mesh | Integer |
Vector | Get Vertex Position | Mesh | Integer |
Color | Get Vertex Specular Color | Mesh | Integer |
Vector 2D | Get Vertex UVs | Mesh | Integer | get the UVs of the specified vertex
Float | Get Vertex Weight | Mesh | Integer | gets the weight of the specified vertex
Rectangle | Get View Rect | None | None |
Float | Get W | Quaternion | None |
Integer | Get Width | 2D Entity | None |
Integer | Get Width | None | None |
Integer | Get Width | Texture | None |
Matrix | Get World Matrix | 3D Entity | None |
Float | Get X | 3D Entity | None |
Float | Get X | Euler Angles | None |
Float | Get X | Quaternion | None |
Float | Get X | Vector | None |
Float | Get X | Vector 2D | None |
Vector | Get X | Matrix | None |
Float | Get Y | 2D Curve | Float |
Float | Get Y | 3D Entity | None |
Float | Get Y | Euler Angles | None |
Float | Get Y | Quaternion | None |
Float | Get Y | Vector | None |
Float | Get Y | Vector 2D | None |
Vector | Get Y | Matrix | None |
Float | Get Z | 3D Entity | None |
Float | Get Z | Euler Angles | None |
Float | Get Z | Quaternion | None |
Float | Get Z | Vector | None |
Vector | Get Z | Matrix | None |
Boolean | Inferior | Float | Float |
Boolean | Inferior | Integer | Float |
Boolean | Inferior | Multiuser Time | Float |
Boolean | Inferior | Float | Integer |
Boolean | Inferior | Integer | Integer |
Boolean | Inferior | Multiuser Time | Multiuser Time |
Boolean | Inferior or Equal | Float | Float |
Boolean | Inferior or Equal | Integer | Float |
Boolean | Inferior or Equal | Multiuser Time | Float |
Boolean | Inferior or Equal | Float | Integer |
Boolean | Inferior or Equal | Integer | Integer |
Boolean | Inferior or Equal | Multiuser Time | Multiuser Time |
Color | Inverse | Color | None |
Float | Inverse | Float | None |
Float | Inverse | Integer | None |
Integer | Inverse | Float | None | 1 / x
Matrix | Inverse | Matrix | None |
Vector | Inverse | Vector | None |
Vector 2D | Inverse | Vector 2D | None |
Vector | Inverse Transform | Vector | 3D Entity | transforms a 3D Entity's position expressed in the World's co-ordinate system into a position expressed in its referential
Vector | Inverse Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector expressed in the World's co-ordinate system into a vector expressed in its referential
Boolean | Is Active | Behavioral Object | None |
Boolean | Is Active | Script | None |
Boolean | Is Body Part Of | Body Part | Character |
Boolean | Is Child Of | 3D Entity | 3D Entity |
Boolean | Is Collision | 3D Entity | 3D Entity |
Boolean | Is Collision | Box | 3D Entity |
Boolean | Is Collision | Box | Box |
Boolean | Is Collision | Box | Vector |
Boolean | Is Content Equal | Array | Array |
Boolean | Is Content Equal | Group | Group |
Boolean | Is Derived From | Basic Object | Basic Object | finds the parent type of the specified object (e.g. a 3D Object is derived from a 3D Entity)
Boolean | Is In | Vector | 3D Entity |
Boolean | Is In | Collection | Basic Object |
Boolean | Is Looping | Wave Sound | None |
Boolean | Is Note Active | Integer | Integer | checks if the specified note is activated or not (specific to the Midi Controller BB)
Boolean | Is Paused | Wave Sound | None |
Boolean | Is Playing | Wave Sound | None |
Boolean | Is Streaming | Wave Sound | None |
Boolean | Is Visible | 2D Entity | None |
Boolean | Is Visible | 3D Entity | None |
Float | Max | Float | Float |
Float | Max | Float | Integer |
Integer | Max | Integer | Float |
Integer | Max | Integer | Integer |
Vector | Max | Box | None |
Vector | Max | Vector | Vector |
Vector 2D | Max | Vector 2D | Vector 2D |
Float | Min | Float | Float |
Float | Min | Float | Integer |
Integer | Min | Integer | Float |
Integer | Min | Integer | Integer |
Vector | Min | Box | None |
Vector | Min | Vector | Vector |
Vector 2D | Min | Vector 2D | Vector 2D |
Integer | Modulo | Integer | Integer |
Color | Multiplication | Float | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Float | Multiplication | Float | Float |
Float | Multiplication | Float | Integer |
Integer | Multiplication | Integer | Float |
Integer | Multiplication | Integer | Integer |
Matrix | Multiplication | Matrix | Float |
Matrix | Multiplication | Matrix | Matrix |
Multiuser Time | Multiplication | Multiuser Time | Float |
Quaternion | Multiplication | Quaternion | Quaternion |
Vector | Multiplication | Vector | Float |
Vector | Multiplication | Vector | Matrix |
Vector | Multiplication | Vector | Multiuser Time |
Vector | Multiplication | Vector | Vector |
Vector 2D | Multiplication | Vector 2D | Float |
Vector 2D | Multiplication | Vector 2D | Vector 2D |
Vector | Normalize | Vector | None |
Boolean | Not | Boolean | None |
Boolean | Not Equal | Basic Object | Basic Object |
Boolean | Not Equal | Boolean | Boolean |
Boolean | Not Equal | Color | Color |
Boolean | Not Equal | Euler Angles | Euler Angles |
Boolean | Not Equal | Float | Float |
Boolean | Not Equal | Integer | Float |
Boolean | Not Equal | Multiuser Time | Float |
Boolean | Not Equal | Integer | Integer |
Boolean | Not Equal | Matrix | Matrix |
Boolean | Not Equal | Multiuser Time | Multiuser Time |
Boolean | Not Equal | Quaternion | Quaternion |
Boolean | Not Equal | Rectangle | Rectangle |
Boolean | Not Equal | Vector | Vector |
Boolean | Not Equal | Vector 2D | Vector 2D |
Boolean | Opposite | Boolean | None |
Float | Opposite | Float | None |
Integer | Opposite | Integer | None |
Vector | Opposite | Vector | None |
Vector 2D | Opposite | Vector 2D | None |
Boolean | Or | Boolean | Boolean | Boolean inclusive logic operation (e.g. 0 Or 1=1; 1 Or 0=1; 0 Or 0=0; 1 Or 1=1)
Collection | Or | Collection | Collection |
Integer | Or | Integer | Integer |
Float | Per Second | Float | None |
Vector | Per Second | Vector | None |
Render Object | Pick Object | Integer | Integer |
Render Object | Pick Object | Vector 2D | None |
Float | Radian To Degree | Float | None |
Color | Rainbow Color | Float | Float | get the associated color (RGBA) from two floats (Hue and Luminosity) between 0 and 1
Boolean | Random | None | None |
Color | Random | None | None |
Float | Random | Float | Float |
Integer | Random | Integer | Integer |
Vector | Random | None | None | between [0,0,0] and [1,1,1]
Vector 2D | Random | None | None |
Vector | Reflect | Vector | Vector | find the reflected vector from the specified vector axis referential
Color | Set Alpha | Color | Float |
Color | Set Blue | Color | Float |
Rectangle | Set Bottom | Rectangle | Float |
Rectangle | Set Geometric Center | Rectangle | Vector 2D |
Color | Set Green | Color | Float |
Rectangle | Set Height | Rectangle | Float |
Rectangle | Set Left | Rectangle | Float |
Matrix | Set Position | Vector | Matrix |
Color | Set Red | Color | Float |
Rectangle | Set Right | Rectangle | Float |
RenderTarget View | Set RTView | Texture | Rectangle |
Rectangle | Set Top | Rectangle | Float |
Quaternion | Set W | Quaternion | Float |
Rectangle | Set Width | Rectangle | Float |
Euler Angles | Set X | Euler Angles | Float |
Matrix | Set X | Vector | Matrix |
Quaternion | Set X | Quaternion | Float |
Vector | Set X | Vector | Float |
Vector 2D | Set X | Vector 2D | Float |
Euler Angles | Set Y | Euler Angles | Float |
Matrix | Set Y | Vector | Matrix |
Quaternion | Set Y | Quaternion | Float |
Vector | Set Y | Vector | Float |
Vector 2D | Set Y | Vector 2D | Float |
Euler Angles | Set Z | Euler Angles | Float |
Matrix | Set Z | Vector | Matrix |
Quaternion | Set Z | Quaternion | Float |
Vector | Set Z | Vector | Float |
Float | Sine | Float | None |
Vector | Spheric To Cartesian | Float | Float | do a conversion from spheric referential coordinates to cartesian referential coordinates (latitude and longitude (can be specified with angles))
Float | Square Root | Float | None |
Boolean | Subtraction | Collection | Basic Object |
Box | Subtraction | Box | Box |
Collection | Subtraction | Collection | Collection |
Color | Subtraction | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Float | Subtraction | Float | Float |
Float | Subtraction | Integer | Float |
Float | Subtraction | Float | Integer |
Integer | Subtraction | Integer | Float |
Integer | Subtraction | Float | Integer |
Integer | Subtraction | Integer | Integer |
Matrix | Subtraction | Matrix | Matrix |
Multiuser Time | Subtraction | Multiuser Time | Float |
Multiuser Time | Subtraction | Float | Multiuser Time |
Multiuser Time | Subtraction | Multiuser Time | Multiuser Time |
Vector | Subtraction | Vector | Vector |
Vector 2D | Subtraction | Vector 2D | Vector 2D |
Boolean | Superior | Float | Float |
Boolean | Superior | Integer | Float |
Boolean | Superior | Multiuser Time | Float |
Boolean | Superior | Float | Integer |
Boolean | Superior | Integer | Integer |
Boolean | Superior | Multiuser Time | Multiuser Time |
Boolean | Superior or Equal | Float | Float |
Boolean | Superior or Equal | Integer | Float |
Boolean | Superior or Equal | Multiuser Time | Float |
Boolean | Superior or Equal | Float | Integer |
Boolean | Superior or Equal | Integer | Integer |
Boolean | Superior or Equal | Multiuser Time | Multiuser Time |
Vector | Symmetry | Vector | Vector |
Vector 2D | Symmetry | Vector 2D | Vector 2D |
Float | Tangent | Float | None |
Rectangle | Transform | Rectangle | Rectangle |
Rectangle | Transform | Rectangle | Vector 2D |
Vector | Transform | Vector | 3D Entity | transforms a 3D Entity's position in its referential to the World's co-ordinate system
Vector | Transform | Vector 2D | Float |
Vector 2D | Transform | Vector | 3D Entity | projects a 3D vector expressed in the 3D Entity's referential into the screen plane
Vector | Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector in its referential to the World's co-ordinate system
Boolean | Xor | Boolean | Boolean | Boolean exclusive logic operation (e.g. 0 XOr 1=1; 1 XOr 0=1; 0 XOr 0=0; 1 XOr 1=0)
Integer | Xor | Integer | Integer |


Parameter Operations by First Input Type

To see Parameter Operations listed differently, click column headers.

Result | Operation | Input 1 | Input 2 |
Float | Get Length | 2D Curve | None |
Float | Get Y | 2D Curve | Float |
Rectangle | Get Bounding Box | 2D Entity | None |
Float | Get Distance | 2D Entity | 2D Entity |
Integer | Get Height | 2D Entity | None |
Material | Get Material | 2D Entity | None |
2D Entity | Get Parent | 2D Entity | None |
Vector 2D | Get Position | 2D Entity | None |
Vector 2D | Get Size | 2D Entity | None |
Integer | Get Width | 2D Entity | None |
Boolean | Is Visible | 2D Entity | None |
Object Animation | Get Animation | 3D Entity | Integer |
Object Animation | Get Animation | 3D Entity | String | retrieves an object's animation; object's name must contain the specified string
Integer | Get Animation Count | 3D Entity | None |
Box | Get Bounding Box | 3D Entity | None | World Bounding Box
Rectangle | Get Bounding Box | 3D Entity | None |
Character | Get Character | 3D Entity | None | retrieves the Character who owns the specified 3D Entity (BodyPart)
Collection | Get Children | 3D Entity | None | retrieves a 3D Entity's children; 3D Entity's name must contain the specified string
Mesh | Get Current | 3D Entity | None |
Vector | Get Dir | 3D Entity | None | Z Vector
Float | Get Distance | 3D Entity | 3D Entity |
Vector | Get Distance | 3D Entity | 3D Entity | returns vector distance (useful to get a direction)
Euler Angles | Get Euler Angles | 3D Entity | 3D Entity |
Vector | Get Geometric Center | 3D Entity | None |
Box | Get Hierarchical Bounding Box | 3D Entity | None |
Matrix | Get Local Matrix | 3D Entity | None |
Collection | Get Mesh List | 3D Entity | None |
3D Entity | Get Parent | 3D Entity | None |
Vector | Get Position | 3D Entity | 3D Entity | a 3D Entity's referential
Vector | Get Position | 3D Entity | None | in the World co-ordinate system
Float | Get Radius | 3D Entity | None |
Place | Get Referential Place | 3D Entity | None | gets the Place containing the 3D Entity
Vector | Get Right | 3D Entity | None | X Vector
Vector | Get Scale | 3D Entity | None |
Vector | Get Up | 3D Entity | None | Y Vector
Matrix | Get World Matrix | 3D Entity | None |
Float | Get X | 3D Entity | None |
Float | Get Y | 3D Entity | None |
Float | Get Z | 3D Entity | None |
Boolean | Is Child Of | 3D Entity | 3D Entity |
Boolean | Is Collision | 3D Entity | 3D Entity |
Boolean | Is Visible | 3D Entity | None |
Material | Get Material | 3D Sprite | None |
String | Convert | Angle | None |
Float | Get Length | Animation | None | number of animation frames expressed as a Float
Integer | Get Column Count | Array | None |
Integer | Get Count | Array | None |
Integer | Get Row Count | Array | None |
Boolean | Is Content Equal | Array | Array |
String | Convert | Attribute | None |
Basic Object | Dynamic Cast | Basic Object | None | filters elements: ensures a BB that requires a specific CKClass only receives inputs of this type (e.g. in the case of iterating a Group, the elements can be of different classes, using this op only elements of the right CKClass are passed to the BB)
Boolean | Equal | Basic Object | Basic Object |
String | Get Name | Basic Object | None |
Registered Class | Get Type | Basic Object | None | returns the CK ClassID of the element
Boolean | Is Derived From | Basic Object | Basic Object | finds the parent type of the specified object (e.g. a 3D Object is derived from a 3D Entity)
Boolean | Not Equal | Basic Object | Basic Object |
Script | Get Script | Behavioral Object | Integer |
Script | Get Script | Behavioral Object | String | retrieves an element's script; the element's name must contain the specified string
Integer | Get Script Count | Behavioral Object | None |
Boolean | Is Active | Behavioral Object | None |
Boolean | Is Body Part Of | Body Part | Character |
Boolean | And | Boolean | Boolean |
Float | Convert | Boolean | None |
Integer | Convert | Boolean | None |
String | Convert | Boolean | None |
Boolean | Equal | Boolean | Boolean |
Vector 2D | Get Mouse Position | Boolean | None |
Boolean | Not | Boolean | None |
Boolean | Not Equal | Boolean | Boolean |
Boolean | Opposite | Boolean | None |
Boolean | Or | Boolean | Boolean | Boolean inclusive logic operation (e.g. 0 Or 1=1; 1 Or 0=1; 0 Or 0=0; 1 Or 1=1)
Boolean | Xor | Boolean | Boolean | Boolean exclusive logic operation (e.g. 0 XOr 1=1; 1 XOr 0=1; 0 XOr 0=0; 1 XOr 1=0)
Box | Addition | Box | Box |
Vector | Get Geometric Center | Box | None |
Vector | Get Scale | Box | None |
Boolean | Is Collision | Box | 3D Entity |
Boolean | Is Collision | Box | Box |
Boolean | Is Collision | Box | Vector |
Vector | Max | Box | None |
Vector | Min | Box | None |
Box | Subtraction | Box | Box |
Vector 2D | Get Aspect Ratio | Camera | None |
Float | Get Far Clip | Camera | None |
Float | Get Field Of View | Camera | None | note: you can specify Angle instead of Float as the result
Float | Get Near Clip | Camera | None |
Float | Get Orthographic Zoom | Camera | None |
Animation | Get Animation | Character | String | retrieves a character's animation; Character's name contains the specified string
Collection | Get Animation | Character | None | retrieves a Character's animations; Character's name must contain the specified string
Body Part | Get BodyPart | Character | String |
Collection | Get BodyParts | Character | None | retrieves a Character's BodyParts; Character's name must contain the specified string
3D Entity | Get Root | Character | None |
Boolean | Addition | Collection | Basic Object |
Collection | And | Collection | Collection |
Boolean | Equal | Collection | Collection |
Integer | Get Count | Collection | None |
Basic Object | Get Element | Collection | Integer |
Boolean | Is In | Collection | Basic Object |
Collection | Or | Collection | Collection |
Boolean | Subtraction | Collection | Basic Object |
Collection | Subtraction | Collection | Collection |
Color | Addition | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
String | Convert | Color | None |
Boolean | Equal | Color | Color |
Float | Get Alpha | Color | None |
Float | Get Blue | Color | None |
Float | Get Green | Color | None |
Float | Get Red | Color | None |
Color | Inverse | Color | None |
Boolean | Not Equal | Color | Color |
Color | Set Alpha | Color | Float |
Color | Set Blue | Color | Float |
Color | Set Green | Color | Float |
Color | Set Red | Color | Float |
Color | Subtraction | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Integer | Get Count | Curve | None |
Curve Point | Get Curve Point | Curve | Integer |
Float | Get Length | Curve | Curve Point |
Float | Get Length | Curve | None |
Vector | Get In Tangent | Curve Point | None |
Vector | Get Out Tangent | Curve Point | None |
Matrix | Convert | Euler Angles | None |
Quaternion | Convert | Euler Angles | None |
Boolean | Equal | Euler Angles | Euler Angles |
Float | Get X | Euler Angles | None |
Float | Get Y | Euler Angles | None |
Float | Get Z | Euler Angles | None |
Boolean | Not Equal | Euler Angles | Euler Angles |
Euler Angles | Set X | Euler Angles | Float |
Euler Angles | Set Y | Euler Angles | Float |
Euler Angles | Set Z | Euler Angles | Float |
Float | Absolute Value | Float | None |
Float | Addition | Float | Float |
Float | Addition | Float | Integer |
Float | Arc Cosine | Float | None |
Float | Arc Sine | Float | None |
Float | Arc Tangent 2 | Float | Float | gets the sine and cosine corresponding to the specified value
Boolean | Convert | Float | None |
Integer | Convert | Float | None |
String | Convert | Float | None |
Vector 2D | Convert | Float | Float |
Float | Cosine | Float | None |
Float | Degree To Radian | Float | None |
Float | Division | Float | Float |
Float | Division | Float | Integer |
Integer | Division | Float | Integer |
Boolean | Equal | Float | Float |
Vector | Get Curve Position | Float | Curve |
Vector 2D | Get Curve Position | Float | 2D Curve |
Vector | Get Curve Tangent | Float | Curve |
Boolean | Inferior | Float | Float |
Boolean | Inferior | Float | Integer |
Boolean | Inferior or Equal | Float | Float |
Boolean | Inferior or Equal | Float | Integer |
Float | Inverse | Float | None |
Integer | Inverse | Float | None | 1 / x
Float | Max | Float | Float |
Float | Max | Float | Integer |
Float | Min | Float | Float |
Float | Min | Float | Integer |
Color | Multiplication | Float | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Float | Multiplication | Float | Float |
Float | Multiplication | Float | Integer |
Boolean | Not Equal | Float | Float |
Float | Opposite | Float | None |
Float | Per Second | Float | None |
Float | Radian To Degree | Float | None |
Color | Rainbow Color | Float | Float | get the associated color (RGBA) from two floats (Hue and Luminosity) between 0 and 1
Float | Random | Float | Float |
Float | Sine | Float | None |
Vector | Spheric To Cartesian | Float | Float | do a conversion from spheric referential coordinates to cartesian referential coordinates (latitude and longitude (can be specified with angles))
Float | Square Root | Float | None |
Float | Subtraction | Float | Float |
Float | Subtraction | Float | Integer |
Integer | Subtraction | Float | Integer |
Multiuser Time | Subtraction | Float | Multiuser Time |
Boolean | Superior | Float | Float |
Boolean | Superior | Float | Integer |
Boolean | Superior or Equal | Float | Float |
Boolean | Superior or Equal | Float | Integer |
Float | Tangent | Float | None |
Integer | Get Count | Group | None |
Basic Object | Get Element | Group | Integer |
Registered Class | Get Group Type | Group | None | gets the CKClass of the elements of a specified Group (returns the common CKClass in the case of different element CKClasses)
Boolean | Is Content Equal | Group | Group |
Integer | Absolute Value | Integer | None |
Integer | Addition | Integer | Float |
Integer | Addition | Integer | Integer |
Integer | And | Integer | Integer | converts to Boolean before adding (e.g. 7 And 3 = 3, but 8 And 3 = 0)
Boolean | Convert | Integer | None |
Float | Convert | Integer | None |
String | Convert | Integer | None |
Vector 2D | Convert | Integer | Integer |
Float | Division | Integer | Float |
Integer | Division | Integer | Float |
Integer | Division | Integer | Integer |
Boolean | Equal | Integer | Float |
Boolean | Equal | Integer | Integer |
Multiuser Session State | Get Session State | Integer | None |
Boolean | Inferior | Integer | Float |
Boolean | Inferior | Integer | Integer |
Boolean | Inferior or Equal | Integer | Float |
Boolean | Inferior or Equal | Integer | Integer |
Float | Inverse | Integer | None |
Boolean | Is Note Active | Integer | Integer | checks if the specified note is activated or not (specific to the Midi Controller BB)
Integer | Max | Integer | Float |
Integer | Max | Integer | Integer |
Integer | Min | Integer | Float |
Integer | Min | Integer | Integer |
Integer | Modulo | Integer | Integer |
Integer | Multiplication | Integer | Float |
Integer | Multiplication | Integer | Integer |
Boolean | Not Equal | Integer | Float |
Boolean | Not Equal | Integer | Integer |
Integer | Opposite | Integer | None |
Integer | Or | Integer | Integer |
Render Object | Pick Object | Integer | Integer |
Integer | Random | Integer | Integer |
Float | Subtraction | Integer | Float |
Integer | Subtraction | Integer | Float |
Integer | Subtraction | Integer | Integer |
Boolean | Superior | Integer | Float |
Boolean | Superior | Integer | Integer |
Boolean | Superior or Equal | Integer | Float |
Boolean | Superior or Equal | Integer | Integer |
Integer | Xor | Integer | Integer |
Color | Get Color | Light | None |
Float | Get Range | Light | None |
Color | Get Ambient Color | Material | None |
Color | Get Diffuse Color | Material | None |
Color | Get Emissive Color | Material | None |
Color | Get Specular Color | Material | None |
Float | Get Specular Color Power | Material | None |
Texture | Get Texture | Material | None |
Matrix | Addition | Matrix | Matrix |
Euler Angles | Convert | Matrix | None |
Quaternion | Convert | Matrix | None |
Matrix | Division | Matrix | Matrix |
Boolean | Equal | Matrix | Matrix |
Vector | Get Position | Matrix | None |
Vector | Get Scale | Matrix | None |
Vector | Get X | Matrix | None |
Vector | Get Y | Matrix | None |
Vector | Get Z | Matrix | None |
Matrix | Inverse | Matrix | None |
Matrix | Multiplication | Matrix | Float |
Matrix | Multiplication | Matrix | Matrix |
Boolean | Not Equal | Matrix | Matrix |
Matrix | Subtraction | Matrix | Matrix |
Box | Get Bounding Box | Mesh | None | Local Bounding Box
Integer | Get Channel By Material | Mesh | Material |
Integer | Get Channel Count | Mesh | None |
Integer | Get Face Count | Mesh | None |
Material | Get Face Material | Mesh | Integer |
Vector | Get Face Normal | Mesh | Integer |
Vector | Get Face Vertex Indices | Mesh | Integer |
Material | Get Material | Mesh | Integer |
Integer | Get Material Count | Mesh | None |
Collection | Get Material List | Mesh | None |
Color | Get Vertex Color | Mesh | Integer |
Integer | Get Vertex Count | Mesh | None |
Vector | Get Vertex Normal | Mesh | Integer |
Vector | Get Vertex Position | Mesh | Integer |
Color | Get Vertex Specular Color | Mesh | Integer |
Vector 2D | Get Vertex UVs | Mesh | Integer | get the UVs of the specified vertex
Float | Get Vertex Weight | Mesh | Integer | gets the weight of the specified vertex
String | Convert | Message | None |
Multiuser Time | Addition | Multiuser Time | Float |
Multiuser Time | Addition | Multiuser Time | Multiuser Time |
Float | Convert | Multiuser Time | None |
String | Convert | Multiuser Time | None |
Boolean | Equal | Multiuser Time | Float |
Boolean | Equal | Multiuser Time | Multiuser Time |
Boolean | Inferior | Multiuser Time | Float |
Boolean | Inferior | Multiuser Time | Multiuser Time |
Boolean | Inferior or Equal | Multiuser Time | Float |
Boolean | Inferior or Equal | Multiuser Time | Multiuser Time |
Multiuser Time | Multiplication | Multiuser Time | Float |
Boolean | Not Equal | Multiuser Time | Float |
Boolean | Not Equal | Multiuser Time | Multiuser Time |
Multiuser Time | Subtraction | Multiuser Time | Float |
Multiuser Time | Subtraction | Multiuser Time | Multiuser Time |
Boolean | Superior | Multiuser Time | Float |
Boolean | Superior | Multiuser Time | Multiuser Time |
Boolean | Superior or Equal | Multiuser Time | Float |
Boolean | Superior or Equal | Multiuser Time | Multiuser Time |
Level | Get Current | None | None |
Scene | Get Current | None | None |
Integer | Get Height | None | None |
Vector 2D | Get Mouse Position | None | None |
Integer | Get Mouse X | None | None |
Integer | Get Mouse Y | None | None |
Vector 2D | Get Screen Origin | None | None |
Rectangle | Get View Rect | None | None |
Integer | Get Width | None | None |
Boolean | Random | None | None |
Color | Random | None | None |
Vector | Random | None | None | between [0,0,0] and [1,1,1]
Vector 2D | Random | None | None |
Encrypted String | Convert | Percentage | None |
Physics Constraint | Convert | Percentage | None |
Physics Motor | Convert | Percentage | None |
Physics Spring | Convert | Percentage | None |
Physics Surface | Convert | Percentage | None |
Shader | Convert | Percentage | None |
Shader Pass | Convert | Percentage | None |
Shader Technique | Convert | Percentage | None |
VSL Script | Convert | Percentage | None |
Collection | Get Portals | Place | None |
Collection | Get Portals | Place | Place |
Euler Angles | Convert | Quaternion | None |
Matrix | Convert | Quaternion | None |
Quaternion | Division | Quaternion | Quaternion |
Boolean | Equal | Quaternion | Quaternion |
Float | Get W | Quaternion | None |
Float | Get X | Quaternion | None |
Float | Get Y | Quaternion | None |
Float | Get Z | Quaternion | None |
Quaternion | Multiplication | Quaternion | Quaternion |
Boolean | Not Equal | Quaternion | Quaternion |
Quaternion | Set W | Quaternion | Float |
Quaternion | Set X | Quaternion | Float |
Quaternion | Set Y | Quaternion | Float |
Quaternion | Set Z | Quaternion | Float |
String | Convert | Rectangle | None |
Boolean | Equal | Rectangle | Rectangle |
Vector 2D | Get Bottom-Right Corner | Rectangle | None |
Vector 2D | Get Geometric Center | Rectangle | None |
Vector 2D | Get Position | Rectangle | None |
Vector 2D | Get Size | Rectangle | None |
Boolean | Not Equal | Rectangle | Rectangle |
Rectangle | Set Bottom | Rectangle | Float |
Rectangle | Set Geometric Center | Rectangle | Vector 2D |
Rectangle | Set Height | Rectangle | Float |
Rectangle | Set Left | Rectangle | Float |
Rectangle | Set Right | Rectangle | Float |
Rectangle | Set Top | Rectangle | Float |
Rectangle | Set Width | Rectangle | Float |
Rectangle | Transform | Rectangle | Rectangle |
Rectangle | Transform | Rectangle | Vector 2D |
Rectangle | Get Rect | RenderTarget View | None |
Vector 2D | Get Texel Size | RenderTarget View | None |
Rectangle | Get Texture Rect | RenderTarget View | None |
Boolean | Is Active | Script | None |
Integer | Get Current | Sprite | None |
Integer | Get Slot Count | Sprite | None |
String | Get Text | Sprite Text | None |
String | Addition | String | String | hello+" world" = "hello world"
Boolean | Contain String | String | String |
Basic Object | Convert | String | None | useful to cast a Group element (retrieved by Group Iterator BB for example) into a specific type
Box | Convert | String | None |
Color | Convert | String | None |
Euler Angles | Convert | String | None |
Float | Convert | String | None |
Integer | Convert | String | None |
Matrix | Convert | String | None |
Message | Convert | String | None |
Multiuser Time | Convert | String | None |
Quaternion | Convert | String | None |
Rectangle | Convert | String | None |
Vector | Convert | String | None |
Vector 2D | Convert | String | None |
Boolean | Equal | String | String |
Layer Type | Get Layer By Name | String | None |
Integer | Get Length | String | None | length of "hello" = 5
Basic Object | Get Object By Name | String | None |
Integer | Get PM Rendered Vertices Coun | t Mesh | None |
3D Entity | Get Target | Target Camera | None |
3D Entity | Get Target | Target Light | None |
Integer | Get Current | Texture | None |
Integer | Get Height | Texture | None |
Integer | Get Slot Count | Texture | None |
Integer | Get Width | Texture | None |
RenderTarget View | Set RTView | Texture | Rectangle |
Encrypted String | Convert | Time | None |
Physics Constraint | Convert | Time | None |
Physics Motor | Convert | Time | None |
Physics Spring | Convert | Time | None |
Physics Surface | Convert | Time | None |
Shader | Convert | Time | None |
Shader Pass | Convert | Time | None |
Shader Technique | Convert | Time | None |
VSL Script | Convert | Time | None |
Vector | Addition | Vector | Vector |
Matrix | Convert | Vector | Vector |
String | Convert | Vector | None |
Vector | Convert | Vector | Vector 2D |
Vector 2D | Convert | Vector | None |
Vector 4D | Convert | Vector | Float |
Vector | Cross Product | Vector | Vector | Cross Product is given by the formula c = ab
Vector | Division | Vector | Float |
Vector | Division | Vector | Vector |
Float | Dot Product | Vector | Vector |
Boolean | Equal | Vector | Vector |
Matrix | From Rotation | Vector | Angle |
Quaternion | From Rotation | Vector | Angle |
Float | Get Angle | Vector | Vector |
Float | Get Distance | Vector | Vector |
Float | Get Magnitude | Vector | None | gets the length of a vector
Float | Get X | Vector | None |
Float | Get Y | Vector | None |
Float | Get Z | Vector | None |
Vector | Inverse | Vector | None |
Vector | Inverse Transform | Vector | 3D Entity | transforms a 3D Entity's position expressed in the World's co-ordinate system into a position expressed in its referential
Vector | Inverse Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector expressed in the World's co-ordinate system into a vector expressed in its referential
Boolean | Is In | Vector | 3D Entity |
Vector | Max | Vector | Vector |
Vector | Min | Vector | Vector |
Vector | Multiplication | Vector | Float |
Vector | Multiplication | Vector | Matrix |
Vector | Multiplication | Vector | Multiuser Time |
Vector | Multiplication | Vector | Vector |
Vector | Normalize | Vector | None |
Boolean | Not Equal | Vector | Vector |
Vector | Opposite | Vector | None |
Vector | Per Second | Vector | None |
Vector | Reflect | Vector | Vector | find the reflected vector from the specified vector axis referential
Matrix | Set Position | Vector | Matrix |
Matrix | Set X | Vector | Matrix |
Vector | Set X | Vector | Float |
Matrix | Set Y | Vector | Matrix |
Vector | Set Y | Vector | Float |
Matrix | Set Z | Vector | Matrix |
Vector | Set Z | Vector | Float |
Vector | Subtraction | Vector | Vector |
Vector | Symmetry | Vector | Vector |
Vector | Transform | Vector | 3D Entity | transforms a 3D Entity's position in its referential to the World's co-ordinate system
Vector 2D | Transform | Vector | 3D Entity | projects a 3D vector expressed in the 3D Entity's referential into the screen plane
Vector | Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector in its referential to the World's co-ordinate system
Vector 2D | Addition | Vector 2D | Vector 2D |
String | Convert | Vector 2D | None |
Vector 2D | Division | Vector 2D | Float |
Vector 2D | Division | Vector 2D | Vector 2D |
Float | Dot Product | Vector 2D | Vector 2D |
Boolean | Equal | Vector 2D | Vector 2D |
Float | Get Angle | Vector 2D | Vector 2D |
Float | Get Distance | Vector 2D | Vector 2D |
Float | Get Magnitude | Vector 2D | None |
Float | Get X | Vector 2D | None |
Float | Get Y | Vector 2D | None |
Vector 2D | Inverse | Vector 2D | None |
Vector 2D | Max | Vector 2D | Vector 2D |
Vector 2D | Min | Vector 2D | Vector 2D |
Vector 2D | Multiplication | Vector 2D | Float |
Vector 2D | Multiplication | Vector 2D | Vector 2D |
Boolean | Not Equal | Vector 2D | Vector 2D |
Vector 2D | Opposite | Vector 2D | None |
Render Object | Pick Object | Vector 2D | None |
Vector 2D | Set X | Vector 2D | Float |
Vector 2D | Set Y | Vector 2D | Float |
Vector 2D | Subtraction | Vector 2D | Vector 2D |
Vector 2D | Symmetry | Vector 2D | Vector 2D |
Vector | Transform | Vector 2D | Float |
Vector | Get Cone | Wave Sound | None |
Float | Get Distance | Wave Sound | None |
Float | Get Gain | Wave Sound | None |
Float | Get Length | Wave Sound | None |
Vector 2D | Get Min Max | Wave Sound | None |
Float | Get Pan | Wave Sound | None |
Float | Get Pitch | Wave Sound | None |
Time | Get Played Time | Wave Sound | None |
Vector | Get Relative Direction | Wave Sound | None |
Vector | Get Relative Position | Wave Sound | None |
Integer | Get Sampling Rate | Wave Sound | None |
String | Get Sound file Name | Wave Sound | None |
Vector | Get Velocity | Wave Sound | None |
Boolean | Is Looping | Wave Sound | None |
Boolean | Is Paused | Wave Sound | None |
Boolean | Is Playing | Wave Sound | None |
Boolean | Is Streaming | Wave Sound | None |


Parameter Operations by Second Input Type

To see Parameter Operations listed differently, click column headers.

Result | Operation | Input 1 | Input 2 |
Vector 2D | Get Curve Position | Float | 2D Curve |
Float | Get Distance | 2D Entity | 2D Entity |
Float | Get Distance | 3D Entity | 3D Entity |
Vector | Get Distance | 3D Entity | 3D Entity | returns vector distance (useful to get a direction)
Euler Angles | Get Euler Angles | 3D Entity | 3D Entity |
Vector | Get Position | 3D Entity | 3D Entity | a 3D Entity's referential
Boolean | Is Child Of | 3D Entity | 3D Entity |
Boolean | Is Collision | 3D Entity | 3D Entity |
Boolean | Is Collision | Box | 3D Entity |
Vector | Inverse Transform | Vector | 3D Entity | transforms a 3D Entity's position expressed in the World's co-ordinate system into a position expressed in its referential
Vector | Inverse Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector expressed in the World's co-ordinate system into a vector expressed in its referential
Boolean | Is In | Vector | 3D Entity |
Vector | Transform | Vector | 3D Entity | transforms a 3D Entity's position in its referential to the World's co-ordinate system
Vector 2D | Transform | Vector | 3D Entity | projects a 3D vector expressed in the 3D Entity's referential into the screen plane
Vector | Transform Vector | Vector | 3D Entity | transforms a 3D Entity's vector in its referential to the World's co-ordinate system
Matrix | From Rotation | Vector | Angle |
Quaternion | From Rotation | Vector | Angle |
Boolean | Is Content Equal | Array | Array |
Boolean | Equal | Basic Object | Basic Object |
Boolean | Is Derived From | Basic Object | Basic Object | finds the parent type of the specified object (e.g. a 3D Object is derived from a 3D Entity)
Boolean | Not Equal | Basic Object | Basic Object |
Boolean | Addition | Collection | Basic Object |
Boolean | Is In | Collection | Basic Object |
Boolean | Subtraction | Collection | Basic Object |
Boolean | And | Boolean | Boolean |
Boolean | Equal | Boolean | Boolean |
Boolean | Not Equal | Boolean | Boolean |
Boolean | Or | Boolean | Boolean | Boolean inclusive logic operation (e.g. 0 Or 1=1; 1 Or 0=1; 0 Or 0=0; 1 Or 1=1)
Boolean | Xor | Boolean | Boolean | Boolean exclusive logic operation (e.g. 0 XOr 1=1; 1 XOr 0=1; 0 XOr 0=0; 1 XOr 1=0)
Box | Addition | Box | Box |
Boolean | Is Collision | Box | Box |
Box | Subtraction | Box | Box |
Boolean | Is Body Part Of | Body Part | Character |
Collection | And | Collection | Collection |
Boolean | Equal | Collection | Collection |
Collection | Or | Collection | Collection |
Collection | Subtraction | Collection | Collection |
Color | Addition | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Boolean | Equal | Color | Color |
Boolean | Not Equal | Color | Color |
Color | Subtraction | Color | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Color | Multiplication | Float | Color | standard color (RGBA) range [0,0,0] to [255,255,255]
Vector | Get Curve Position | Float | Curve |
Vector | Get Curve Tangent | Float | Curve |
Float | Get Length | Curve | Curve Point |
Boolean | Equal | Euler Angles | Euler Angles |
Boolean | Not Equal | Euler Angles | Euler Angles |
Float | Get Y | 2D Curve | Float |
Color | Set Alpha | Color | Float |
Color | Set Blue | Color | Float |
Color | Set Green | Color | Float |
Color | Set Red | Color | Float |
Euler Angles | Set X | Euler Angles | Float |
Euler Angles | Set Y | Euler Angles | Float |
Euler Angles | Set Z | Euler Angles | Float |
Float | Addition | Float | Float |
Float | Arc Tangent 2 | Float | Float | gets the sine and cosine corresponding to the specified value
Vector 2D | Convert | Float | Float |
Float | Division | Float | Float |
Boolean | Equal | Float | Float |
Boolean | Inferior | Float | Float |
Boolean | Inferior or Equal | Float | Float |
Float | Max | Float | Float |
Float | Min | Float | Float |
Float | Multiplication | Float | Float |
Boolean | Not Equal | Float | Float |
Color | Rainbow Color | Float | Float | get the associated color (RGBA) from two floats (Hue and Luminosity) between 0 and 1
Float | Random | Float | Float |
Vector | Spheric To Cartesian | Float | Float | do a conversion from spheric referential coordinates to cartesian referential coordinates (latitude and longitude (can be specified with angles))
Float | Subtraction | Float | Float |
Boolean | Superior | Float | Float |
Boolean | Superior or Equal | Float | Float |
Integer | Addition | Integer | Float |
Float | Division | Integer | Float |
Integer | Division | Integer | Float |
Boolean | Equal | Integer | Float |
Boolean | Inferior | Integer | Float |
Boolean | Inferior or Equal | Integer | Float |
Integer | Max | Integer | Float |
Integer | Min | Integer | Float |
Integer | Multiplication | Integer | Float |
Boolean | Not Equal | Integer | Float |
Float | Subtraction | Integer | Float |
Integer | Subtraction | Integer | Float |
Boolean | Superior | Integer | Float |
Boolean | Superior or Equal | Integer | Float |
Matrix | Multiplication | Matrix | Float |
Multiuser Time | Addition | Multiuser Time | Float |
Boolean | Equal | Multiuser Time | Float |
Boolean | Inferior | Multiuser Time | Float |
Boolean | Inferior or Equal | Multiuser Time | Float |
Multiuser Time | Multiplication | Multiuser Time | Float |
Boolean | Not Equal | Multiuser Time | Float |
Multiuser Time | Subtraction | Multiuser Time | Float |
Boolean | Superior | Multiuser Time | Float |
Boolean | Superior or Equal | Multiuser Time | Float |
Quaternion | Set W | Quaternion | Float |
Quaternion | Set X | Quaternion | Float |
Quaternion | Set Y | Quaternion | Float |
Quaternion | Set Z | Quaternion | Float |
Rectangle | Set Bottom | Rectangle | Float |
Rectangle | Set Height | Rectangle | Float |
Rectangle | Set Left | Rectangle | Float |
Rectangle | Set Right | Rectangle | Float |
Rectangle | Set Top | Rectangle | Float |
Rectangle | Set Width | Rectangle | Float |
Vector 4D | Convert | Vector | Float |
Vector | Division | Vector | Float |
Vector | Multiplication | Vector | Float |
Vector | Set X | Vector | Float |
Vector | Set Y | Vector | Float |
Vector | Set Z | Vector | Float |
Vector 2D | Division | Vector 2D | Float |
Vector 2D | Multiplication | Vector 2D | Float |
Vector 2D | Set X | Vector 2D | Float |
Vector 2D | Set Y | Vector 2D | Float |
Vector | Transform | Vector 2D | Float |
Boolean | Is Content Equal | Group | Group |
Object Animation | Get Animation | 3D Entity | Integer |
Script | Get Script | Behavioral Object | Integer |
Basic Object | Get Element | Collection | Integer |
Curve Point | Get Curve Point | Curve | Integer |
Float | Addition | Float | Integer |
Float | Division | Float | Integer |
Integer | Division | Float | Integer |
Boolean | Inferior | Float | Integer |
Boolean | Inferior or Equal | Float | Integer |
Float | Max | Float | Integer |
Float | Min | Float | Integer |
Float | Multiplication | Float | Integer |
Float | Subtraction | Float | Integer |
Integer | Subtraction | Float | Integer |
Boolean | Superior | Float | Integer |
Boolean | Superior or Equal | Float | Integer |
Basic Object | Get Element | Group | Integer |
Integer | Addition | Integer | Integer |
Integer | And | Integer | Integer | converts to Boolean before adding (e.g. 7 And 3 = 3, but 8 And 3 = 0)
Vector 2D | Convert | Integer | Integer |
Integer | Division | Integer | Integer |
Boolean | Equal | Integer | Integer |
Boolean | Inferior | Integer | Integer |
Boolean | Inferior or Equal | Integer | Integer |
Boolean | Is Note Active | Integer | Integer | checks if the specified note is activated or not (specific to the Midi Controller BB)
Integer | Max | Integer | Integer |
Integer | Min | Integer | Integer |
Integer | Modulo | Integer | Integer |
Integer | Multiplication | Integer | Integer |
Boolean | Not Equal | Integer | Integer |
Integer | Or | Integer | Integer |
Render Object | Pick Object | Integer | Integer |
Integer | Random | Integer | Integer |
Integer | Subtraction | Integer | Integer |
Boolean | Superior | Integer | Integer |
Boolean | Superior or Equal | Integer | Integer |
Integer | Xor | Integer | Integer |
Material | Get Face Material | Mesh | Integer |
Vector | Get Face Normal | Mesh | Integer |
Vector | Get Face Vertex Indices | Mesh | Integer |
Material | Get Material | Mesh | Integer |
Color | Get Vertex Color | Mesh | Integer |
Vector | Get Vertex Normal | Mesh | Integer |
Vector | Get Vertex Position | Mesh | Integer |
Color | Get Vertex Specular Color | Mesh | Integer |
Vector 2D | Get Vertex UVs | Mesh | Integer | get the UVs of the specified vertex
Float | Get Vertex Weight | Mesh | Integer | gets the weight of the specified vertex
Integer | Get Channel By Material | Mesh | Material |
Matrix | Addition | Matrix | Matrix |
Matrix | Division | Matrix | Matrix |
Boolean | Equal | Matrix | Matrix |
Matrix | Multiplication | Matrix | Matrix |
Boolean | Not Equal | Matrix | Matrix |
Matrix | Subtraction | Matrix | Matrix |
Vector | Multiplication | Vector | Matrix |
Matrix | Set Position | Vector | Matrix |
Matrix | Set X | Vector | Matrix |
Matrix | Set Y | Vector | Matrix |
Matrix | Set Z | Vector | Matrix |
Multiuser Time | Subtraction | Float | Multiuser Time |
Multiuser Time | Addition | Multiuser Time | Multiuser Time |
Boolean | Equal | Multiuser Time | Multiuser Time |
Boolean | Inferior | Multiuser Time | Multiuser Time |
Boolean | Inferior or Equal | Multiuser Time | Multiuser Time |
Boolean | Not Equal | Multiuser Time | Multiuser Time |
Multiuser Time | Subtraction | Multiuser Time | Multiuser Time |
Boolean | Superior | Multiuser Time | Multiuser Time |
Boolean | Superior or Equal | Multiuser Time | Multiuser Time |
Vector | Multiplication | Vector | Multiuser Time |
Float | Get Length | 2D Curve | None |
Rectangle | Get Bounding Box | 2D Entity | None |
Integer | Get Height | 2D Entity | None |
Material | Get Material | 2D Entity | None |
2D Entity | Get Parent | 2D Entity | None |
Vector 2D | Get Position | 2D Entity | None |
Vector 2D | Get Size | 2D Entity | None |
Integer | Get Width | 2D Entity | None |
Boolean | Is Visible | 2D Entity | None |
Integer | Get Animation Count | 3D Entity | None |
Box | Get Bounding Box | 3D Entity | None | World Bounding Box
Rectangle | Get Bounding Box | 3D Entity | None |
Character | Get Character | 3D Entity | None | retrieves the Character who owns the specified 3D Entity (BodyPart)
Collection | Get Children | 3D Entity | None | retrieves a 3D Entity's children; 3D Entity's name must contain the specified string
Mesh | Get Current | 3D Entity | None |
Vector | Get Dir | 3D Entity | None | Z Vector
Vector | Get Geometric Center | 3D Entity | None |
Box | Get Hierarchical Bounding Box | 3D Entity | None |
Matrix | Get Local Matrix | 3D Entity | None |
Collection | Get Mesh List | 3D Entity | None |
3D Entity | Get Parent | 3D Entity | None |
Vector | Get Position | 3D Entity | None | in the World co-ordinate system
Float | Get Radius | 3D Entity | None |
Place | Get Referential Place | 3D Entity | None | gets the Place containing the 3D Entity
Vector | Get Right | 3D Entity | None | X Vector
Vector | Get Scale | 3D Entity | None |
Vector | Get Up | 3D Entity | None | Y Vector
Matrix | Get World Matrix | 3D Entity | None |
Float | Get X | 3D Entity | None |
Float | Get Y | 3D Entity | None |
Float | Get Z | 3D Entity | None |
Boolean | Is Visible | 3D Entity | None |
Material | Get Material | 3D Sprite | None |
String | Convert | Angle | None |
Float | Get Length | Animation | None | number of animation frames expressed as a Float
Integer | Get Column Count | Array | None |
Integer | Get Count | Array | None |
Integer | Get Row Count | Array | None |
String | Convert | Attribute | None |
Basic Object | Dynamic Cast | Basic Object | None | filters elements: ensures a BB that requires a specific CKClass only receives inputs of this type (e.g. in the case of iterating a Group, the elements can be of different classes, using this op only elements of the right CKClass are passed to the BB)
String | Get Name | Basic Object | None |
Registered Class | Get Type | Basic Object | None | returns the CK ClassID of the element
Integer | Get Script Count | Behavioral Object | None |
Boolean | Is Active | Behavioral Object | None |
Float | Convert | Boolean | None |
Integer | Convert | Boolean | None |
String | Convert | Boolean | None |
Vector 2D | Get Mouse Position | Boolean | None |
Boolean | Not | Boolean | None |
Boolean | Opposite | Boolean | None |
Vector | Get Geometric Center | Box | None |
Vector | Get Scale | Box | None |
Vector | Max | Box | None |
Vector | Min | Box | None |
Vector 2D | Get Aspect Ratio | Camera | None |
Float | Get Far Clip | Camera | None |
Float | Get Field Of View | Camera | None | note: you can specify Angle instead of Float as the result
Float | Get Near Clip | Camera | None |
Float | Get Orthographic Zoom | Camera | None |
Collection | Get Animation | Character | None | retrieves a Character's animations; Character's name must contain the specified string
Collection | Get BodyParts | Character | None | retrieves a Character's BodyParts; Character's name must contain the specified string
3D Entity | Get Root | Character | None |
Integer | Get Count | Collection | None |
String | Convert | Color | None |
Float | Get Alpha | Color | None |
Float | Get Blue | Color | None |
Float | Get Green | Color | None |
Float | Get Red | Color | None |
Color | Inverse | Color | None |
Integer | Get Count | Curve | None |
Float | Get Length | Curve | None |
Vector | Get In Tangent | Curve Point | None |
Vector | Get Out Tangent | Curve Point | None |
Matrix | Convert | Euler Angles | None |
Quaternion | Convert | Euler Angles | None |
Float | Get X | Euler Angles | None |
Float | Get Y | Euler Angles | None |
Float | Get Z | Euler Angles | None |
Float | Absolute Value | Float | None |
Float | Arc Cosine | Float | None |
Float | Arc Sine | Float | None |
Boolean | Convert | Float | None |
Integer | Convert | Float | None |
String | Convert | Float | None |
Float | Cosine | Float | None |
Float | Degree To Radian | Float | None |
Float | Inverse | Float | None |
Integer | Inverse | Float | None | 1 / x
Float | Opposite | Float | None |
Float | Per Second | Float | None |
Float | Radian To Degree | Float | None |
Float | Sine | Float | None |
Float | Square Root | Float | None |
Float | Tangent | Float | None |
Integer | Get Count | Group | None |
Registered Class | Get Group Type | Group | None | gets the CKClass of the elements of a specified Group (returns the common CKClass in the case of different element CKClasses)
Integer | Absolute Value | Integer | None |
Boolean | Convert | Integer | None |
Float | Convert | Integer | None |
String | Convert | Integer | None |
Multiuser Session State | Get Session State | Integer | None |
Float | Inverse | Integer | None |
Integer | Opposite | Integer | None |
Color | Get Color | Light | None |
Float | Get Range | Light | None |
Color | Get Ambient Color | Material | None |
Color | Get Diffuse Color | Material | None |
Color | Get Emissive Color | Material | None |
Color | Get Specular Color | Material | None |
Float | Get Specular Color Power | Material | None |
Texture | Get Texture | Material | None |
Euler Angles | Convert | Matrix | None |
Quaternion | Convert | Matrix | None |
Vector | Get Position | Matrix | None |
Vector | Get Scale | Matrix | None |
Vector | Get X | Matrix | None |
Vector | Get Y | Matrix | None |
Vector | Get Z | Matrix | None |
Matrix | Inverse | Matrix | None |
Box | Get Bounding Box | Mesh | None | Local Bounding Box
Integer | Get Channel Count | Mesh | None |
Integer | Get Face Count | Mesh | None |
Integer | Get Material Count | Mesh | None |
Collection | Get Material List | Mesh | None |
Integer | Get Vertex Count | Mesh | None |
String | Convert | Message | None |
Float | Convert | Multiuser Time | None |
String | Convert | Multiuser Time | None |
Level | Get Current | None | None |
Scene | Get Current | None | None |
Integer | Get Height | None | None |
Vector 2D | Get Mouse Position | None | None |
Integer | Get Mouse X | None | None |
Integer | Get Mouse Y | None | None |
Vector 2D | Get Screen Origin | None | None |
Rectangle | Get View Rect | None | None |
Integer | Get Width | None | None |
Boolean | Random | None | None |
Color | Random | None | None |
Vector | Random | None | None | between [0,0,0] and [1,1,1]
Vector 2D | Random | None | None |
Encrypted String | Convert | Percentage | None |
Physics Constraint | Convert | Percentage | None |
Physics Motor | Convert | Percentage | None |
Physics Spring | Convert | Percentage | None |
Physics Surface | Convert | Percentage | None |
Shader | Convert | Percentage | None |
Shader Pass | Convert | Percentage | None |
Shader Technique | Convert | Percentage | None |
VSL Script | Convert | Percentage | None |
Collection | Get Portals | Place | None |
Euler Angles | Convert | Quaternion | None |
Matrix | Convert | Quaternion | None |
Float | Get W | Quaternion | None |
Float | Get X | Quaternion | None |
Float | Get Y | Quaternion | None |
Float | Get Z | Quaternion | None |
String | Convert | Rectangle | None |
Vector 2D | Get Bottom-Right Corner | Rectangle | None |
Vector 2D | Get Geometric Center | Rectangle | None |
Vector 2D | Get Position | Rectangle | None |
Vector 2D | Get Size | Rectangle | None |
Rectangle | Get Rect | RenderTarget View | None |
Vector 2D | Get Texel Size | RenderTarget View | None |
Rectangle | Get Texture Rect | RenderTarget View | None |
Boolean | Is Active | Script | None |
Integer | Get Current | Sprite | None |
Integer | Get Slot Count | Sprite | None |
String | Get Text | Sprite Text | None |
Basic Object | Convert | String | None | useful to cast a Group element (retrieved by Group Iterator BB for example) into a specific type
Box | Convert | String | None |
Color | Convert | String | None |
Euler Angles | Convert | String | None |
Float | Convert | String | None |
Integer | Convert | String | None |
Matrix | Convert | String | None |
Message | Convert | String | None |
Multiuser Time | Convert | String | None |
Quaternion | Convert | String | None |
Rectangle | Convert | String | None |
Vector | Convert | String | None |
Vector 2D | Convert | String | None |
Layer Type | Get Layer By Name | String | None |
Integer | Get Length | String | None | length of "hello" = 5
Basic Object | Get Object By Name | String | None |
Integer | Get PM Rendered Vertices Coun | t Mesh | None |
3D Entity | Get Target | Target Camera | None |
3D Entity | Get Target | Target Light | None |
Integer | Get Current | Texture | None |
Integer | Get Height | Texture | None |
Integer | Get Slot Count | Texture | None |
Integer | Get Width | Texture | None |
Encrypted String | Convert | Time | None |
Physics Constraint | Convert | Time | None |
Physics Motor | Convert | Time | None |
Physics Spring | Convert | Time | None |
Physics Surface | Convert | Time | None |
Shader | Convert | Time | None |
Shader Pass | Convert | Time | None |
Shader Technique | Convert | Time | None |
VSL Script | Convert | Time | None |
String | Convert | Vector | None |
Vector 2D | Convert | Vector | None |
Float | Get Magnitude | Vector | None | gets the length of a vector
Float | Get X | Vector | None |
Float | Get Y | Vector | None |
Float | Get Z | Vector | None |
Vector | Inverse | Vector | None |
Vector | Normalize | Vector | None |
Vector | Opposite | Vector | None |
Vector | Per Second | Vector | None |
String | Convert | Vector 2D | None |
Float | Get Magnitude | Vector 2D | None |
Float | Get X | Vector 2D | None |
Float | Get Y | Vector 2D | None |
Vector 2D | Inverse | Vector 2D | None |
Vector 2D | Opposite | Vector 2D | None |
Render Object | Pick Object | Vector 2D | None |
Vector | Get Cone | Wave Sound | None |
Float | Get Distance | Wave Sound | None |
Float | Get Gain | Wave Sound | None |
Float | Get Length | Wave Sound | None |
Vector 2D | Get Min Max | Wave Sound | None |
Float | Get Pan | Wave Sound | None |
Float | Get Pitch | Wave Sound | None |
Time | Get Played Time | Wave Sound | None |
Vector | Get Relative Direction | Wave Sound | None |
Vector | Get Relative Position | Wave Sound | None |
Integer | Get Sampling Rate | Wave Sound | None |
String | Get Sound file Name | Wave Sound | None |
Vector | Get Velocity | Wave Sound | None |
Boolean | Is Looping | Wave Sound | None |
Boolean | Is Paused | Wave Sound | None |
Boolean | Is Playing | Wave Sound | None |
Boolean | Is Streaming | Wave Sound | None |
Collection | Get Portals | Place | Place |
Quaternion | Division | Quaternion | Quaternion |
Boolean | Equal | Quaternion | Quaternion |
Quaternion | Multiplication | Quaternion | Quaternion |
Boolean | Not Equal | Quaternion | Quaternion |
Boolean | Equal | Rectangle | Rectangle |
Boolean | Not Equal | Rectangle | Rectangle |
Rectangle | Transform | Rectangle | Rectangle |
RenderTarget View | Set RTView | Texture | Rectangle |
Object Animation | Get Animation | 3D Entity | String | retrieves an object's animation; object's name must contain the specified string
Script | Get Script | Behavioral Object | String | retrieves an element's script; the element's name must contain the specified string
Animation | Get Animation | Character | String | retrieves a character's animation; Character's name contains the specified string
Body Part | Get BodyPart | Character | String |
String | Addition | String | String | hello+" world" = "hello world"
Boolean | Contain String | String | String |
Boolean | Equal | String | String |
Boolean | Is Collision | Box | Vector |
Vector | Addition | Vector | Vector |
Matrix | Convert | Vector | Vector |
Vector | Cross Product | Vector | Vector | Cross Product is given by the formula c = ab
Vector | Division | Vector | Vector |
Float | Dot Product | Vector | Vector |
Boolean | Equal | Vector | Vector |
Float | Get Angle | Vector | Vector |
Float | Get Distance | Vector | Vector |
Vector | Max | Vector | Vector |
Vector | Min | Vector | Vector |
Vector | Multiplication | Vector | Vector |
Boolean | Not Equal | Vector | Vector |
Vector | Reflect | Vector | Vector | find the reflected vector from the specified vector axis referential
Vector | Subtraction | Vector | Vector |
Vector | Symmetry | Vector | Vector |
Rectangle | Set Geometric Center | Rectangle | Vector 2D |
Rectangle | Transform | Rectangle | Vector 2D |
Vector | Convert | Vector | Vector 2D |
Vector 2D | Addition | Vector 2D | Vector 2D |
Vector 2D | Division | Vector 2D | Vector 2D |
Float | Dot Product | Vector 2D | Vector 2D |
Boolean | Equal | Vector 2D | Vector 2D |
Float | Get Angle | Vector 2D | Vector 2D |
Float | Get Distance | Vector 2D | Vector 2D |
Vector 2D | Max | Vector 2D | Vector 2D |
Vector 2D | Min | Vector 2D | Vector 2D |
Vector 2D | Multiplication | Vector 2D | Vector 2D |
Boolean | Not Equal | Vector 2D | Vector 2D |
Vector 2D | Subtraction | Vector 2D | Vector 2D |
Vector 2D | Symmetry | Vector 2D | Vector 2D |


Enumerations - Parameter Types

text


Address Mode pType

Address Mode controls how Textures are applied to a Material, specifically how Texture coordinates outside the range 0-1 are interpreted.

Wrap
Tiles the Texture according to the UV coordinates, 0 to 1 then 0 to 1

Mirror
Tiles the Texture according to the UV coordinates, 0 to 1 then 1 to 0

Clamp
If the Texture is too small to cover the surface, then the edge pixels are duplicated until the Texture is large enough

Border
If the Texture is too small to cover the surface, then the border color is used to fill in the missing pixels.


Fill Mode pType

Fill Mode controls how the faces of a Material are rendered.

Point
Only vertices are rendered.

Wireframe
Vertices and the edges between vertices are rendered.

Solid
Fills the areas created by the edges. Note that Solid is not shown below as Solid depends on the Shade Mode pType.

OnlyZ
to complete.


Filter Mode pType

Filter Mode defines the interpolation method to use when reducing (Minimization) or enlarging a (Magnification) Texture pixel (Texel) onscreen. Note that the Mip modes work only if you have generated a MipMap for the Texture (Mip Levels must be set to Automatic in Texture Setup).

Nearest
Copy the nearest texel.

Linear
Bilinear interpolation filtering. A weighted average of a 2×2 area of texels surrounding the desired pixel is used.

MipNearest
Nearest-point mipmap filtering. The rasterizer uses the color from the texel of the nearest mipmap texture.

MipLinear
Trilinear mipmap interpolation. The rasterizer linearly interpolates pixel color, using the texels of the two nearest mipmap textures.

LinearMipNearest
Same as Mip Nearest, with Bilinear interpolation filtering.

LinearMipLinear
Same as Mip Linear, with Bilinear interpolation filtering.

Anisotropic
Anisotropic texture filtering. corrects distortion visible in the image of a 3D object whose surface is oriented at an angle with respect to the viewing plane.


Shade Mode pType

Shade Mode controls how solid faces of a Material are rendered. Note that for Shade Mode to have any influence, the Fill Mode pType for a Material must be set to Solid.

Flat
All pixels are lit with the same light color.

Gouraud
The light color is linearly interpolated between vertices.


Texture Blend Mode pType

Texture Blending is the action to blend the Texture color information with the color of the Material. Calling S = (Cs, As) = (Rs, Gs, Bs, As) the texture's color to apply, D = (Cd, Ad) = (Rd, Gd, Bd, Ad) the material's color and R = (C, A) = (R, G, B, A) the resulting texel value, the blending is computed following the equations given in the table below. Formulas are given for the programmers who want to know the exact meaning of each setting. But a more meaningfull description is also available for non programmers.

Blending Mode | Operation | Description
Decal | R = S | In this mode, the RGB and alpha values of the texture replace the colors that would have been used with no texturing.
Modulate | C = Cs*Ds if (As) A = As else A = Ad | In this mode, the RGB values of the texture are multiplied with the RGB values that would have been used with no texturing. Any alpha values in the texture replace the alpha values in the colors that would have been used with no texturing; if the texture does not contain an alpha component, alpha values at the vertices in the source are interpolated between vertices.
Decal Alpha | C = Cd (1 - As) + As*Cs A = Ad | In this mode, the RGB and alpha values of the texture are blended with the colors that would have been used with no texturing, according to the given formulas.
Modulate Alpha | C = Cs*Cd A = As*Ad | In this mode, the RGB values of the texture are multiplied with the RGB values that would have been used with no texturing, and the alpha values of the texture are multiplied with the alpha values that would have been used with no texturing.
Decal Mask | C = lsb(As) ? Cs : Cd A = Ad | When the least-significant bit of the texture's alpha component is zero, the effect is as if texturing were disabled.
Modulate Mask | C = lsb(As) ? Cs*Cd : Cd A = Ad | When the least-significant bit of the texture's alpha component is zero, the effect is as if texturing were disabled.
Copy | Same as Decal | Same as Decal
Add | C = Cs + Cd A = Ad | Add the Gouraud interpolants to the texture lookup with saturation semantics (that is, if the color value overflows it is set to the maximum possible value).

Warning: It is very important to note that all graphic cards do not necessarily support all the blending operators available. When it is not supported, you get a black result instead of the normal result. The more common value supported by most cards is the modulate value.


VSL (Virtools Scripting Language)

VSL in Virtools Dev

  • Introducing VSL
  • Understanding VSL
  • VSL Script Manager
  • Learning VSL through Examples
  • Core Language Features
  • Actions: VSL in Authoring Mode (NEW)

    • Appendixes

  • Global Variable bc and ac
  • Using GUID
  • SDK Binding Tables
  • FAQs

    • Comments


VSL Overview

Understanding VSL

Global VSL Scripts and Run VSL Scripts

A VSL script can be one of two types: Global VSL or Run VSL.

Global VSL scripts exist to define functions that are available to all other VSL scripts. Global VSL scripts cannot be run themselves, they can only be called by other VSL scripts (including Global VSL and Run VSL).

Run VSL scripts are attached to Run VSL BBs in the Schematic Editor - one Run VSL script corresponds to one Run VSL BB where the first pIn of a Run VSL BB contains the VSL code executed by that BB. Run VSL scripts can be run in either Author mode (by executing the code from within the VSL Script Manager) or at run-time when the BB is activated and processed just like any other BB.

Run VSL scripts are able to use bc (behavior context) global variable.

Global variables bc (behavior context) and ac (action context)

bc is a global variable that can only be used in Run VSL scripts.
ac is a global variable that can only be used in Actions scripts.

Both provide some very useful methods to:

  • create objects
  • write text in the console or 3D view
  • manage attributes
  • deal with the variable manager
  • profiles yours scripts
  • etc.

bc has specific runtime methods, for example:

  • to manage messages
  • to launch a scene
  • etc.

ac focuses on selections and mouse position.

Dependencies between Scripts

Note that any script (Global VSL or Run VSL) that calls a function from a Global VSL script is then dependent on that Global VSL script. If you modify a Global VSL script, not only must this script be recompiled before VSL can interpret it, but all scripts that call that Global VSL script must also be recompiled. When you make changes to a VSL script you can see if the changes require any other VSL scripts to be recompiled by looking at the Compiled column in the VSL Scripts view of the VSL Manager.

Variable Types

In addition to the base types listed below, you can use the Classes listed in VSL <- SDK Binding Tables - Classes and Methods. You can also use the enumerated parameter types listed in VSL <- SDK Binding Tables - Enumerations.

Base Types

bool: boolean value. A bool is either true (TRUE) or false (FALSE).
char: character value. A char is a signed byte value in the range of -128 to 127 inclusive.
int: integer value. An int is a signed 4 byte value in the range of -2,147,483,648 to 2,147,483,647 inclusive.
float: floating point value. A float is a signed 4 byte value.
str: string. An str is an constant array of characters terminated by the null character 0 or '\0'. Note: If you want to manipulate strings, you should use the String class bound from the Virtools SDK to VSL.

As mentioned above, all other possible variable types are listed in the VSL <- SDK Binding Tables. If you do not see the type you are looking for in the VSL <- SDK Binding Tables, then variables of that type are not allowed.

To avoid defining NULL objects, you are strongly advised to use Debug Check (activated or deactivated in the Variables Manager). Running a script that uses a NULL object variable can result in the VSL Manager failing, perhaps causing Dev to crash. As always, when performing software development, you are strongly advised to save incremental versions of your project as often as you can.

Compiling

All VSL scripts must be compiled before they can be run. The VSL Manager will automatically try to compile uncompiled VSL Scripts in the following situations:

  • when loading a Virtools file (CMO, VMO, NMO or NMS)
  • when a Run VSL BB is activated

Note that the VSL Manager attempts to compile any required (linked) Global VSL scripts before attempting to compile Run VSL scripts. We strongly recommend that you compile your VSL Scripts before running them to check for errors and to help ensure that your VSL Scripts will perform as intended.

You can choose to compile all scripts or only certain scripts in the VSL Script Manager. When you compile a VSL script, you must decide whether you want to compile it as Debug or as Release.

Debug and Release

A VSL script compiled as debug can be debugged using the debugging tools described in VSL Script Manager. Examples of using these tools are given in the series Learning VSL through Examples.

VSL scripts compiled as Release cannot be debugged using the VSL Script Manager debugging tools. At runtime, Release VSL scripts execute several times faster than Debug VSL scripts since they are compiled using a JIT compiler that creates highly optimized assembler-like code.

Note:
1. It is possible to have certain scripts in Debug and others in Release at the same time - unless scripts share a Global VSL script (i.e. Global VSL scripts can be debug or release, but not both at the same time.)
2. Changing the compile mode on a VSL script (e.g. from Debug to Release) can result in linked Global scripts being recompiled as well.
3. When you compile a script (either Global VSL or Run VSL), the VSL Manager first attempts to compile any global scripts that are either uncompiled or are in a different compiled mode (e.g. release/debug). If compilation fails then error messages appear in the Errors section of the VSL Script Manager and in the Event Log.
4. After editing a global script, that script becomes "uncompiled". Any other scripts that use any part of this script are also made "uncompiled".
5. Highly recommended: Select the "Debug Check Variable" in the VSL section of the Variable Manager to ensure that all objects are tested and to ensure that they are not NULL (ie that they exist) before they are used.

Running VSL Scripts

You can run VSL scripts in Author mode or in Player mode.

Author Mode
In the VSL Script Manager, select a Run VSL script in the VSL Scripts column and click Run Script or press F5. Note that running a script in Author mode only executes the VSL code; the BB itself is not activated. This means that pIns are used and pOuts calculated, but bIns and bOuts are not considered.

Player Mode (Run-time)
The BB must be be activated by a link from another BB or from the Start.

Saving/Importing

You can save and load both Global VSL and Run VSL scripts via the save and load buttons in the VSL Script Manager interface. VSL scripts are saved as text files with the .VSC extension. Note that you can only load a VSL script into an existing VSL script. Before loading, ensure that the script is empty; otherwise, the script you are importing will replace whatever code you already have. Note also that all you are saving or importing is the source code from the code view - no information related to the connectors (bIns, bOuts, pIns, pOuts) is saved.

You can, of course, save Virtools files (CMO/VMO/NMO/NMS) that have VSL scripts. In this case, ensure that all dependent scripts are available when the saved file is loaded.

Debugging

A number of debugging tools exist to help you debug your scripts in the VSL Script Manager. To use the debugging tools, you must be in debug mode. Note: You cannot debug SDK elements from VSL.

Limitations

VSL complements but does not replace the SDK. There are occasions when the SDK is more suitable, and there are certain things that VSL cannot do:

- no templates in VSL
- no pointers in VSL
- no dynamic allocation (e.g. operators like New) in VSL
- no writing to or reading from the disk with VSL
- no class creation in VSL
- no double type in VSL
- VSL scripts have a limit of 65,535 characters

The VSL <- SDK Binding Tables page lists all capabilities available in VSL and their corresponding SDK element. If an SDK element is not listed in the tables, then that SDK element is not available in VSL.

Note: Some things, such as the creation of managers, file importers, new parameter types etc., are only possible with the Virtools SDK. See the section Schematic v. VSL v. SDK - Which One to Use? on the Introducing VSL page for further information.


VSL Script Manager

Overview

The VSL Script Manager allows you to edit and debug VSL Scripts. The VSL Script Manager is the only location in Dev where you can do this. The VSL Script Manager also allows you to compile VSL scripts and run them. Before using the VSL Script Manager, make sure you first read Understanding VSL.

Toolbar Errors and Watchview VSL Scripts Code View BB Connectors Function Call Stack

Select a portion of the image above for more information.

Top Toolbar

Compile All
Attempts to compile all no compiled scripts.

Compile All + Shift
Force to compile all scripts.

Release/Debug
Sets the compilation mode. Note that compiling Run VSL scripts in a different compilation mode will result in the VSL Manager first attempting to compile any linked Global scripts first, if the Global script(s) are not in that mode.

Resize All
Returns all parts of the VSL Script Manager window to their default size.

Display Instances
Show/Hide Run VSL BB instances.

Save and Load
VSL scripts are saved as text files with the .VSC extension. Note that you can only load a VSL script into an existing VSL script. Ensure the script is empty; otherwise, the script you are importing will replace whatever code you already have. Note also that all you are saving or importing is the code from the code view - no information on connectors (bIns, bOuts, pIns, pOuts) is saved.

Debug Tools

The following tools only work if the currently selected VSL script is in debug mode.

Breakpoint
Adds/removes a breakpoint.

F9 + Shift
Remove all breakpoints in the selected script.

F9 + Shift + Control
Remove all breakpoints in all scripts.

Run Script
Executes a Run VSL script or continues execution of a Run VSL script after stopping at a breakpoint. Note that Run Script only executes the VSL script, and does not activate the Run VSL BB itself - therefore bIns and bOuts are not activated (but pIn values are used, and pOuts are calculated).

Stop Script
Stops execution of a Run VSL Script (but only if the VSL script was manually activated in Author mode; this button has no effect on a Run VSL BB activated in the Schematic).

Step
Advance one line of code, but do not enter a function if one is called.

Step Into
Advance one line of code and enter a function if called.

Step Out
Leave called function and return to line of code that called the function.

VSL Scripts Column

VSL Scripts

There are no limits on the number of folders or sub-folders you can create. You can use drag-and-drop to organize your VSL scripts, except that you cannot drag a script from Global to Run VSL or to Actions, and vice versa.

The contextual menus (right-click) allow you to do a number of things, including creating new folders, Global scripts, compiling all or selected scripts, etc.

The Global folder contains scripts that will be used to define functions, structures, enumerations used by other scripts (in Run VSL and in this folder). The Run VSL folder contains scripts that correspond to BBs in the Schematic. The new Actions folder contains scripts used in authoring mode and managed by the Action Manager.

Compiled

The compiled column displays the state of VSL scripts:

  • Debug (the script is in a debug state, meaning that execution is slow but debugging tools can be used).
  • Release (the script is is a release state, meaning it will execute several times faster than in debug).
  • No (the script has changed, or one or more of the Global scripts the script links to has changed. Therefore the script must be recompiled, and is neither in a state of debug or release).

Comp Time (Compilation Time)

The comp Time column displays when a script must be compiled.

  • Load At load the script is compiled.
  • Run The script will be compiled just before execute it.

Note that global script and instances don't have a Comp time column.

Run VSL Window/Code View

At the top of the window the name of the VSL script is displayed. The main section displays code that you can edit or add to. You are advised to write your code as you would for any other language, using indentation and comments. There are two ways of inserting comments:

  • using two slashes, e.g.
    // this is a comment

  • or using slash-asterisk to open a comment, and asterisk-slash to close, e.g.
    /* this is a comment */
The code view also supports features such as tooltips and auto-complete in much the same way as Microsoft Visual Studio. Many shortcuts are the same as well, such as F7 to compile the VSL script you are working on or F9 to insert a breakpoint. Note however that the code view must have focus for theses shortcuts to work. The contextual menu gives you access to useful features such as find/replace, cut/copy/paste and toggle (code view) to fullscreen.

Note that the maximum size for a single script is 65,535 characters.

BB Connectors (bIns, bOuts, pIns, pOuts)

The BB connectors column is the only place you can add and remove connectors (bIns, bOuts, pIns, pOuts), and change their order (by dragging). Note that changing the order of a connector in the VSL Script Manager also changes the order in the Schematic.

Name
The name of the connector. Press F2 to change.

Type
The type of variable used. Double-click to change. Note that the type for bIns and bOuts is Bool which cannot be changed.

To add a connector
Right-click the connector group and select Add.

To remove a connector
Select the connector and press DELETE.

Errors/Watchviews

The Errors window shows compilation errors (also shown in the Event Log) when attempting to compile VSL scripts.

The Errors window changes to a three paned Watchview when debugging scripts - you must be in debug mode, the script must be executing, and execution must be stopped by a breakpoint before any debug information can appear.

The Watchview windows display variable names and values and allow you to organize things better as you can copy variables from one pane to another. The number of possible Watchviews is set in the Variables Manager (the VSL Script Manager must be closed when you change this value).

You can changes the focus and change values for all visible types except str (although it may seem as though you *can* change values for str, these will be lost immediately when focus changes). Note that for CKObjects names and CK_IDs are visible, but once again these are not editable.

Note that you cannot debug SDK functions in Watchviews.

Function Call Stack

The Function Call Stack lists calls to functions and allows you to jump to the appropriate line of a function that your VSL script calls. This way you can easily trace back what is happening. Also variables that are displayed (name, value) are contextual to that function you are currently looking at.


Global Variable bc and ac

Global Variable bc

bc is a global variable which can only be used in Run VSL scripts. Its type is BehaviorContext. It provides some very useful methods to create object, write text in the console or in the 3D view, manage attributes, messages deal with variable manager, profiling yours scripts...

See more details on bc in the BehaviorContext Binding Table.

Global Variable ac

ac is a global variable which can only be used in Actions scripts. Its type is ActionContext. It provides methods to access mouse coordinates and selections. It also allow you to manage attributes and write text in the console and in the 3D view.

See more details on ac in the ActionContext Binding Table.


Using GUID

To get a GUID in VSL, you have to use GetGUID function:

Return | Function | Parameters
GUID | GetGUID | iGuidEnum (PGUID)

Here is the description of the enum PGUID:

PGUID

    GUID_DIRECTION
    GUID_NONE
    GUID_FLOAT
    GUID_ANGLE
    GUID_PERCENTAGE
    GUID_INT
    GUID_KEY
    GUID_BOOL
    GUID_STRING
    GUID_RECT
    GUID_VECTOR
    GUID_2DVECTOR
    GUID_QUATERNION
    GUID_EULERANGLES
    GUID_MATRIX
    GUID_COLOR
    GUID_BOX
    GUID_OBJECTARRAY
    GUID_OBJECT
    GUID_BEOBJECT
    GUID_MESH
    GUID_MATERIAL
    GUID_TEXTURE
    GUID_SPRITE
    GUID_3DENTITY
    GUID_CURVEPOINT
    GUID_LIGHT
    GUID_TARGETLIGHT
    GUID_ID
    GUID_CAMERA
    GUID_TARGETCAMERA
    GUID_SPRITE3D
    GUID_OBJECT3D
    GUID_BODYPART
    GUID_CHARACTER
    GUID_CURVE
    GUID_2DCURVE
    GUID_LEVEL
    GUID_PLACE
    GUID_GROUP
    GUID_2DENTITY
    GUID_RENDEROBJECT
    GUID_SPRITETEXT
    GUID_SOUND
    GUID_WAVESOUND
    GUID_MIDISOUND
    GUID_OBJECTANIMATION
    GUID_ANIMATION
    GUID_KINEMATICCHAIN
    GUID_SCENE
    GUID_BEHAVIOR
    GUID_MESSAGE
    GUID_SYNCHRO
    GUID_CRITICALSECTION
    GUID_STATE
    GUID_ATTRIBUTE
    GUID_CLASSID
    GUID_VOIDBUF
    GUID_BLENDMODE
    GUID_FILTERMODE
    GUID_BLENDFACTOR
    GUID_FILLMODE
    GUID_LITMODE
    GUID_SHADEMODE
    GUID_GLOBALEXMODE
    GUID_ZFUNC
    GUID_ADDRESSMODE
    GUID_WRAPMODE
    GUID_3DSPRITEMODE
    GUID_FOGMODE
    GUID_LIGHTTYPE
    GUID_SPRITEALIGN
    GUID_SCRIPT
    GUID_LAYERTYPE
    GUID_STATECHUNK
    GUID_DATAARRAY
    GUID_COMPOPERATOR
    GUID_BINARYOPERATOR
    GUID_SETOPERATOR
    GUID_SPRITETEXTALIGNMENT
    GUID_OBSTACLEPRECISION
    GUID_OBSTACLEPRECISIONBEH
    GUID_OBSTACLE
    GUID_PATCHMESH
    GUID_POINTER
    GUID_ENUMS
    GUID_STRUCTS
    GUID_FLAGS
    GUID_FILTER
    GUID_TIME
    GUID_OLDTIME
    GUID_COPYDEPENDENCIES
    GUID_DELETEDEPENDENCIES
    GUID_SAVEDEPENDENCIES
    GUID_REPLACEDEPENDENCIES
    GUID_SCENEACTIVITYFLAGS
    GUID_SCENEOBJECT
    GUID_SCENERESETFLAGS
    GUID_ARRAYTYPE
    GUID_RENDEROPTIONS
    GUID_PARAMETERTYPE
    GUID_MATERIALEFFECT
    GUID_TEXGENEFFECT
    GUID_TEXGENREFEFFECT
    GUID_COMBINE2TEX
    GUID_COMBINE3TEX
    GUID_BUMPMAPPARAM
    GUID_TEXCOMBINE
    GUID_PIXELFORMAT
    GUID_AXIS
    GUID_SUPPORT
    GUID_BITMAP_SYSTEMCACHING
    GUID_OLDMESSAGE
    GUID_OLDATTRIBUTE

Exemple:

void main()
{
    // Create an array.
    Array myArray = bc.CreateArray("MyArray", false, true);

    /// Then we add some columns.
    //

    // Add an Entity3D column.
    myArray.InsertColumn(-1, CKARRAYTYPE_OBJECT, "entity", GetGUID(GUID_3DENTITY));

    // Add an int column.
    myArray.InsertColumn(-1, CKARRAYTYPE_INT, "age", GetGUID(GUID_INT));

    // Add 10 Vector columns.
    GUID guid_vector = GetGUID(GUID_VECTOR);
    String columnName;
    for (int i = 0; i < 10; ++i) {
        columnName = "vector";
        columnName += i;
        myArray.InsertColumn(-1, CKARRAYTYPE_PARAMETER, columnName.Str(), guid_vector);
    }
}


Learn VSL

Learn VSL By Example

The following series of exercises show you how to use the VSL Script Manager and should give you a better idea of some of things that you can achieve using VSL.

You are advised to review these examples in the order listed below.

  1. Hello World
  2. Concatenating Strings
  3. Solving a 2nd Degree Equation
  4. Parsing a String
  5. Placing Objects in a Circle
  6. Reading Strings from an Array
Once you have reviewed these examples, check out the many other VSL technical samples supplied in the Virtools Minisite, located in Dev's Documentation folder under \CMOS\TechnicalSamples\VSL\Samples\.


Learn VSL - Hello World

This first exercise shows you how to create, write, compile, and run a VSL script. Our goal is to implement that classic first programming exercise: output "Hello World" to the console (Event Log).

  1. Start a new composition and create a script on the Level. From the Building Blocks tab, drag the Run VSL BB (VSL/Run VSL) into the script in the Schematic.

    As you can see, when you first add this BB to a script, it doesn't have any pIns or pOuts (later, you will see how to add pIns and pOuts). A Run VSL BB can only be edited in the VSL Script Manager.

  2. To open the VSL Script Manager, do one of the following:
    • Click on the Run VSL BB and press the V key.
    • From the Editors menu, select VSL Script Manager. The script is in the Run VSL folder in the left tree.

  3. Now copy this code into the editor:
    4. 	void main()
    {
        String s = "Hello World.";
        bc.OutputToConsole(s);
    }
  4. To compile the code you have added to your script, do one of the following:
    • Press F7
    • Right-click your VSL script (in the VSL Scripts section of the window) and select Compile from the contextual menu.

  5. Verify that there are no errors reported in the Errors part of the VSL Script Manager window. If there are any errors, correct them and try to compile again.

  6. Rename your script by selecting it in the left pane of the VSL Script Manager, pressing F2, and entering "Hello World".

  7. Run your script, using one of the following methods:
    • From the VSL Manager, if your script was compiled in debug mode.
      • Press F5.
      • Click Run Script.
    • In Play mode, as you would for any other BB (i.e. in the Schematic connect the bIn to the Start).

  8. Now open the console (Event Log), and you will see that "Hello World." is displayed!


Learn VSL - Concat String

In this exercise you will see how to add pIns to a VSL script, and in the event of errors, how to locate them. The goal of this exercise is to take two strings as pIns and output them, as a single string, on a pOut.

  1. Start a new composition and create a script on the Level. In the Schematic, double-click anywhere on the script body while pressing CTRL. A list of all available BBs appears. Type "ru" (without the quotes), and "Run VSL" appears. Click Run VSL to add the BB to the script. Finally, select the Run VSL BB, press F2, and rename the BB to Concat String.

    Now you need to add two pIns (for the two strings that are to be concatenated) and one pOut (for the result) to the BB. You can only configure the connectors for the Run VSL BB in the VSL Script Manager.

  2. Press the V key on the Run VSL BB to open the VSL Script Manager. In the right side of the VSL Script Manager, right-click pIn and select Add pIn.

    You just added a new pIn to your BB. Its default type is int and it's default name is "pIn0". You will change both.

  3. Double-click int in the Type column, and change the type to String. Press F2 and rename the pIn "string1" (without the quotes). Add a second pIn, change the type to String and rename the pIn to "string2". Finally, add a pOut in the same manner, again changing the type to String and renaming the pOut to "strConcat".

  4. Copy the following lines of code into the code window (called Concat String as long as you renamed the BB in step 1. above):

        void main()
    {
        strConcat = string1 + string2
    }
  5. Ensure that the compilation mode is set to debug, and compile your script (right-click the script, compile).

    The VSL script does not compile. An error message appears informing you of the error and telling you the line: Concat String, line 4 : parse error, expecting `';''

  6. To immediately go to the error, do one of two things:
    • Double-click the error message
    • Press F4

    The line containing the error is indicated by a yellow arrow. The error message tells you that a ';' must be added.

  7. Correct the error so that the line is as follows:
            strConcat = string1 + string2;
  8. Compile once more and then switch to the Schematic. To edit the pIns you created, double click the Run VSL BB as you would for any other BB to display the Edit Parameters dialog box. Enter the following values (without the quotes):
    • string1 = "This is your "

    • string2 = "second vsl script"

  9. Connect concatString to the Start of the script, and press Play, then Stop. Check the value of the strConcat pOut; its value will be "This is your second vsl script".


Learn VSL - 2nd Degree Equation Resolution

Learn VSL - Solving a 2nd Degree Equation

The goal of this exercise is to write a script that can solve a 2nd degree equation:
Find the value of x, given the expression ax^2+bx+c = 0, and
given the values of a, b, c

The algorithm is as follows:

delta = b^2-4ac

if delta < 0
then
    there is no solution

else
    there are one or two solutions:
    x' = (-b+sqrt(delta))/2a
    x'' = (-b-sqrt(delta))/2a
  1. Start with a new composition, create a script, and add a Run VSL BB to the script as you have done in the previous two exercises. Rename the BB to "Solve 2nd Degree" (without the quotes). Switch to the VSL Script Manager, and add three pIns of type Float called "a", "b", "c" and two pOuts (also of type Float) called "x1" and "x2".

  2. Enter the following code into the code window:
    void main()
{
    if (!a)
        return;

    float delta = pow(b, 2)-4*a*c;

    if (delta >= 0)
    {
        x1 = (-b+sqrt(delta))/2*a;
        x2 = (-b-sqrt(delta))/2*a;
    }
}
  3. Compile the VSL script, switch to the Schematic and enter the following values for the pIns:
    • a = 3
    • b = 5
    • c = -3

  4. Run your VSL script. Check the pOuts; you should see the following results: x1 = 4.21537 x2 = -19.2154.

    The VSL script functions correctly, but can be optimized. Currently the sqrt of delta is calculated twice. However it is possible to calculate it only once, to store the value, and reuse the value later in the script.

  5. Modify your VSL script as follows:
    void main()
{
    if (!a)
        return;

    float delta = pow(b, 2)-4*a*c;

    if (delta >= 0)
    {
        float sqrtDelta = sqrt(delta);

        x1 = (-b+sqrtDelta)/2*a;
        x2 = (-b-sqrtDelta)/2*a;
    }
}
  6. Compile the VSL script once again and run it.

    You probably did not notice any difference. This is normal as the VSL script is small. However, many small optimizations like this can greatly decrease the overall execution time of your composition (which, of course, is a Good Thing (tm)).

    The VSL script can be further optimized, as the value of x is not calculated:

    • When 'a' is equal to 0, the script could stop as the case is no longer a second degree equation.
    • If delta is negative, the script could stop as there there is no solution.

    You will now add two bOuts to support these cases.

  7. In the right side of the VSL Script Manager, right-click bOut and select Add bOut. Repeat so that you have added two bOuts. Rename the bOuts from bOut1 and bOut2 to "Not Second Degree" and "No Solution".

    Note that the VSL Manager renames the bOuts to "Not_Second_Degree" and "No_Solution" - VSL does not support variable names with spaces. Note also that the type for bOuts is bool (which can be TRUE (on) or FALSE (off)). The type for bOuts can not be changed.

  8. Modify your code to match the following:
    void main()
{
    if (!a)
    {
        Not_Second_Degree = TRUE;
        return;
    }

    float delta = pow(b, 2)-4*a*c;

    if (delta >= 0)
    {
        float sqrtDelta = sqrt(delta);

        x1 = (-b+sqrtDelta)/2*a;
        x2 = (-b-sqrtDelta)/2*a;
    }
    else
    {
        No_Solution = TRUE;
        return;
    }

    Out = TRUE;
}
  9. Now your VSL script has three bOuts that it can activate, as necessary, in response to the input data.

    Note: When the VSL script only had a single bOut it was not necessary to explicitly activate the bOut output as this was automatically done when the VSL Manager had finished executing the code. However, with two or more bOuts you need to write your VSL script such that you explicitly activate the appropriate bOut at the appropriate time.


Learn VSL - Parse String

Learn VSL - Parsing a String

This exercise demonstrates parsing a string and filling an Array with information contained in the string.

  1. Start with a new composition and create an Array. Rename the Array to "Players" (without the quotes) and add three columns with the following name - column types:
    • NickNames - String
    • Age - Integer
    • Score - Integer.

  2. Create a new script on the Level and add the Run VSL BB to it. In the VSL Script Manager add two pIns. Rename the first pIn to "data" and set the type to String. Rename the second pIn to "array" with the type set to Array.

  3. Switch to the Schematic, and enter the following string (without quotes) as the value for the "data" pIn you created a few moments ago:

    "Eva,22,1024.
    Jane,34, 544.
    Pierre, 17, 5410.
    John, 85,10."

    You may want to expand the data entry field for the "data" pIn.

    The idea is to parse the input string to extract information that is then copied to an Array. For this exercise, the required information is name, age and score. The commas and periods are of no interest as data but are useful as characters that separate data fields or signal the end of a line. You will use the StringTokenizer class as listed in VSL <- SDK Binding Tables - Classes and Methods. Given a string to parse and the separator used, the method "NextToken(str iPrevToken)" extracts tokens one by one.

  4. Enter the following code into the code window:
    void main()
{
    // We clear all data in the array
    array.Clear();

    // We create the first tokenizer in order to
    // get data line by line. The "." separates lines.
    str tokenLine = null;
    StringTokenizer tokenizerLine(data.CStr(), ".");

    int row = 0;

    // Get new line
    while (tokenLine = tokenizerLine.NextToken(tokenLine))
    {
        // For each line extracted, we add a row in the array
        array.AddRow();

        // The second tokenizer works with the extracted line
        // to extract the data on a word by word basis.
        // The "," separates words.
        str tokenWord = null;
        StringTokenizer tokenizerWord(tokenLine, ",");

        int column = 0;

        // Get new word
        while (tokenWord = tokenizerWord.NextToken(tokenWord))
        {
            // Insert word in the array
            array.SetElementStringValue(row, column, tokenWord);
            ++column;
        }
        ++row;
    }
}
  5. Compile the VSL script and run it. Verify that the contents of the Array are as follows:

    You can see that the names "Jane", "Pierre" and "John" are not extracted very well as they start with a return character (the non-printing return character is shown as a small box). In order to remove this extra character, you need to add a function to the VSL script that removes the return character. The following code should perform this task:
    void 		RemoveFirstReturnCharacter(String str2clear)
{
    // If first character is equal to return...
    if (str2clear[0] == '\n')
        / ... crop string from second character to the end
        str2clear = str2clear.Crop(1, str2clear.Length()-1);
}
  6. Modify your code to include the above function. Your code should now look like this:
    void main()
{
    // We clear all data in the array
    array.Clear();

    // We create the first tokenizer in order to
    // get data line by line
    str tokenLine = null;
    StringTokenizer tokenizerLine(data.CStr(), ".");

    int row = 0;

    // Get new line
    while (tokenLine = tokenizerLine.NextToken(tokenLine))
    {
        // For each line extracted, we add a row in the array
        array.AddRow();

        // The second tokenizer works with the extracted line
        // to extract the data on a word by word basis.
        // The "," separates words.
        str tokenWord = null;
        StringTokenizer tokenizerWord(tokenLine, ",");

        int column = 0;

        // Get new word
        while (tokenWord = tokenizerWord.NextToken(tokenWord))
        {
            // Remove first character if it's a '\n'
            String strToClear = tokenWord;
            RemoveFirstReturnCharacter(strToClear);

            // Insert word in the array
            array.SetElementStringValue(row, column, strToClear.CStr());
            ++column;
        }
        ++row;
    }
}
    Now, just before inserting a word into the Array, the new function checks the string and modifies it (if necessary) to remove the return character.

  7. Compile your VSL script and run it. Your Array looks a lot better now!


Learn VSL - Place Objects in a Circle

Learn VSL - Placing Objects in a Circle

This exercise demonstrates how to use VSL to manipulate 3D Entities and copy objects.

  1. Start a new composition and add several random objects (or create several 3D Frames) in the 3D Layout. Create a Group and add all the objects to the Group.

    Note: if you use 3D Frames make sure you select the Show All Frames check box in Player Mode section of the 3D Layout - Rendering preferences to be able to see the 3D Frames in player mode!

  2. Create a script on the level and add a Run VSL BB to it. In the VSL Script Manager, add two pIns: the first called "objGroup" of type Group and the second called "radius" of type float.

  3. Copy the following code into the code view, and compile the VSL script:
    void main()
{
    // Get number of objects
    int nbObject = objGroup.GetObjectCount();

    // Calculate angle betwen each objets
    float angle = 2*pi/nbObject;

    Vector pos(0,0,0);

    // Place each object on the circle
    for (int i = 0; i < nbObject; ++i)
    {
        // We get the nth object and cast it in Entity3D
        Entity3D obj = Entity3D.Cast(objGroup.GetObject(i));

        // If cast failed obj is null so we skip process...
        if (!obj)
            continue;

        // Compute object position
        pos.x = radius*sin(i*angle);
        pos.z = radius*cos(i*angle);

        // Place object
        obj.SetPosition(pos, null, true);
    }
}
  4. In the Schematic, edit the parameters of your Run VSL BB as follows:
    • objGroup = Group1 (or the name you chose for the group)
    • radius = 10

  5. Run the VSL Script. You will see that all objects in the 3D Layout are now equally spaced around the circumference of a circle.

    An interesting modification to this script would be to use a single object and copy it several times at run-time rather than have several objects at the start.

  6. In the VSL Script Manager, remove the Group pIn and add two pIns: one called "originalObject" of type Entity3D and the other called "nbObject" of type int. Then modify your code to match the following:
    void main()
{
    // Calculate angle betwen each objets
    float angle = 2*pi/nbObject;

    Vector Pos(0,0,0);

    // Place each object on the circle
    for (int i = 0; i < nbObject; ++i)
    {
        // We copy a nth object and cast it in Entity3D
        Entity3D obj = Entity3D.Cast(bc.Copy(originalObject, true, true));

        //If cast failed obj is null so we skip process...
        if (!obj)
            continue;

        // Compute object position
        pos.x = radius*sin(i*angle);
        pos.z = radius*cos(i*angle);

        // Place object
        obj.SetPosition(pos, null, true);
    }
}
  7. Edit your pIns, compile and then run your VSL script.

    You will see that your original object was copied the specified number of times and that all objects are now equally spaced around the circumference of a circle. Note that the copied objects have been created dynamically (as controlled by the second parameter of the "Copy" method of object bc (Behaviour Context)). If you press reset, all of your dynamically created objects are destroyed.


Learn VSL - Reading Strings from an Array

This exercise demonstrates how to use VSL to read Strings from an array, it is the inverse procedure of exercise 4.

  1. Start to create an array and go to "Array Setup" to edit it.
    Add as many String columns as you like, and create some rows.
    Now fill the cells with some text.
  2. Here is what your array might looks like :

  3. Create a script on the Level and add a Run VSL BB to it. In the VSL Script Manager, add one pIn to the BB of type "Array" and named it "myarray". Edit the parameter and set it to your Array.
  4. Copy the following code into the code view, and compile the VSL script:
    void main()
{
    // Array where we will put the strings that will be read.
    ArrayString arrayString;

    // String as temporary buffer.
    String tmp;

    // Loop to read each array's cell.
    for (int c = 0; c < myarray.GetColumnCount(); ++c) {
        for (int r = 0; r < myarray.GetRowCount(); ++r) {

            // First we get the size of the string at pos (r, c)
            int lengthToRead = myarray.GetElementStringValue(r, c, null);

            // Then we resize the string before reading the array.
            tmp.Resize(lengthToRead);

            // At last, we can read the string.
            // Note that 3rd parameter of GetElementStringValue is a str
            // and not an String.
            myarray.GetElementStringValue(r, c, tmp.Str());

            // We keep the read string in our array.
            arrayString.PushBack(tmp);
        }
    }

    // We can do what we want with these strings.
    int stringNb = arrayString.Size();
    for (int i = 0; i < stringNb; ++i) {
        bc.OutputToConsole(arrayString[i].Str());
    }
}

Now check out the many other VSL technical samples supplied in the Virtools Minisite, in Dev's Documentation folder under \CMOS\TechnicalSamples\VSL\Samples\.


VSL Core Language Features

Core Language Features

Bases and Procedural Approach

  • Values, Types and Variables
  • Expressions and Operators
  • Statements
  • Functions
  • Enumerations
  • Structures

    • Object Oriented Approach

  • Using C++ Class in VSL
  • Binding new C/C++ functionality
    • Comments


VSL Values, Types and Variables

Values, Types and Variables

Values

VSL recognizes the following types of values:
  • Numbers, such as 123, 3.14159, 'v' or 0xe0d02090
  • Logical boolean values: true or false
  • Strings, such as "Virtools, The Behavior Company!"
  • Special keyword null which is equal to 0.

    • Types

    VSL is a typed language, which means that every variable and every expression has a type that is known at compilation time. Types determine the meaning of the operations; strong typing helps detect errors at compilation time.

    The VSL types are divided into 3 categories :

  • Primitive types
  • VSL structure types
  • C++ class/structure types

  • The primitive types are the boolean (bool) type and the numeric types. The numeric types are the integer types (char, int) and the floating-point type float.

    Type | Contents | Size | Range
bool | Type bool is an integral type. It represents a logical quantity with two possible values, indicated by the literals true and false | 4 Bytes | true or false (0 or 1)
char | Type char is an integral type that usually contains members of the execution character set, this is ASCII. | 4 Bytes | -128 to 127
int | Type int is an integral type. Equivalent to unsigned int type of C/C++. | 4 Bytes | –2147483647–1 to 2147483647
float | Type float is a floating type. Equivalent to float type of C/C++. | 4 Bytes | -3.402823466e+38F to 3.402823466e+38F
str | Type str is equivalent to char* type of C/C++. | 4 Bytes | -

    As you can see, all VSL primitives are implemented in 4 bytes, word-aligned in memory, independent of whether or not they need that much space. For example, the char type needs just 1 byte to represent the members of the ASCII table but uses 4 bytes in VSL.

  • A VSL structure is a way to create custom data types in VSL. A VSL structure can have zero or more members where each member can be of any type known by VSL. VSL structs are very similar to C structs

    Example of a structure declaration :
    struct Car
{
    Entity3D entity;
    Vector direction;
    float gaz;
};

  • VSL can manipulate C/C++ type. Before using a class in VSL you have to bind it.

    • VSL comes with a lot of Virtools SDK bound classes. In most cases, the class name changes from the Virtools SDK to VSL. CK3dEntity is a well know class for Virtools SDK users but in VSL its name changes to "Entity3D".

    Variables

    A variable is a storage location and has an associated type that is either a primitive type, a VSL struct or a C/C++ class. A variable always contains a value that is assignment compatible with its type. A variable’s value is changed by an assignment or by a prefix or postfix ++ (increment) or -- (decrement) operator.

    Here are some examples of variable declarations in VSL :

    // Declare an integer variable named "i"
int i;

// Declare an array of 123 float named "table"
float table[123];

// Declare a Vector variable named "speed", initialized with values 1.0, 2.0 and 3.0
Vector speed(1.0,2.0,3.0);

// Declare a variable referencing an Entity3D
Entity3D bird;

    Variables Scopes

    VSL names can be used only in certain regions of a program. This area is called the “scope” of the name. The scope determines a name's “lifetime” for variables which are not static or shared. Scope also determines a name's visibility when class constructors and destructors are called, and when the scope's local variables are initialized.

    void foo(int a) // start of the function foo scope
{
    if (a) // start of if scope
    {

    } // end of if scope
} // end of the function foo scope

    Let us examine variable lifetime in a simple example :

    float angle; // Declaring a global variable

void foo()
{
    angle = 0.01; // ok
}

void foo2(int a)
{
    angle = a*180/P; // error, P is not yet declared
    float P = 3.14159;

    if (a) // ok
    {
        float angle2 = 360-angle; // ok
    }
    bc.OutputToConsole(angle2); // it doesn't exist outside of the scope of the enclosing braces {...}

}

    When you declare a variable outside of a function, it is called a global variable, because it is available everywhere in the current VSL script.

    Static and Shared Global Variables

    Only global variables can be shared or static.

    • A static global variable has the specificity of keeping its value between two executions of a script.
    • A shared global variable has the ability to keep its value static but it is able to be "shared" between all script that declare it.

    How to declare static or shared global variables
    shared int a; // a is a shared global variable
static float b;	// b is a static global variable

void main()
{
    shared int i;// i is not a shared variable (shared keyword is ignored)
    static float j;// j is not a static variable (static keyword is ignored)
    // ...
}

    You can't initialize or call a no default constructor when declaring static or shared global variable.

    shared int a = 0; // error
static Vector v(1.0,2.0,3.0); // error

void main()
{
    static int b = 0; // Not an error because static keyword is ignored
    shared Vector w(-1,0,0); // Not an error because shared keyword is ignored
    // ...
}

    Static global variable

    A static global variable has the specificity of keeping its value between two executions of a script.

    Example:

    // ...
static int a;

void main()
{
    if (iIn1) { // iIn1 is a boolean global variable
        a = 0;
    } else {
        ++a;
    }
}

    If iIn1 is true when we execute the script the first time, a is equal to 0.
    Then we set iIn1 to false in order that the next script execution will increment a, so the second execution will set a to 1, the third will set a to 2, etc.

    Shared global variable

    A shared global variable has the ability to keep its value static but it is able to be "shared" between all script that declare it.

    Example:

    // First script
shared Vector pos;

void main()
{
    pos.Set(0,1,0.5);
}

    // Second script
shared Vector pos; // the second script also declares pos as a shared Vector

void main()
{
    Vector test(0,1,0.5)
    if (pos == test) {
        // ...
    }
}

    If we execute the first script before the second, pos value is {0,1,0.5} so condition pos == test is true in the second script.

    Names

    With VSL, certain names are forbidden as variable names such as class/struct names and some reserved names:
    main
    int
    short
    float
    char
    while
    do
    bool     		if
    for
    then
    else
    true
    false
    TRUE
    FALSE     		NULL
    null
    struct
    class
    enum
    extern
    shared
    static

    switch
    case
    default
    break
    continue
    return

    The compiler searches for names in the following order, stopping when the name is found :

  • Search name from current scope to global scope
  • Search if names is an enums value
  • Search if name is a defined constant
    • void foo(int a)
{
    bc.OutputToConsole(pi); // print 3.14159 (pi is a constant in VSL)

    float pi = 1.0;

    if (a)
    {
        float pi = 0.5;
        bc.OutputToConsole(pi); // print 0.5
    }

    bc.OutputToConsole(pi); // print 1.0
}

    enum Const
{
    pi,
    epsilon,
    maxint,
};

void foo(int a)
{
    bc.OutputToConsole(pi); // print 0

    float pi = 1.0;

    if (a)
    {
        float pi = 0.5;
        bc.OutputToConsole(pi); // print 0.5
    }

    bc.OutputToConsole(pi); // print 1.0
}


VSL Expressions and Operators

Expressions and Operators

Expressions

An expression is any combination of variables, operators, and expressions that evaluates to a single value. The value can be a number, a string, or a logical value.

There are two types of expressions: those that assign a value to a variable, and those that simply have a value. For example, the expression x = 5 is an expression that uses the assignment operator to assign the value 5 to x. The evaluation of x = 5 also returns the value 5. Alternatively, the expression (4 + 1) simply evaluates to 5, it does not perform an assignment

Operators

VSL has the following types of operators :

  • Assignment Operators
  • Comparison Operators
  • Arithmetic Operators
  • Logical Operators

    • Assignment Operators

    An assignment operator assigns a value to its left operand based on the value of its right operand.
    Equal (=) is the base of Assignment operators, x = y assigns the value of y to x.

    Supported
    Operator | Meaning
x += y | x = x + y
x -= y | x = x - y
x *= y | x = x * y
x /= y | x = x / y
    Unsupported
    Operator
    x %= y
    x <<= y
    x >>= y
    x >>>= y
    x &= y
    x ^= y
    x |= y

    Examples:

    void main()
{
    int x = 2;
    int y = 4;

    x += y; // x is equal to 6
    x -= 3; // x is equal to 3
    x *= y-1; // x is equal to 9
    x /= x-y; // x is equal to 1
}

    NOTE Assignment operator expressions evaluate to the value of their left operand after the assignment is performed. Therefore, the following script is syntactically valid:

    void main()
{
    int x;
    int y;
    int z = 10;

    x = y = z; // ok, x and y equal to 10
    x += y += z; // ok, x equal to 30 and y to 20
    x *= y /= z; // ok. x equal to 60 and y to 2
    // ...
}

    Comparison Operators

    A comparison operator compares its operands and returns a logical value based on whether the comparison is true. Here are the comparison operator supported by VSL.

    Operator | Meaning | Description
== | Equal | Returns true if the operands are equal.
!= | Not equal | Returns true if the operands are not equal.
> | Greater than | Returns true if the left operand is greater than the right operand.
>= | Greater than or equal | Returns true if the left operand is greater than or equal to the right operand.
< | Less than | Returns true if the left operand is less than the right operand.
<= | Less than or equal | Returns true if the left operand is less than or equal to the right operand.

    Examples :

    void main()
{
    int i = 10;
    float f = 2.3;
    bool b1 = i > f; // b1 equal to true
    bool b2 = b1 == i; // b2 equal to false
    i = b1 != b2; // i equal to 1;
}

    Arithmetic Operators

    Arithmetic operators take numerical values (literals or variables) as their operands and return a single numerical value.

    Operator | Meaning | Description
+ | Addition | Binary operator. Causes its two operands to be added. Both operands can be either integral or floating types.
- | Subtraction | Binary operator. Subtracts the second operand from the first. Both operands can be either integral or floating types.
* | Multiplication | Binary operator. Causes its two operands to be multiplied.
/ | Division | Binary operator. Causes the first operand to be divided by the second.
% | Modulus | Binary operator. Returns the integer remainder of dividing the two operands.
++ | Increment | Unary operator. Adds one to its operand. If used as a prefix operator (++x), returns the value of its operand after adding one, if used as a postfix operator (x++), returns the value of its operand before adding one.
-- | Decrement | Unary operator. Subtracts one to its operand. The return value is analogous to that for the increment operator.
(Unary) - | Unary negation | Unary operator. Returns the negation of its operand.

    Examples :

    void main()
{
    int i1 = 42;
    int i2 = 123;
    float f1 = .2;
    float f2 = 3567.3623;

    int r1 = i2-i1; // r1 equal 81
    float r2 = i2*f1; // r2 equal to 24.6
    int r3 = i2/2; // r3 equal to 61
    int r4 = f1*f2; // r4 equal to 713
    float r5 = f1*f2; / r5 equal to 713.472473

}

    void main()
{
    int a = 10;
    a++; // a equal to 11
    int b = ++a; // a and b equal to 12
    int c = a--; // a equal to 11 and c equal to 12
}

    Logical Operators

    The logical operators, AND (&&) and OR (||), are used to combine multiple conditions formed using relational or equality expressions.

    Operator | Meaning | Description
&& | Logical AND | Returns true if both operands are true, otherwise, returns false.
|| | Logical OR | Returns true if either operand is true, if both are false, returns false.
! | Logical NOT | Returns true if operand is false, else returns false.

    Examples :

    void main()
{
    Entity3D ent = Entity3D.Cast(bc.GetOwner());
    if (ent && ent.CanBeHide()) // if ent is null (false), expression ent.CanBeHide() is not evaluated
    {
        // ...
    }
}


VSL Statements

Statements

Conditional Statements

if else Statement

Use the if statement to perform certain statements if a logical condition is true, you can use the optional else clause to perform other statements if the condition is false. An if statement looks as follows :

if (condition) {statements1}[else {statements2}]

Example :

bool CheckTextureSquare(Texture tex)
{
    if (tex.GetHeight() == tex.GetWidth())
    {
        bc.OutputToConsole("Texture ok.");
        return true;
    }
    else
    {
        bc.OutputToConsole("Error, texture is not square.");
        return false;
    }
}

switch Statement

A switch statement allows a program to evaluate an expression and attempt to match the expression’s value to a case label. If a match is found, the program executes the associated statement. The expression must evaluate to an integer type. The syntax of a switch statement is as follows:

switch (expression){ case label : statement; [break;] case label : statement; [break;]... [default : statement;] }

Example :

void GetVectorDirection(int direction, Vector vec)
{
    switch(direction)
    {
        case 0 :
            // North
            vec.Set(0,1,0);
        break;

        case 1 :
            // East
            vec.Set(1,0,0);
        break;

        case 2 :
            // South
            vec.Set(0,-1,0);
        break;

        case 3 :
            // West
            vec.Set(-1,0,0);
        break;

        default :
            bc.OutputToConsole("error, bad direction number.");
        break;
    }
}

Loop Statements

for Statement

The syntax of the for statement is as follows:

for ([initialExpression]; [condition]; [updateExpression]) {statement block}

The for statement repeatedly executes the statement block until [condition evaluates to zero. The initialExpression, condition, and updateExpression fields are all optional.

The initialExpression is executed before any other element of the for statement, often used to initialize loop indices. It can contain declaration or assignment.

The condition is executed before execution of a given iteration of the loop, including the first iteration. It is an expression that evaluates to an integral type.

The updateExpression is evaluated at the end of each iteration of the loop. It is often used to be a assignment or as an increment expression.

Example:

float Average(IntArray array)
{
    float total = 0;
    int arraySize = array.Size();

    // Add all integers
    for (int i = 0; i < arraySize; ++i)
        total += array[i];

    return total/arraySize;
}

do-while Statement

The do-while statement repeats until the specified condition evaluates to false. The syntax of a do-while statement is as follows:

do {statement} while (condition);

The statement executes once before the condition is checked. If the condition returns true, the statement executes again.

Example :

void MakeItAtLeastOnce(int i)
{
    do
    {
        --i;
        // MakeIt ...
    }
    while (i > 0);
}

while Statement

The while statement lets you repeat a statement until the specified condition evaluates to false. The syntax of a while statement is as follows:

while (condition) {statements}

Example :

int Factorial(int n)
{
    int res = 1;
    while (n > 1)
    {
        res *= n--;
    }
    return res;
}

break Statement

Use the break statement to terminate a loop or a switch statement

Example :

void	FindIndex(IntArray array, int value)
{
    int size = array.Size();
    int i = 0;
    for (;i < size; ++i)
        if (array[i] == value)
            break; // We don't have to search anymore ...
                // exit the for loop

    // And continue processing here...
}

continue Statement

You can use the continue statement only inside loop statement. Executing the continue statement stops the current iteration of the loop and continues program flow with the beginning of the loop.

Example :

struct person
{
    bool men;
    int age;
};

float	AverageMenAge(person parray[3])
{
    int nbMen = 0;
    float  averageAge = 0;
    for (int i = 0; i < 3; ++i)
    {
        person p = parray[i];
        if (!p.men)
            continue; // Go to next iteration

        ++nbMen;
        averageAge += p.age;
    }
    if (nbMen)
        return averageAge/nbMen;
    return -1;
}


VSL Functions

Functions

Declaring VSL Functions

Function Definitions Syntax

Function definitions establish the name of the function, its return type, the type and number of its formal parameters, and (finally) the function body.

returnType functionName( [paramList] ) { functionBody }

paramList :
parameter, ...

parameter :
type parameterName

Example :

int Square(int i)
{
    return i*i;
}

Function Parameters

Parameters are the values the function expects to receive. In a function prototype, the parentheses following the function name contain a complete list of the function’s parameters and their types. Parameter declarations specify the types, sizes, and identifiers of values stored in the parameters.

When declaring parameters, you can specify defaults values.

void MakeAction(int actionNumber, bool logInConsole = false)
{
    // Make action according to actionNumber
    // ...

    if (logInConsole)
    {
        String message("Make Action Num ");
        message += actionNumber;
        bc.OutputToConsole(message);
    }
}

void main()
{
    MakeAction(0, true);
    MakeAction(1, false);

    // In this case, second parameter of MakeAction
    // is equal to default value false
    MakeAction(0);
}

You can declare functions with no parameter.

float Pi()
{
    return 3.14156;
}

Function Return Type

The return type of a function establishes the size and type of the value returned by the function.
Here is a list of all type-specifiers than can be returned in a function :

    void
    char
    int
    float
    VSL enum
    VSL struct
    C/C++ struct/class
You can declare functions with no return type. In this case you have to use "void" as type name.

void Print(String s, int line)
{
    s += line;
    bc.OutputToConsole(s);
}

Function Overloading

VSL allows specification of more than one function of the same name. These are called “overloaded functions”. Overloaded functions enable programmers to supply different semantics for a function, depending on the types and number of arguments.

Examples:

int Add(int a, int b) // Add two int
{
    return a + b;
}

float Add(float a, float b) // Add two float
{
    return a + b;
}

void main()
{
    float r1 = add(10.0,5.0); // Call first Add function
    int r2 = add(1,2); // Call second Add function
}

When you have overloaded functions, it is the VSL compiler which choose the matching function. In some case you can have an ambiguous situation because the compiler does not know which function to choose.

void main()
{
    float r = add(10.0, 5); // error, ambiguous call
}

This function call is ambiguous because, both Add functions could be used:
10.0 could be cast in int or 5 could be cast in float.

Calling Functions

In a VSL script, you can call any VSL function defined in the current script, in a global script or any bound C/C++ function. Defining a function does not execute it. Defining the function simply names the function and specifies what to do when the function is called. Calling the function actually performs the specified actions with the indicated parameters.

Recursivity

A function can even be recursive, that is, it can call itself. For example, here is a function that computes Fibonacci numbers:

int fibo(int n)
{
    if (n == 0)
        return 0;
    if (n == 1)
        return 1;
    return fibo(n-2)+fibo(n-1);
}

void main()
{
    fibo(3); // return 2
    fibo(4); // return 3
    fibo(5); // return 5
    fibo(6); // return 8
}

Passing Parameters To VSL Functions

In VSL, all primitive types (bool, char, int, float, str) are passed by value. The value is passed to the function, but if the function changes the value of the parameter, this change is not reflected globally or in the calling function.

void foo(int a)
{
    a = 10;
    bc.OutputToConsole(a); // Print 10 in the console
}

void main()
{
    int b = 3;
    foo(b);
    bc.OutputToConsole(b); // Print 3 in the console
}

VSL struct and C/C++ struct/class are passed by reference. If a function modifies a referenced parameter, it modifies the original too.

void ChangeVector(Vector v)
{
    v.x = 1.0;
    v.x = 2.0;
    v.x = 3.0;
}

void main()
{
    Vector v(0.0,0.0,0.0); // the members x, y and z are equal to 0.0

    ChangeVector(v);
    bc.OutputToConsole(v.x); // Print 1.0
    bc.OutputToConsole(v.y); // Print 2.0
    bc.OutputToConsole(v.z); // Print 3.0
}

Passing Parameters To C/C++ Functions

When calling C/C++ functions, VSL respect C/C++ rules according to the function declarations. Constants parameters are not supported in VSL, but it is possible to use const C/C++ function and to use C/C++ functions with constants parameters. Since the const keyword is not implemented, you must take extra care when using C/C++ functions with constant parameters.


VSL Enums

Enums

The enum keyword specifies an enumerated type. An enumerated type is a user-defined type consisting of a set of named constants called enumerators. By default, the first enumerator has a value of 0, and each successive enumerator is one larger than the value of the previous one (unless you explicitly specify a value for a particular enumerator).

Definitions Syntax :

enum enumName { enumMember , ... };

enumMember :
enumMembersName
or
enumMembersName = integerValue

Examples :

enum CharacterType
{
    HUMAIN,		// 0
    MONSTER,	// 1
    GHOST,		// 2
    BIRD		// 3
};

enum DisplacementMode
{
    WALK,
    FLY,
    TELEPORT
};

Then you can use your defined constant in your functions.

void ManageCharacterMove(Entity3D charac, CharacterType type, DisplacementMode disp)
{
    switch (type)
    {
        case HUMAIN :
            if (disp == WALK)
            {
                // ...
            }
            else if (disp == FLY)
            {
                // ...
            }
            else
            {
                // ...
            }
        break;

        case MONSTER :
            // ...
        break;

        // ...
    }
}

Enumerators needn’t have unique values. The name of each enumerator is treated as a constant and must be unique within the scope of where the enum is defined.

enum week
{
    Mon = 1, 	// forces start at value 1
    Tue, 		// 2
    Wed, 		// 3
    Thu, 		// etc
    Fri,
    Sat,
    Sun
};

enum weekend
{
    Sat, // error, Sat redefinition
    Sun // error, Sun redefinition
};


VSL Structures

Structures

Definitions Syntax

A structure type is a user-defined composite type. A struct is composed of "members" that can have different types.

struct structName { memberList };

Example :

struct Person
{
    String name;
    int age;
    float weight;
};

The type of each struct member can be of a primitive type, other VSL structs, or C/C++ struct/class. Members that are arrays of these types are also supported.

struct Car
{
    Entity3D entity;
    Person passengers[4];
    float weight;
    Vector velocity;
};
To access a struct member, you have to use the "." operator.
void SetPerson(Person p, String name, int age, float weight)
{
    // Set name
    if (name == "")
        p.name = "Unknown";
    else
        p.name = name;

    // Set age
    if (age < 0)
        age = 1;
    p.age = age;

    // Set weight
    if (weight < 0)
        weight = 40;
    p.weight = weight;
}

void main()
{
    Car car;
    car.entity = null;
    car.velocity.Set(0,0,0);

    car.weight = 1500;

    // Set persons
    for (int i = 0; i < 4; ++i)
    {
        String name("Passengers");
        name += i;
        SetPerson(car.passengers[i], name, rand()*20+20, rand()*30+60);

        // Add person weight to the car weight
        car.weight += car.passengers[i].weight;
    }
}

Using operator =, == and != On Structures

When using =, == and != operators on a structure, the VSL compiler calls the appropriate operators for each member that has this overloaded operator. If one member is (itself) a structure, the VSL Compiler inspects each submember as necessary.

For members that do not have overloaded operators, this code is produced:

Operator =
Code is generated to copy memory.

Operator == and !=
Code is generated to compare memory.

Examples:

Person p1;
Person p2;

String name("john");
SetPerson(p1, name, 30, 75);

p2 = p1;
is equivalent to:
p2.name = p1.name; // call the String operator =
p2.age = p1.age;
p2.weight = p1.weight;

p2 == p1;
is equivalent to:
p2.name == p1.name; // call the String operator ==
p2.age == p1.age;
p2.weight == p1.weight;

p2 != p1;
is equivalent to:
p2.name != p1.name; // call the String operator !=
p2.age != p1.age;
p2.weight != p1.weight;


VSL - Using C++ Class

Using C++ Class in VSL

This section is not for readers that are just learning how to program in C++. We assume that you already have significant programming experience in C++.

VSL doesn't allow you to create new C++ classes or C/C++ functions. VSL does allow you to manipulate existing C++ classes or C/C++ functions. VSL only recognizes "bound" C/C++ code and data - these classes, functions or enums must be registered in VSL before they can be used.

Many Virtools SDK features are ready to use in VSL, but VSL is not C++ and some notable differences appear in the manipulation of classes.

Unsupported C++ features

  • Pointer

    • "Pointers" do not exist in VSL. You can not declare a pointer in any form.

  • Dynamic Memory Allocation

    • The new operator does not exist in VSL. You can not allocate memory from the heap in VSL.

  • Reference

    • The reference operator "&" does not exist in VSL. You can't manipulate references.

  • Const

    • The const keyword does not exist in VSL but you can call C++ functions or member functions that use the const notation.

  • Templates

    • Templates do not exist in VSL. The Template class can not be bound.

    Supported C++ features

    Constructor Calls

    In VSL, you can't allocate objects on the heap (you can't use the new operator).
    However, when you are declaring C++ objects, you are able to use constructors.

    Example :

    String s1; // Call default constructor
String s2("some text");
String s3(s2); // Call copy constructor

    Your are not allowed to explicitly call constructors in order to temporarily construct variables:

    Entity3D ent;
// ...
ent.SetPosition(Vector(0,0,0)); // error, can't call explicitly the constructor

    VSL sees C++ constructors as if they were all defined as explicit, meaning that a VSL script never has implicit conversions.

    Language
    Code
    Correct
    Comment
    C++

    void foo(XString s)
{
    // Do something ...
}

void main()
{
    foo("another text");
}
    Yes
    There is an implicit conversion in XString.
    XString constructor is called.
    foo("another text");
    is equivalent to:
    foo(XString("another text");
    VSL

    void foo(String s)
{
    // Do something ...
}

void main()
{
    foo("another text");
}
    No
    No implicit conversion is allowed.

    Members Access

    Like in C++, you have to use operator "." on C++ objects to access members. Because pointers do not exist in VSL, you never have to use the pointer member access operator "->" (ie: it does not exist).

    In VSL, you can not access private or protected members of a class because VSL does not permit you to bind them. Only public members of a class may be bound.

    Member functions call

    Calling member functions in VSL is just like in C++.

    Example :

    Matrix m;
m.SetIdentity();
    Static member functions call

    In C++, you call static member functions as follows: className :: staticFunctionName( paramList )
    In VSL, the scope resolution operator "::" doesn't exist; you must use the member access "." operator after the class name.

    Example :

    void foo(Object obj)
{
    Entity3D entity = Entity3D.Cast(obj); // Cast is a static functions
}
    Calling Overloaded operators

    Using overloaded operators in VSL is just like in C++.

    Supported operators:
    =, +=, -=, *=, /=, &&, ||, <, >, <=, >=, +, -, (unary)+, (unary)-,*, /, %, ++, --, !

    Example :

    Vector v1(1.0,2.1,.5);
Vector v2(0.2,1.9,3.1);
Vector v3 = v1*v2; // Call Vector overloaded operator *
    Accessing Members

    Accessing members in VSL is just like in C++.

    Example :

    Rect r;
r.left = 12.3;
r.top = 5.0;
r.right = -r.left;
r.bottom = -r.top;

    Calling Friend Functions

    Calling a friend function does not differ from calling a regular function.

    Derived Class

    VSL manages derived classes and polymorphism on C++ objects, meaning that virtual function calls are managed just like in C++.


VSL Binding new C/C++ functionality

Binding New C/C++ Functionality

This section is for developers who want add functionality to VSL by binding their own C/C++ code. In this context, "binding" means "to make your custom C/C++ code accessible as a runtime process".
Note: Remember that VSL is not C++. Not all C++ code is "bindable" by VSL.

Binding Architecture

All binding macros use VSLManager, so you have to be sure that VSLManager is successfully loaded before binding anything. The best way to bind your code and data is to create your own manager, inherited from CKBaseManager (see SDK documentation), and place your binding macro in your overloaded member function OnCKInit().

You must start your binding code with the macro STARTVSLBIND. STARTVSLBIND takes a single parameter: the unique CKContext of your application. You must finish with the STOPVSLBIND macro. For example:

#include "VSLManagerSDK.h"

CKERROR MyManager::OnCKInit()
{
    STARTVSLBIND(m_Context)

    // Binding macros ...

    STOPVSLBIND
    return CK_OK;
}

Class - Working Example

In the following sections, we will work with this hypothetic class:
// C++ code
class MyClass
{
 public :
     // Members
     int i;
    float f;
    AnotherClass ac;

    // Constructors and destructor
    MyClass();
    MyClass(int a, float f);
    ~MyClass();

    // Members functions
    void Nothing();
    float SetIAndF(int i, float f);
    int GetI() const;
    MyClass operator *(const MyClass &mc);

 private :
     // Private members can't be bound
};

Bind New Types

Binding new types is a fundamental VSL binding capability; it is also one of the most tricky features to use because you have different ways to bind new types. The various mechanisms are as follows.

DECLAREOBJECTTYPE(type)
type : your struct/class name.
Use this macro to bind struct/class.

Example:
In your MyManager::OnCKInit()

DECLAREOBJECTTYPE(MyClass)
In a VSL script:
MyClass a; // If a constructor is bound, it is called
MyClass b; // Ditto
a = b; // Implemented with memcpy because no assignment operator ( = ) is defined for this class.

DECLAREOBJECTTYPEALIAS(type,alias)
type : your struct/class name.
alias : a string (const char *) containing the name you will use in VSL to manipulate your struct/class.
Use this macro to bind struct/class and to use it with a different name in VSL.

Example:
In your MyManager::OnCKInit()

DECLAREOBJECTTYPEALIAS(MyClass, "myclass")
In a VSL script:
myclass a; // If a constructor is bound, it is called
myclass b; // Ditto
a = b; // Implemented with memcpy because no assignment operator ( = ) is defined for this class

DECLAREPOINTERTYPE(type)
type : your struct/class name.
Use this macro to bind pointer on struct/class (when the constructor is not accessible).
In this case VSL is not able to instantiate any object of this struct/class.

Example:
In your MyManager::OnCKInit()

DECLAREPOINTERTYPE(MyClass)
In a VSL script:
MyClass a; // No constructor is called, a must be affected
MyClass b; // Ditto
a = b; // Affectation is just a DWORD copy (MyClass is managed as a pointer) because no operator = exist

DECLAREPOINTERTYPEALIAS(type,alias)
type : your struct/class name.
alias : a string (const char *) containing the name you will use in VSL to manipulate your struct/class.
Use this macro to bind pointer on struct/class (when constructor is not accessible).
In this case VSL is not able to instantiate any object of this struct/class.
You will also use this class under its alias name.

Example:
In your MyManager::OnCKInit()

DECLAREPOINTERTYPEALIAS(MyClass, "myclass")
In a VSL script:
myclass a; // No constructor is called, a must be affected
myclass b; // Ditto
a = b; // Implemented as a DWORD copy of the pointer (myclass is managed as a pointer)
        //because no assignment operator ( = ) is defined for this class.

Bind Functions

DECLAREFUN_%T_%P(returnType,functionName, [paramDeclList] )
T : function call convention, C for CDECL and S for STDCALL.
P : number of parameters (0 to 6).
returnType : return type of the function.
functionName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

Example:

// C function declaration
void  div(int iNumer, int iDenom, int& oQuot, int& oRemain);
Then in our MyManager::OnCKInit()
DECLAREFUN_C_4(void, div, int iNumer, int iDenom, int& oQuot, int& oRemain)
In a VSL script:
int quot;
int remain;
div(5, 2, quot, remain);

Note that you can bind alias functions. You have to use the macro DECLAREFUNALIAS instead of DECLAREFUN.

DECLAREFUNALIAS_%T_%P(alias,returnType,functionName, [paramDeclList] )
T : function call convention, C for CDECL and S for STDCALL.
P : number of parameters (0 to 6).
alias : function's alias (const char *) .
returnType : return type of the function.
functionName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

Example in our MyManager::OnCKInit() :

DECLAREFUNALIAS_C_4("cDiv", void, div, int iNumer, int iDenom, int& oQuot, int& oRemain)

Bind Friends Functions

DECLAREFRIEND_%P(returnType,functionName, [paramDeclList] )
P : number of parameters (0 to 6).
returnType : return type of the function.
functionName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

Bind Friends Operators

DECLAREFRIENDOP_%P(returnType,operatorName, [paramDeclList] )
P : number of parameters (0 to 2).
returnType : return type of the function.
functionName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

NOTE: operator name must be : "operator" plus the operator.

Example:

// C++ function declaration
friend const VxVector operator + (const VxVector& v);
Then in our MyManager::OnCKInit()
DECLAREFRIENDOP_1(const VxVector,operator+,const VxVector& v);

Bind Constructors

To bind a constructor you have to define a constructor binding function that will call the real constructor (with the address of the variable as a parameter): this is called a "placement new".
Before binding constructors of a struct/class, this struct/class must be already bound with the macro DECLAREOBJECTTYPE or DECLAREOBJECTTYPEALIAS.
The constructor binding function's name MUST be the concatenation of the string "__new" ("new" is preceded by two underscore characters) and the struct/class C++ name that is being bound(and not the alias name).

In our case:

void __newMyClass(BYTE *iAdd)
{
    new (iAdd) MyClass();
}
And:
void __newMyClass(BYTE *iAdd, int a, float f)
{
    new (iAdd) MyClass(int a, float f);
}

Then you have to bind this function with the macro named "DECLARECTOR_" concatenated with the number of the constructor's parameters. The first parameter to the macro must be the function's name. If your constructor use parameters then you have to add their declarations (in the order that they appear in the constructor definition) to the parameter list.

In our case, in our MyManager::OnCKInit()

DECLARECTOR_0(__newMyClass)
DECLARECTOR_2(__newMyClass, int i, int f)

Bind Destructors

Before binding constructors of a struct/class, this struct/class must be already bound with the macro DECLAREOBJECTTYPE or DECLAREOBJECTTYPEALIAS.

Binding destructors is much like binding constructors. First, define a function that will call the destructor using the macro DECLAREDESTRUCTORFUNCTION with the struct/class name as parameter.
Then bind the function, its name will be the concatenation of "__dest" and the struct/class C++ name.

In our case :

// This macro defines the function __destMyClass
DECLAREDESTRUCTORFUNCTION(MyClass)
Then in our MyManager::OnCKInit()
DECLAREDESTRUCTOR(__destMyClass)

Bind Member Functions

DECLAREMETHOD[C]_%P(class,returnType,functionName, [paramDeclList] )
C : Add C to macro if the member function is constant.
P : number of parameters (0 to 8).
class : class of the member function.
returnType : return type of the function.
functionName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

Then in our MyManager::OnCKInit()
DECLAREMETHOD_0(MyClass,void,Nothing)
DECLAREMETHOD_2(MyClass,float,SetIAndF, int i, int f)

// Note that we use DECLAREMETHODC macro, because GetI is const
DECLAREMETHODC_0(MyClass,int,GetI, int i, int f)

Bind Member Operators

DECLAREOP[C]_%P(class,returnType,operatorName, [paramDeclList] )
C : Add C to macro if the member function is constant.
P : number of parameters (0 to 2).
class : class of the member function.
returnType : return type of the function.
operatorName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

NOTE: operator name must be : "operator" plus the operator.

In our MyManager::OnCKInit()
DECLAREOP_1(MyClass,MyClass,operator*,const MyClass &mc)

Bind Member Static Functions

DECLARESTATIC[C]_%P(class,returnType,functionName, [paramDeclList] )
C : Add C to macro if the member function is constant.
P : number of parameters (0 to 8).
class : class of the member function.
returnType : return type of the function.
functionName : function's name (it is not a string).
paramDeclList : list of parameter declaration.

Bind Members

DECLAREMEMBER(class,type,memberName)
class : class of the member function.
type : member's type (this type must be already bound).
functionName : function's name (it is not a string).
memberName : member's name.

In our MyManager::OnCKInit()
DECLAREMEMBER(MyClass,int,i)
DECLAREMEMBER(MyClass,float,f)
DECLAREMEMBER(MyClass,AnotherClass,ac) // Type AnotherClass must be already bound

Bind Enums

DECLAREENUM(enumName)
enumName : enum's name.

DECLAREENUMVALUE(enumName,valueName,value)
enumName : enum's name (const char *).
valueName : value's name.
value : int value.

Example:

// C/C++ enum declaration
enum CKSUPPORT
{
    CKSUPPORT_FRONT,
    CKSUPPORT_CENTER,
    CKSUPPORT_BACK
};
Then in our MyManager::OnCKInit()
DECLAREENUM("CKSUPPORT");
DECLAREENUMVALUE("CKSUPPORT", "CKSUPPORT_FRONT" , 0);
DECLAREENUMVALUE("CKSUPPORT", "CKSUPPORT_CENTER", 1);
DECLAREENUMVALUE("CKSUPPORT", "CKSUPPORT_BACK"  , 2);

Bind Constants

DECLARECONST(constName,constType,value)
constName : constant's name (const char *).
constType : constant's type (BIND_BOOL, BIND_CHAR, BIND_INT or BIND_FLOAT).
value : value.

Example in our MyManager::OnCKInit()
DECLARECONST("pi",BIND_FLOAT,3.14159)
DECLARECONST("one",BIND_INT,1)
DECLARECONST("WRONG",BIND_BOOL,FALSE)

Bind Managers

Binding a manager requires a combination of the binding techniques that we have just seen: binding class, member functions, etc...
In a VSL script, access to a manager is via the global variable bc:

// In a VSL script, we want to have access to RenderManager
RenderManager rm =  bc.GetRenderManager();

But if you write your own manager, you can not add a GetMyManager() function to the behavior context (bc)..
Therefore, you have to write (and bind) a function that will return your manager's GUID:

CKGUID GetMyManagerGuid()
{
    return MY_MANAGER_GUID;
}

Then, add a static function member Cast() to your manager as follows:

static MyManager * Cast(CKBaseManager* iM)
{
    return (MyManager *)iM;
}

Then you will be able to use GetManagerByGuid from bc, with your function returning your manager's GUID as the parameter:

MyManager mm = MyManager.Cast(bc.GetManagerByGuid(GetMyManagerGuid()));

Bind Function/Members Functions With Defaults Parameters

To bind functions, members functions, static functions and constructors with defaults parameters, you have to use special MACROs. These MACROs use the prefixes listed above (according to what you wish to bind), and you add the postfix _WITH_DEF_VALS.

An example with three functions:
void foo(int i = 0); // Default value is 0
void foo2(int i = 0, int j = 0); // Defaults values are 0
void foo3(int i, int j = 0); // Default value is 0
The bind code is:
DECLAREFUN_C_1_WITH_DEF_VALS(void, foo, int i, 0)
DECLAREFUN_C_2_WITH_DEF_VALS(void, foo2, int i, 0, int j, 0)
DECLAREFUN_C_2_WITH_DEF_VALS(void, foo3, int i, NODEFAULT, int j, 0)

In the last example, because function "foo3" had two prarameters, and only one had a default value, we still had to use MACRO DECLAREFUN_C_2_WITH_DEF_VALS. However, since the first parameter has no default value, we must use NODEFAULT as the default value.


Action Scripting Overview

Action Scripting in VSL

Overview

An Action is a specific type of VSL script that is created in the VSL Script Manager. Essentially a productivity enhancement used when authoring your Virtools composition, an Action's primary purpose is to be launched from the Action Manager or a user-defined keyboard shortcut in order to performs a predefined task on a selection or parameter.

For example, you could create an Action to be able to realign selected objects, change textures, move to a particular position, etc.

Creating an Action

Right Click on the Action folder in the VSL Scripts Window.

- New Folder: Creates a subfolder to help organize your actions.
- Add Action: Creates a file named "action.vsl" in the Action subdirectory. If you rename the action in the VSL Scripts Window, the corresponding VSL file is also renamed.
- Compile All: Compiles all Action scripts so that they are ready to open in the Action Manager.
- Load Action: Load or reload all actions present in Dev's /Actions directory. (.VSL files). Note: See the Action variables in the Variable Manager to automatically load all actions at start-up.

Scripting Actions in VSL

The main differences between action scripts and 'Run VSL' scripts are:
  • the use of global variable ac (action behavior) instead of bc
  • the use of extern global variables.
  • the impossibility of using global scripts

Like bc (in 'Run VSL' scripts), ac provides methods that allow you to create objects, manage attributes, print in the console etc.
But ac does have some specific members:

  • the mouse position
  • the selection list
  • the selected object
  • a boolean to update the selection

An extern (external) global variable is equivalent to a 'parameter input'. To define an external global variable, you have to add the keyword 'extern' before your global variable:

    extern int nbObjectToCreate;

    void main()
    {
        for (int i = 0; i < nbObjectToCreate; ++i)
        {
            //...
        }
    }
Then, before running the script, a window will popup to ask you to enter the value of the variable 'nbObjectToCreate'.

An extern global variable:

  • can be of any type managed by a Virtools parameter.
  • cannot be a VSL structure.
  • cannot be affected at the initialization
    extern Vector v1; // ok
    extern Matrix m1; // ok
    extern String s1; // ok

    struct twoInt {
        int a;
        int b;
    };

    extern twoInt ti; // error
    extern int nbObjectToCreate = 10; // error
Action scripts are able to use shared and static variables as usual, allowing you to share variables between 'Run VSL' and Actions, so it's an easy way to tune your VSL scripts!

Compiling

Actions cannot use global scripts, so when compiling actions, globals will not be compiled.
In the Variable Manager, under 'actions' there are 3 variables to customize actions script compilation:

Load At Startup
Allows you to specify if the actions must be loaded at Virtools Dev 's startup.
In any case you are still able to reload action with the 'Reload Actions' command (right click on actions tree root).

Compile At Load
Must the actions be compiled when loaded?

Include In Compile All
Are actions compiled when pressing the 'Compile All' button.

Note: If a non-compiled action is to be executed, VSL Manager will try to compile it before running it.

Working with the Action Manager

Once scripted, actions are ready to be imported into the Action Manager. The Action Manager allow you to bind scripts to buttons, you can also add a description of your action in your script with the keyword 'description' like this :

// description : This is the action description
The description text will be printed in the 'Description' column and must be in one line.

Debugging

A action script can be debugged just like any other VSL script: i.e. you can place breakpoints, see, change the values of your variables, use the call stack.

Limitations

  • the impossibility of using global scripts.
  • the impossibility of choosing the path of your actions scripts.
  • you can't save action's breakpoints.

See also: Action Scripting Example


Learn VSL Action Scripting - Aligning Object

Learn VSL Action Scripting - Aligning Objects

This first exercise shows you how to create, write, compile, and run a VSL Actions script. We presume that you have already covered the foundations of VSL.

  1. Open the VSL Script Manager, rigth clicks on 'Actions' and select "Add Action". You have just created a file on your disk in "($VirtoolsFolder)\Actions" named Action.vsl .

  2. Now copy the code above and compile it the same way that you would with a 'Run VSL' script.
    // Description : Align all selected 3D entities on the first selected entity on a given axis

// These external global variables are the parameters
// that user will set when the action will be activated
extern CKAXIS 		axis;
extern CKSUPPORT 	support;

float ComputeAlign(Entity3D iEnt)
{
    //  Get the 3D entity's bounding box
    Bbox box = iEnt.GetBoundingBox(FALSE);

    //  Return the alignement value
    switch (support) {
        case CKSUPPORT_FRONT:
        return box.Max[axis];
        break;

        case CKSUPPORT_CENTER:
        return (box.Max[axis] + box.Min[axis])/2;
        break;

        case CKSUPPORT_BACK:
        return box.Min[axis];
        break;
    }
    return 0;
}

void main()
{
    BOOL first = TRUE;

    float align;
    Vector trans(0);

    // Get the number of objects in the selection
    int count = ac.selection.Size();
    for (int i=0; i < count; ++i) {

        // Try to cast the selected object i in a 3D entity
        Entity3D ent = Entity3D.Cast(ac.selection[i]);

        // If object is not a 3D entity we skip its computation
        if (!ent) continue;

        if (first) { // First object
            first = FALSE;

            // All others object were be aligned on the first
            align = ComputeAlign(ent);

        } else { // Subsequent objects

            // Find the align value of this object
            trans[axis] = align - ComputeAlign(ent);;

            // Translate the object of the align  result difference
            ent.Translate(trans,NULL,0);
        }
    }
}
  3. Once the Action is compiled, open it in the Action Manager (through the contextual menu) and bind it to a keyboard shortcut.
  4. Then select 3D entities in your 3D Layout and test out the keyboard shortcut. You should get a dialog box that asks which axis to align to, as well a whether to align the front, top or back of the object.


VSL FAQs

Introduction

This FAQ section is work in progress. Please send any questions you think should be on this page to doc@virtools.com. Thank-you!

VSL - Frequently Asked Questions

How can I add arguments (pIns) or any inputs or outputs to my Run VSL BB ?
You have to open VSL Script Manager, click on your VSL BB script on the left and add/remove inputs/outputs by left clicking on bIn, bOut, pIn or pOut in the tree in the right window.

Can I write to or read from disk?
No.

Is there a debugger for VSL ?
Yes a debugger exist. To use it, you have to compile your script in Debug mode. You can Add/Remove breakpoints with F9.

How do I know what functions and class I can access ? Do I have to use "#include" statements in my VSL scripts ?
Check binding tables. No need for #includes statements.

How do I store/exchange my VSL scripts ?
You can save your VSL scripts by saving your BB as an NMS. All global scripts will be saved too.

What is Debug Check, and why is it recommended ?
- It's in variables manager, ensures that objects are not NULL, that array index are in the range.... (Otherwise this can cause VSL to fail, and crash Dev !)

Is a "Run VSL" script dependend on the virtools behavior timing and priority?
A "Run VSL" script is executed when the BB containing the script is activated, so yes it depends on the virtools behavior engine (and timing)

VSL Script Questions

Can I use preprocessing directives as "#define", "#ifdef" ... just like in C/C++ ?
No.

Do I have to manually set bIns to false as I would in C++ ?
No. BB bIn are automatically set to false after the script execution .

How do I include comments ?
As in C++ : prefix the comment line with // or insert the comment between /* and */ .

Example :

// It is a commentary
/* It is a second
   commentary */

What is word bc in a VSL Script ?
bc = behavioral context. bc is a global variable. You can use it only in Run VSL script (not global one).
From it you can create, copy CKOBjects, send messages, deals with attributes get the delta time...

How do I create CKObjects ?
You have to use global variable bc (behavior context) :

Entity3D entity = Entity3D.Cast(bc.CreateObject(CKCID_3DENTITY, "EntityName", TRUE, FALSE));
Light light = Light.Cast(bc.CreateObject(CKCID_LIGHT, "LightName", TRUE, FALSE));
// ...

You can also used specific member functions :

Entity3D entity = bc.CreateEntity3D("EntityName", TRUE, FALSE);
Light light = bc.CreateLight("LightName", TRUE, FALSE);
// ...

How do I profile my VSL scripts ?
You can use UserProfileStart and UserProfileEnd on bc objects and go on the "Details" section of the regular profiler:

bc.UserProfileStart(0);
// Profile 0 will profile code here.
// ...
bc.UserProfileEnd(0);

bc.UserProfileStart(1);
// Profile 1 will profile code here.
// ...
bc.UserProfileEnd(1);

// ...

Does the "shared" or "static" keywords mean "global"
No, "shared" and "static" keywords don't meen "global", but only global variables can be "shared" or "static".

How do I manipulate GUIDs ?
Because in the Virtools SDK, GUIDs a defined with MACROS you can't use them the same way in VSL.
You have to use GetGUID function.

// We want to use the GUID associated with vector
// In C++ with Virtools SDK, we should use CKPGUID_VECTOR
// In VSL we have to use GetGUID like this :
GUID guidVector = GetGUID(GUID_VECTOR);


VSL

VSL <- SDK Binding Tables

The VSL <- SDK Binding Tables list what elements from the Virtools SDK are available in VSL (what elements have been "bound").

  • Global Functions
  • Classes and Methods
  • Enumerations

    • Comments


VSL

VSL <- SDK Binding Tables - Classes and Methods

Index

Class | Parents
ActionContext | ScriptContext
Animation | SceneObject
Array | BeObject
ArrayString |
BaseString |
Bbox |
BeObject | SceneObject
BehaviorContext | ScriptContext
BitArray |
BitmapData |
Camera | Entity3D
Character | Entity3D
CloudAttribute |
CloudIterator |
CloudRenderGroup |
CollisionManager |
Color |
Curve | Entity3D
Curve2D |
Curve2DPoint |
CurvePoint | Entity3D
Entity2D | RenderObject
Entity3D | RenderObject
FloatArray |
FloorManager |
Frustum |
GUID |
Grid | Entity3D
Group | BeObject
ImpactDesc |
InputManager |
IntArray |
IntersectionDesc |
Layer | Object
Light | Entity3D
Material | BeObject
Matrix |
Mesh | BeObject
OBB |
Object |
ObjectArray |
PatchMesh | Mesh
Plane |
PointCloud | Entity3D
Quaternion |
Ray |
Rect |
RenderContext | Object
RenderManager |
RenderObject | BeObject
Scene | BeObject
ScriptContext |
Sphere |
Sprite | Entity2D
Sprite3D | Entity3D
String | BaseString
StringTokenizer |
Texture | BeObject, BitmapData
Timer |
Vector |
Vector2D |
Vector2DArray |
Vector4 | Vector
Vector4Array |
VectorArray |
WaveFormat |
WaveSound | BeObject
WebServerManager |

Classes

ActionContext

Parents Classes

    ScriptContext

Members

    mouse (Vector2D)
    updateselection (bool)
    selected (Object)
    selection (ObjectArray)

Animation

Parents Classes

    SceneObject

Methods

Return | Function | Parameters
bool | CanBeInterrupt |
void | CenterAnimation | fram (float)
Animation | CreateMergedAnimation | anim2 (Animation) dynamic = false (bool)
float | CreateTransition | in (Animation) out (Animation) OutTransitionMode (int) length = 6.000000 (float) FrameTo = 0.000000 (float)
bool | DoesCharacterTakeOrientation |
Character | GetCharacter |
int | GetFlags |
float | GetFrame |
float | GetLength |
float | GetLinkedFrameRate |
float | GetMergeFactor |
float | GetNextFrame | delta_t (float)
Entity3D | GetRootEntity |
CK_SECONDARYANIMATION_FLAGS | GetSecondaryAnimationMode |
float | GetStep |
CK_ANIMATION_TRANSITION_MODE | GetTransitionMode |
bool | IsLinkedToFrameRate |
bool | IsMerged |
void | LinkToFrameRate | link (bool) fps = 30.000000 (float)
void | SetCanBeInterrupt | can = true (bool)
void | SetCharacterOrientation | orient = true (bool)
void | SetCurrentStep | Step (float)
void | SetFlags | flags (int)
void | SetFrame | frame (float)
void | SetLength | nbframe (float)
void | SetMergeFactor | factor (float)
void | SetSecondaryAnimationMode | mode (CK_SECONDARYANIMATION_FLAGS)
void | SetStep | step (float)
void | SetTransitionMode | mode (CK_ANIMATION_TRANSITION_MODE)

Array

Parents Classes

    BeObject

Methods

Return | Function | Parameters
void | AddRow |
void | CheckPostDeletion |
void | CheckPreDeletion |
void | Clear | Params = true (bool)
CK_CLASSID | GetClassID |
int | GetColumnCount |
str | GetColumnName | c (int)
GUID | GetColumnParameterGuid | c (int)
CK_ARRAYTYPE | GetColumnType | c (int)
int | GetElement | i (int) c (int)
Object | GetElementObject | i (int) c (int)
int | GetElementStringValue | i (int) c (int) svalue (str)
bool | GetElementValue | i (int) c (int) value (ptr)
bool | GetHighest | c (int) row (int)
int | GetKeyColumn |
bool | GetLowest | c (int) row (int)
int | GetMemoryOccupation |
bool | GetNearest | c (int) value (ptr) row (int)
int | GetRowCount |
int | GetStringValue | key (int) c (int) svalue (str)
void | InsertColumn | cdest (int) type (CK_ARRAYTYPE) name (str) paramguid (GUID)
int | IsObjectUsed | o (Object) cid (CK_CLASSID)
bool | LoadElements | string (str) append (bool) column (int)
void | MoveColumn | csrc (int) cdest (int)
void | MoveRow | rsrc (int) rdst (int)
bool | PasteShortcut | i (int) c (int) pout (Parameter)
void | PostLoad |
int | Product | c (int)
void | RandomShuffle |
void | RemoveColumn | c (int)
void | RemoveRow | n (int)
ParameterOut | RemoveShortcut | i (int) c (int)
void | Reverse |
void | SetColumnName | c (int) name (str)
void | SetColumnType | c (int) type (CK_ARRAYTYPE) paramguid (GUID)
bool | SetElementObject | i (int) c (int) object (Object)
bool | SetElementStringValue | i (int) c (int) svalue (str)
bool | SetElementValue | i (int) c (int) value (ptr) size = 0 (int)
bool | SetElementValueFromParameter | i (int) c (int) pout (Parameter)
void | SetKeyColumn | c (int)
void | Sort | c (int) ascending (bool)
int | Sum | c (int)
void | SwapRows | i1 (int) i2 (int)
void | Unique | c (int)
bool | WriteElements | string (str) column (int) number (int) iAppend = false (bool)

ArrayString

Methods

Return | Function | Parameters
ArrayString | = | iArray (ArrayString)
void | Clear |
void | PopBack |
void | PushBack | iValue (String)
void | PushFront | iValue (String)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
String | [] | iPos (int)

BaseString

Methods

Return | Function | Parameters
str | CStr |
int | Length |
float | ToFloat |
int | ToInt |
char | [] | i (int)
char | [] | i (int)

Bbox

Members

    Max (Vector)
    Min (Vector)

Methods

Return | Function | Parameters
int | Classify | box2 (Bbox) pt (Vector)
Vector | GetCenter |
Vector | GetHalfSize |
Vector | GetSize |
void | Intersect | v (Bbox)
bool | IsBoxInside | b (Bbox)
bool | IsValid |
void | Merge | v (Bbox)
void | Merge | v (Vector)
void | Reset |
void | SetCenter | center (Vector) halfsize (Vector)
void | SetCorners | min (Vector) max (Vector)
void | SetDimension | position (Vector) size (Vector)
void | TransformFrom | sbox (Bbox) Mat (Matrix)
void | TransformTo | pts (Vector) Mat (Matrix)
bool | VectorIn | v (Vector)

BeObject

Parents Classes

    SceneObject

Methods

Return | Function | Parameters
int | CallBehaviorCallbackFunction | Message (int) behguid = 0 (GUID)
void | ExecuteBehaviors | delta (float)
int | GetAttributeCount |
int | GetAttributeType | index (int)
CK_CLASSID | GetClassID |
float | GetLastExecutionTime |
int | GetLastFrameMessageCount |
int | GetMemoryOccupation |
int | GetPriority |
int | GetScriptCount |
bool | IsInGroup | group (Group)
bool | IsObjectUsed | obj (Object) cid (CK_CLASSID)
bool | IsWaitingForMessages |
void | RemoveAllAttributes |
int | RemoveAllScripts |
void | SetAsWaitingForMessages | wait = true (bool)
void | SetPriority | priority (int)

BehaviorContext

Parents Classes

    ScriptContext

Methods

Return | Function | Parameters
BeObject | GetOwner |
BeObject | GetTarget |
bool | IsRuntimeMode |
void | LaunchScene | scene = 0 (Scene) activity = 0 (CK_SCENEOBJECTACTIVITY_FLAGS) reset = 0 (CK_SCENEOBJECTRESET_FLAGS)
void | SendMessage | iMessage (Message) iDest (BeObject)
void | SendMessage | iMessage (str) iDest (BeObject)

BitArray

Methods

Return | Function | Parameters
BitArray | -= | a (BitArray)
BitArray | = | a (BitArray)
void | And | a (BitArray)
void | AppendBits | n (int) v (int) bitcount (int)
int | BitSet |
bool | CheckCommon | a (BitArray)
void | CheckSize | n (int)
void | Clear |
void | Fill |
int | GetMemoryOccupation | addstatic = false (bool)
int | GetSetBitPosition | n (int)
int | GetUnsetBitPosition | n (int)
void | Invert |
int | IsSet | n (int)
void | Or | a (BitArray)
void | Set | n (int)
int | Size |
int | TestSet | n (int)
int | TestUnset | n (int)
void | Unset | n (int)
void | XOr | a (BitArray)
int | [] | n (int)

BitmapData

Members

    m_Width (int)
    m_Height (int)
    m_CurrentSlot (int)
    m_PickThreshold (int)
    m_BitmapFlags (int)
    m_TransColor (int)
    m_SaveOptions (CK_BITMAP_SAVEOPTIONS)

Methods

Return | Function | Parameters
bool | CreateImage | Width (int) Height (int) BPP = 32 (int) Slot = 0 (int) ImagePointer = 0 (ptr)
int | GetCurrentSlot |
VX_PIXELFORMAT | GetDesiredVideoFormat |
int | GetHeight |
str | GetMovieFileName |
int | GetPickThreshold |
int | GetPixel | x (int) y (int) slot = -1 (int)
CK_BITMAP_SAVEOPTIONS | GetSaveOptions |
int | GetSlotCount |
str | GetSlotFileName | Slot (int)
CK_BITMAP_SYSTEMCACHING | GetSystemCaching |
int | GetTransparentColor |
int | GetWidth |
bool | IsCubeMap |
bool | IsTransparent |
bool | LoadMovieFile | Name (String)
bool | LoadSlotImage | Name (String) Slot = 0 (int)
char | LockSurfacePtr | Slot = -1 (int)
bool | ReleaseAllSlots |
bool | ReleaseSlot | Slot (int)
bool | ReleaseSurfacePtr | Slot = -1 (int)
bool | ResizeImages | Width (int) Height (int)
bool | SaveImage | Name (str) Slot = 0 (int) CKUseFormat = false (bool)
bool | SaveImageAlpha | Name (str) Slot = 0 (int)
void | SetCubeMap | CubeMap (bool)
bool | SetCurrentSlot | Slot (int)
void | SetDesiredVideoFormat | pf (VX_PIXELFORMAT)
void | SetPickThreshold | pt (int)
bool | SetPixel | x (int) y (int) col (int) slot = -1 (int)
void | SetSaveOptions | Options (CK_BITMAP_SAVEOPTIONS)
bool | SetSlotCount | Count (int)
bool | SetSlotFileName | Slot (int) Filename (str)
void | SetSystemCaching | iOptions (CK_BITMAP_SYSTEMCACHING)
void | SetTransparent | Transparency (bool)
void | SetTransparentColor | Color (int)
bool | ToRestore |

Camera

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
void | ComputeProjectionMatrix | mat (Matrix)
void | GetAspectRatio | width (int) height (int)
float | GetBackPlane |
float | GetFov |
float | GetFrontPlane |
float | GetOrthographicZoom |
int | GetProjectionType |
Entity3D | GetTarget |
void | ResetRoll |
void | Roll | angle (float)
void | SetAspectRatio | width (int) height (int)
void | SetBackPlane | back (float)
void | SetFov | fov (float)
void | SetFrontPlane | front (float)
void | SetOrthographicZoom | zoom (float)
void | SetProjectionType | proj (int)
void | SetTarget | target (Entity3D)

Character

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
int | AddAnimation | anim (Animation)
int | AddBodyPart | part (BodyPart)
void | AlignCharacterWithRootPosition |
void | FlushSecondaryAnimations |
Animation | GetActiveAnimation |
Animation | GetAnimation | index (int)
int | GetAnimationCount |
float | GetAnimationLevelOfDetail |
BodyPart | GetBodyPart | index (int)
int | GetBodyPartCount |
void | GetEstimatedVelocity | deltat (float) velocity (Vector)
Entity3D | GetFloorReferenceObject |
Animation | GetNextActiveAnimation |
BodyPart | GetRootBodyPart |
Animation | GetSecondaryAnimation | index (int)
int | GetSecondaryAnimationsCount |
Animation | GetWarper |
void | GetWarperParameters | TransitionMode (int) AnimSrc (Animation) FrameSrc (float) AnimDest (Animation) FrameDest (float)
bool | IsAutomaticProcess |
int | PlaySecondaryAnimation | anim (Animation) StartingFrame = 0.000000 (float) PlayFlags = 1082130432 (CK_SECONDARYANIMATION_FLAGS) warplength = 5.000000 (float) LoopCount = 0 (int)
void | ProcessAnimation | deltat = 1.000000 (float)
int | RemoveAnimation | anim (Animation)
int | RemoveBodyPart | part (BodyPart)
int | SetActiveAnimation | anim (Animation)
void | SetAnimationLevelOfDetail | LOD (float)
void | SetAutomaticProcess | process = true (bool)
void | SetFloorReferenceObject | FloorRef (Entity3D)
int | SetNextActiveAnimation | anim (Animation) transitionmode (int) warplength = 0.000000 (float)
int | SetRootBodyPart | part (BodyPart)
int | StopSecondaryAnimation | anim (Animation) warp = false (bool) warplength = 5.000000 (float)
int | StopSecondaryAnimation | anim (Animation) warplength = 5.000000 (float)

CloudAttribute

Members

    ValueType (int)
    Name (String)
    EnumDescription (String)
    BitsPerValue (int)
    ForAllPoints (bool)

CloudIterator

Methods

Return | Function | Parameters
void | GetBox | oBox (Bbox)
int | GetChildrenCount |
int | GetCurrentPointIndex |
Vector | GetCurrentPointPosition |
Vector | GetCurrentPointRealPosition |
void | GetRealBox | oBox (Bbox)
bool | IsChildHere | iBranchIndex (int)
bool | IsLeaf |
bool | IsNode |
bool | NextNode |
bool | NextPoint |
bool | ToChildByBranch | iBranchIndex (int)
bool | ToChildByIndex | iChildIndex (int)
bool | ToParent |

CloudRenderGroup

Members

    Name (String)
    Material (Material)
    Visible (bool)
    UseSpriteRendering (bool)
    SpriteSize (float)
    UseMaterialColor (bool)

CollisionManager

Methods

Return | Function | Parameters
void | AddObstacle | ent (Entity3D) moving = false (bool) precision = 1065353216 (CK_GEOMETRICPRECISION) hiera = false (bool)
int | AddObstaclesByName | level (Level) substring (str) moving = false (bool) precision = 1065353216 (CK_GEOMETRICPRECISION) hiera = false (bool)
bool | BoxBoxIntersection | ent1 (Entity3D) hiera1 (bool) local1 (bool) ent2 (Entity3D) hiera2 (bool) local2 (bool)
bool | BoxFaceIntersection | ent1 (Entity3D) hiera1 (bool) local1 (bool) ent2 (Entity3D)
bool | DetectCollision | ent (Entity3D) precis_level (CK_GEOMETRICPRECISION) replacementPrecision (int) detectionPrecision (int) inmpactFlags (CK_IMPACTINFO) imp (ImpactDesc)
bool | FaceFaceIntersection | ent1 (Entity3D) ent2 (Entity3D)
Entity3D | GetFixedObstacle | pos (int) level = false (bool)
int | GetFixedObstacleCount | level = false (bool)
Entity3D | GetMovingObstacle | pos (int) level = false (bool)
int | GetMovingObstacleCount | level = false (bool)
Entity3D | GetObstacle | pos (int) level = false (bool)
int | GetObstacleCount | level = false (bool)
bool | IsHierarchyInCollisionWithHierarchy | ent (Entity3D) precis_level1 (CK_GEOMETRICPRECISION) ent2 (Entity3D) precis_level2 (CK_GEOMETRICPRECISION) sub (Entity3D) subob (Entity3D)
bool | IsInCollision | ent (Entity3D) precis_level1 (CK_GEOMETRICPRECISION) ent2 (Entity3D) precis_level2 (CK_GEOMETRICPRECISION)
Entity3D | IsInCollisionWithHierarchy | ent (Entity3D) precis_level1 (CK_GEOMETRICPRECISION) ent2 (Entity3D) precis_level2 (CK_GEOMETRICPRECISION)
bool | IsObstacle | ent (Entity3D) moving = false (bool)
bool | ObstacleBetween | pos (Vector) endpos (Vector) width (float) height (float)
Entity3D | ObstacleBetween | pos (Vector) endpos (Vector) iFace = true (bool) iFirstContact = false (bool) iIgnoreAlpha = false (bool) oDesc = 0 (IntersectionDesc)
void | RemoveAllObstacles | level = true (bool)
void | RemoveObstacle | ent (Entity3D)

Color

Members

    r (float)
    g (float)
    b (float)
    a (float)

Methods

Return | Function | Parameters
Color | *= | v (Color)
Color | *= | s (float)
Color | += | v (Color)
Color | -= | v (Color)
Color | /= | v (Color)
Color | /= | s (float)
void | Check |
void | Clear |
int | GetRGB |
int | GetRGBA |
float | GetSquareDistance | color (Color)
void | Set | _r (float) _g (float) _b (float) _a (float)
void | Set | _r (float) _g (float) _b (float)
void | Set | _r (float)
void | Set | col (int)
void | Set | _r (int) _g (int) _b (int) _a (int)
void | Set | _r (int) _g (int) _b (int)

Curve

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
int | AddControlPoint | pt (CurvePoint)
void | Close |
int | CreateLineMesh |
Color | GetColor |
CurvePoint | GetControlPoint | pos (int)
int | GetControlPointCount |
float | GetFittingCoeff |
float | GetLength |
int | GetLocalPos | step (float) pos (Vector) dir = 0 (Vector)
int | GetPos | step (float) pos (Vector) dir = 0 (Vector)
int | GetStepCount |
int | GetTangents | index (int) in (Vector) out (Vector)
int | GetTangents | pt (CurvePoint) in (Vector) out (Vector)
int | InsertControlPoint | prev (CurvePoint) pt (CurvePoint)
bool | IsOpen |
void | Open |
int | RemoveAllControlPoints |
int | RemoveControlPoint | pt (CurvePoint) removeall = false (bool)
void | SetColor | Color (Color)
void | SetFittingCoeff | fit (float)
int | SetStepCount | steps (int)
int | SetTangents | index (int) in (Vector) out (Vector)
int | SetTangents | pt (CurvePoint) in (Vector) out (Vector)

Curve2D

Methods

Return | Function | Parameters
void | AddControlPoint | iPosition (Vector2D)
void | DeleteControlPoint | iPoint (Curve2DPoint)
Curve2DPoint | GetControlPoint | iIndex (int)
int | GetControlPointCount |
float | GetLength |
int | GetPos | step (float) pos (Vector2D)
float | GetY | X (float)

Curve2DPoint

Methods

Return | Function | Parameters
float | GetBias |
float | GetContinuity |
Curve2D | GetCurve |
Vector2D | GetInTangent |
float | GetLength |
Vector2D | GetOutTangent |
Vector2D | GetPosition |
float | GetTension |
bool | IsLinear |
bool | IsTCB |
void | SetBias | iBias (float)
void | SetContinuity | iBias (float)
void | SetInTangent | iInTangent (Vector2D)
void | SetLinear | iLinear (bool)
void | SetOutTangent | iOutTangent (Vector2D)
void | SetPosition | iPosition (Vector2D)
void | SetTension | iBias (float)
void | UseTCB | iTCB (bool)

CurvePoint

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
float | GetBias |
float | GetContinuity |
Curve | GetCurve |
float | GetLength |
void | GetTangents | in (Vector) out (Vector)
float | GetTension |
bool | IsLinear |
bool | IsTCB |
void | NotifyUpdate |
void | SetBias | b (float)
void | SetContinuity | c (float)
void | SetLinear | linear = false (bool)
void | SetTangents | in (Vector) out (Vector)
void | SetTension | t (float)
void | UseTCB | use = true (bool)

Entity2D

Parents Classes

    RenderObject

Methods

Return | Function | Parameters
int | Draw | context (RenderContext)
void | EnableClipToCamera | Clip = true (bool)
void | EnableRatioOffset | Ratio = true (bool)
Entity2D | GetChild | i (int)
int | GetChildrenCount |
int | GetFlags |
int | GetHomogeneousRect | rect (Rect)
Material | GetMaterial |
Entity2D | GetParent |
int | GetPosition | vect (Vector2D) hom = false (bool) ref = 0 (Entity2D)
void | GetRect | rect (Rect)
int | GetSize | vect (Vector2D) hom = false (bool)
void | GetSourceRect | rect (Rect)
Entity2D | HierarchyParser | current (Entity2D)
bool | IsBackground |
bool | IsClipToParent |
bool | IsClippedToCamera |
bool | IsHomogeneousCoordinates |
bool | IsPickable |
bool | IsRatioOffset |
bool | IsUsingSourceRect |
void | ModifyFlags | add (int) remove = 0 (int)
int | Render | context (RenderContext)
void | RestoreInitialSize |
void | SetBackground | back = true (bool)
void | SetClipToParent | clip = false (bool)
void | SetFlags | Flags (int)
void | SetHomogeneousCoordinates | Coord = true (bool)
int | SetHomogeneousRect | rect (Rect) KeepChildren = false (bool)
void | SetMaterial | mat (Material)
bool | SetParent | parent (Entity2D)
void | SetPickable | Pick = true (bool)
void | SetPosition | vect (Vector2D) hom = false (bool) KeepChildren = false (bool) ref = 0 (Entity2D)
void | SetRect | rect (Rect) KeepChildren = false (bool)
void | SetSize | vect (Vector2D) hom = false (bool) KeepChildren = false (bool)
void | SetSourceRect | rect (Rect)
void | UseSourceRect | Use = true (bool)

Entity3D

Parents Classes

    RenderObject

Methods

Return | Function | Parameters
bool | AddChild | Child (Entity3D) KeepWorldPos = true (bool)
bool | AddChildren | Children (ObjectArray) KeepWorldPos = true (bool)
int | AddMesh | mesh (Mesh)
void | AddScale | Scale (Vector) KeepChildren = false (bool) Local = true (bool)
void | AddScale | X (float) Y (float) Z (float) KeepChildren = false (bool) Local = true (bool)
bool | AreAnimationIgnored |
void | ChangeReferential | Ref = 0 (Entity3D)
bool | CheckIfSameKindOfHierarchy | Mov (Entity3D) SameOrder = false (bool)
bool | ConstructLocalMatrix | Pos (Vector) Scale (Vector) Quat (Quaternion)
bool | ConstructLocalMatrixEx | Pos (Vector) Scale (Vector) Quat (Quaternion) Shear (Quaternion) Sign (float)
bool | ConstructWorldMatrix | Pos (Vector) Scale (Vector) Quat (Quaternion)
bool | ConstructWorldMatrixEx | Pos (Vector) Scale (Vector) Quat (Quaternion) Shear (Quaternion) Sign (float)
bool | DestroySkin |
bool | GetBaryCenter | Pos (Vector)
Bbox | GetBoundingBox | Local = false (bool)
Entity3D | GetChild | pos (int)
int | GetChildrenCount |
Mesh | GetCurrentMesh |
int | GetFlags |
Bbox | GetHierarchicalBox | Local = false (bool)
Matrix | GetInverseWorldMatrix |
Matrix | GetLastFrameMatrix |
Matrix | GetLocalMatrix |
Mesh | GetMesh | pos (int)
int | GetMeshCount |
int | GetMoveableFlags |
int | GetObjectAnimationCount |
void | GetOrientation | Dir (Vector) Up (Vector) Right = 0 (Vector) Ref = 0 (Entity3D)
Entity3D | GetParent |
void | GetPosition | Pos (Vector) Ref = 0 (Entity3D)
void | GetQuaternion | Quat (Quaternion) Ref = 0 (Entity3D)
float | GetRadius |
Place | GetReferencePlace |
void | GetRenderExtents | rect (Rect)
void | GetScale | Scale (Vector) Local = true (bool)
Matrix | GetWorldMatrix |
Entity3D | HierarchyParser | current (Entity3D)
void | IgnoreAnimations | ignore = true (bool)
void | InverseTransform | Dest (Vector) Src (Vector) Ref = 0 (Entity3D)
void | InverseTransformMany | Dest (Vector) Src (Vector) count (int) Ref = 0 (Entity3D)
void | InverseTransformVector | Dest (Vector) Src (Vector) Ref = 0 (Entity3D)
bool | IsAllInsideFrustrum |
bool | IsAllOutsideFrustrum |
bool | IsInViewFrustrum | Dev (RenderContext) Flags = 0 (int)
bool | IsInViewFrustrumHierarchic | Dev (RenderContext)
bool | IsPickable |
void | LookAt | Pos (Vector) Ref = 0 (Entity3D) KeepChildren = false (bool)
int | ModifyMoveableFlags | Add (int) Remove (int)
int | RayIntersection | Pos1 (Vector) Pos2 (Vector) Desc (IntersectionDesc) Ref = 0 (Entity3D) iOptions = 0 (CK_RAYINTERSECTION)
bool | RemoveChild | Mov (Entity3D)
int | RemoveMesh | mesh (Mesh)
bool | Render | Dev (RenderContext) Flags = 0 (int)
void | Rotate | Axis (Vector) Angle (float) Ref = 0 (Entity3D) KeepChildren = false (bool)
void | Rotate | X (float) Y (float) Z (float) Angle (float) Ref = 0 (Entity3D) KeepChildren = false (bool)
bool | SetBoundingBox | BBox (Bbox) Local = false (bool)
Mesh | SetCurrentMesh | m (Mesh) add_if_not_here = true (bool)
void | SetFlags | Flags (int)
void | SetLocalMatrix | Mat (Matrix) KeepChildren = false (bool)
void | SetMoveableFlags | flags (int)
void | SetOrientation | Dir (Vector) Up (Vector) Right = 0 (Vector) Ref = 0 (Entity3D) KeepChildren = false (bool)
bool | SetParent | Parent (Entity3D) KeepWorldPos = true (bool)
void | SetPickable | Pick = true (bool)
void | SetPosition | Pos (Vector) Ref = 0 (Entity3D) KeepChildren = false (bool)
void | SetPosition | X (float) Y (float) Z (float) Ref = 0 (Entity3D) KeepChildren = false (bool)
void | SetQuaternion | Quat (Quaternion) Ref = 0 (Entity3D) KeepChildren = false (bool) KeepScale = false (bool)
void | SetRenderAsTransparent | Trans = true (bool)
void | SetScale | Scale (Vector) KeepChildren = false (bool) Local = true (bool)
void | SetScale | X (float) Y (float) Z (float) KeepChildren = false (bool) Local = true (bool)
void | SetWorldMatrix | Mat (Matrix) KeepChildren = false (bool)
void | Transform | Dest (Vector) Src (Vector) Ref = 0 (Entity3D)
void | TransformMany | Dest (Vector) Src (Vector) count (int) Ref = 0 (Entity3D)
void | TransformVector | Dest (Vector) Src (Vector) Ref = 0 (Entity3D)
void | Translate | Vect (Vector) Ref = 0 (Entity3D) KeepChildren = false (bool)
void | Translate | X (float) Y (float) Z (float) Ref = 0 (Entity3D) KeepChildren = false (bool)
bool | UpdateSkin |

FloatArray

Methods

Return | Function | Parameters
FloatArray | += | iArray (FloatArray)
FloatArray | = | iArray (FloatArray)
void | Clear |
bool | Erase | iValue (float)
bool | EraseAt | iPos (int)
bool | IsHere | iValue (float)
float | PopBack |
void | PushBack | iValue (float)
void | PushFront | iValue (float)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
float | [] | iPos (int)

FloorManager

Methods

Return | Function | Parameters
void | AddFloorObject | ent (Entity3D) geo (CK_FLOORGEOMETRY) moving (bool) type (int) hiera (bool) first (bool)
int | AddFloorObjectsByName | level (Level) floorname (str) geo (CK_FLOORGEOMETRY) moving (bool) type (int) hiera (bool) first (bool)
bool | ConstrainToFloor | iPosition (Vector) iRadius (float) oPosition (Vector) iExcludeAttribute = -1 (Attribute)
bool | ConstrainToFloor | iOldPosition (Vector) iPosition (Vector) iRadius (float) oPosition (Vector) iExcludeAttribute = -1 (Attribute)
Entity3D | GetFloorObject | pos (int)
int | GetFloorObjectCount |
float | GetLimitAngle |
CK_FLOORNEAREST | GetNearestFloor | iPosition (Vector) oFloor (Entity3D) oFaceIndex = 0 (int) oNormal = 0 (Vector) oDistance = 0.000000 (float) iExcludeFloor = 0 (Entity3D)
void | RemoveFloorObject | ent (Entity3D)
void | SetLimitAngle | angle (float)

Frustum

Methods

Return | Function | Parameters
float | Classify | v (Bbox)
float | Classify | b (Bbox) mat (Matrix)
void | ComputeVertices | vertices (Vector)
Plane | GetBottomPlane |
float | GetDMax |
float | GetDMin |
float | GetDRatio |
Vector | GetDir |
Plane | GetFarPlane |
Plane | GetLeftPlane |
Plane | GetNearPlane |
Vector | GetOrigin |
float | GetRBound |
float | GetRF |
Vector | GetRight |
Plane | GetRightPlane |
float | GetUBound |
float | GetUF |
Vector | GetUp |
Plane | GetUpPlane |
bool | IsInside | v (Vector)
void | Transform | invworldmat (Matrix)
void | Update |

GUID

Members

    d1 (int)
    d2 (int)

Grid

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
int | AddClassification | classification (int)
int | AddClassification | ClassificationName (str)
Layer | AddLayer | type (int) Format = 0 (int)
Layer | AddLayer | TypeName = (null) (str) Format = 0 (int)
void | ConstructMeshTexture | opacity = 0.000000 (float)
void | DestroyMeshTexture |
float | Get2dCoordsFrom3dPos | pos3d (Vector) x (int) y (int)
void | Get3dPosFrom2dCoords | pos3d (Vector) x (int) y (int)
int | GetGridPriority |
float | GetHeightValidity |
Layer | GetLayer | type (int)
Layer | GetLayer | TypeName (str)
Layer | GetLayerByIndex | type (int)
int | GetLayerCount |
int | GetLength |
CK_GRIDORIENTATION | GetOrientationMode |
int | GetWidth |
bool | HasCompatibleClass | ent (Entity3D)
bool | IsActive |
int | RemoveAllLayers |
int | RemoveClassification | classification (int)
int | RemoveClassification | ClassificationName (str)
int | RemoveLayer | type (int)
int | RemoveLayer | TypeName (str)
void | SetDimensions | width (int) length (int) sizeX (float) sizeY (float)
void | SetGridPriority | Priority (int)
void | SetHeightValidity | HeightValidity (float)
void | SetOrientationMode | orimode (CK_GRIDORIENTATION)

Group

Parents Classes

    BeObject

Methods

Return | Function | Parameters
int | AddObject | o (BeObject)
int | AddObjectFront | o (BeObject)
int | CanBeHide |
void | CheckPreDeletion |
void | Clear |
CK_CLASSID | GetClassID |
CK_CLASSID | GetCommonClassID |
int | GetMemoryOccupation |
BeObject | GetObject | pos (int)
int | GetObjectCount |
int | InsertObjectAt | o (BeObject) pos (int)
int | IsObjectUsed | o (Object) cid (CK_CLASSID)
void | MoveObjectDown | o (BeObject)
void | MoveObjectUp | o (BeObject)
void | PostLoad |
void | PreDelete |
BeObject | RemoveObject | pos (int)
void | RemoveObject | obj (BeObject)
void | Show | Show = 1065353216 (CK_OBJECT_SHOWOPTION)

ImpactDesc

Members

    m_OwnerEntity (int)
    m_ObstacleTouched (int)
    m_SubObstacleTouched (int)
    m_TouchedVertex (int)
    m_TouchingVertex (int)
    m_TouchedFace (int)
    m_TouchingFace (int)
    m_ImpactWorldMatrix (Matrix)
    m_ImpactPoint (Vector)
    m_ImpactNormal (Vector)
    m_Entity (int)

InputManager

Methods

Return | Function | Parameters
void | EnableKeyboardRepetition | e = true (bool)
bool | GetCursorVisibility |
int | GetJoystickButtonsState | Joystick (int)
int | GetJoystickCount |
void | GetJoystickPointOfViewAngle | Joystick (int) angle (float)
void | GetJoystickPosition | Joystick (int) pos (Vector)
void | GetJoystickRotation | Joystick (int) rot (Vector)
void | GetJoystickSliders | Joystick (int) pos (Vector2D)
char | GetKeyChar | key (Key)
int | GetKeyFromBuffer | i (int) k (int) timeStamp = 0 (int)
int | GetKeyFromName | key_name (String)
void | GetKeyName | key (Key) key_name (String)
void | GetMousePosition | v (Vector2D) absolute = true (bool)
void | GetMouseRelativePosition | pt (Vector)
int | GetNumberOfKeyInBuffer |
VXCURSOR_POINTER | GetSystemCursor |
bool | IsJoystickAttached | Joystick (int)
bool | IsJoystickButtonDown | Joystick (int) Button (int)
bool | IsKeyDown | key (Key) stamp = 0 (int)
bool | IsKeyToggled | key (Key) stamp = 0 (int)
bool | IsKeyboardAttached |
bool | IsKeyboardRepetitionEnabled |
bool | IsMouseAttached |
bool | IsMouseButtonDown | but (CK_MOUSEBUTTON)
bool | IsMouseClicked | but (CK_MOUSEBUTTON)
bool | IsMouseToggled | but (CK_MOUSEBUTTON)
void | SetSystemCursor | cursor (VXCURSOR_POINTER)
void | ShowCursor | b (bool)

IntArray

Methods

Return | Function | Parameters
IntArray | += | iArray (IntArray)
IntArray | = | iArray (IntArray)
void | Clear |
bool | Erase | iValue (int)
bool | EraseAt | iPos (int)
bool | IsHere | iValue (int)
int | PopBack |
void | PushBack | iValue (int)
void | PushFront | iValue (int)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
int | [] | iPos (int)

IntersectionDesc

Members

    Object (Entity3D)
    IntersectionPoint (Vector)
    IntersectionNormal (Vector)
    TexU (float)
    TexV (float)
    Distance (float)
    FaceIndex (int)

Layer

Parents Classes

    Object

Methods

Return | Function | Parameters
int | GetFormat |
int | GetOwner |
int | GetSquareArray |
int | GetType |
void | GetValue | x (int) y (int) val (ptr)
bool | GetValue2 | x (int) y (int) val (ptr)
bool | IsVisible |
void | SetFormat | Format (int)
void | SetOwner | owner (int)
void | SetSquareArray | sqarray (int)
void | SetType | Type (int)
void | SetValue | x (int) y (int) val (ptr)
bool | SetValue2 | x (int) y (int) val (ptr)
void | SetVisible | vis = true (bool)

Light

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
void | Active | iActive (bool)
bool | GetActivity |
Color | GetColor |
float | GetConstantAttenuation |
float | GetFallOff |
float | GetFallOffShape |
float | GetHotSpot |
float | GetLightPower |
float | GetLinearAttenuation |
float | GetQuadraticAttenuation |
float | GetRange |
bool | GetSpecularFlag |
Entity3D | GetTarget |
VXLIGHT_TYPE | GetType |
void | SetColor | iColor (Color)
void | SetConstantAttenuation | iFactor (float)
void | SetFallOff | iAngle (float)
void | SetFallOffShape | iFactor (float)
void | SetHotSpot | iAngle (float)
void | SetLightPower | iPower = 1.000000 (float)
void | SetLinearAttenuation | iFactor (float)
void | SetQuadraticAttenuation | iFactor (float)
void | SetRange | iDistance (float)
void | SetSpecularFlag | iEnable (bool)
void | SetTarget | iTarget (Entity3D)
void | SetType | iType (VXLIGHT_TYPE)

Material

Parents Classes

    BeObject

Methods

Return | Function | Parameters
bool | AlphaBlendEnabled |
bool | AlphaTestEnabled |
void | EnableAlphaBlend | Blend = true (bool)
void | EnableAlphaTest | Enable = true (bool)
void | EnablePerpectiveCorrection | Perspective = true (bool)
void | EnableZWrite | ZWrite = true (bool)
VXCMPFUNC | GetAlphaFunc |
char | GetAlphaRef |
Color | GetAmbient |
VXBLEND_MODE | GetDestBlend |
Color | GetDiffuse |
Parameter | GetEffectParameter |
Color | GetEmissive |
VXFILL_MODE | GetFillMode |
float | GetPower |
VXSHADE_MODE | GetShadeMode |
VXBLEND_MODE | GetSourceBlend |
Color | GetSpecular |
Texture | GetTexture | TexIndex = 0 (int)
VXTEXTURE_ADDRESSMODE | GetTextureAddressMode |
VXTEXTURE_BLENDMODE | GetTextureBlendMode |
int | GetTextureBorderColor |
VXTEXTURE_FILTERMODE | GetTextureMagMode |
VXTEXTURE_FILTERMODE | GetTextureMinMode |
VXCMPFUNC | GetZFunc |
bool | IsAlphaTransparent |
bool | IsTwoSided |
bool | PerspectiveCorrectionEnabled |
void | SetAlphaFunc | AlphaFunc = 1090519040 (VXCMPFUNC)
void | SetAlphaRef | AlphaRef = >
void | SetAmbient | Color (Color)
bool | SetAsCurrent | (RenderContext) Lit = true (bool) TextureStage = 0 (int)
void | SetDestBlend | BlendMode (VXBLEND_MODE)
void | SetDiffuse | Color (Color)
void | SetEmissive | Color (Color)
void | SetFillMode | FillMode (VXFILL_MODE)
void | SetPower | Value (float)
void | SetShadeMode | ShadeMode (VXSHADE_MODE)
void | SetSourceBlend | BlendMode (VXBLEND_MODE)
void | SetSpecular | Color (Color)
void | SetTexture | Tex (Texture)
void | SetTexture | TexIndex (int) Tex (Texture)
void | SetTextureAddressMode | Mode (VXTEXTURE_ADDRESSMODE)
void | SetTextureBlendMode | BlendMode (VXTEXTURE_BLENDMODE)
void | SetTextureBorderColor | Color (int)
void | SetTextureMagMode | FilterMode (VXTEXTURE_FILTERMODE)
void | SetTextureMinMode | FilterMode (VXTEXTURE_FILTERMODE)
void | SetTwoSided | TwoSided (bool)
void | SetZFunc | ZFunc = 1082130432 (VXCMPFUNC)
bool | ZWriteEnabled |

Matrix

Methods

Return | Function | Parameters
bool | != | mat (Matrix)
Matrix | * | iMat (Matrix)
Matrix | *= | mat (Matrix)
bool | == | mat (Matrix)
void | Clear |
void | Orthographic | iZoom (float) iAspect (float) iNearPlane (float) iFarPlane (float)
void | OrthographicRect | iLeft (float) iRight (float) iTop (float) iBottom (float) iNearPlane (float) iFarPlane (float)
void | Perspective | iFov (float) iAspect (float) iNearPlane (float) iFarPlane (float)
void | PerspectiveRect | iLeft (float) iRight (float) iTop (float) iBottom (float) iNearPlane (float) iFarPlane (float)
void | RecomposeMatrix | Pos (Vector) Scale (Vector) Quat (Quaternion)
void | RecomposeMatrixEx | Pos (Vector) Scale (Vector) Quat (Quaternion) Shear (Quaternion) Sign (float)
void | SetIdentity |
Vector4 | [] | i (int)

Mesh

Parents Classes

    BeObject

Methods

Return | Function | Parameters
void | ActivateAllChannels | Active = true (bool)
void | ActivateChannel | Index (int) Active = true (bool)
int | AddChannel | Mat (Material) CopySrcUv = true (bool)
void | ApplyGlobalMaterial | Mat (Material)
void | BuildFaceNormals |
void | BuildNormals |
void | Clean | KeepVertices = false (bool)
void | ColorChanged |
void | Consolidate |
void | CreateLineStrip | StartingLine (int) Count (int) StartingVertexIndex (int)
int | CreatePM |
void | DestroyPM |
void | DissociateAllFaces |
void | EnablePMGeoMorph | enable (bool)
void | GetBaryCenter | Vector (Vector)
int | GetChannelByMaterial | mat (Material)
int | GetChannelCount |
VXBLEND_MODE | GetChannelDestBlend | Index (int)
int | GetChannelFlags | Index (int)
Material | GetChannelMaterial | Index (int)
VXBLEND_MODE | GetChannelSourceBlend | Index (int)
ptr | GetColorsPtr | Stride (int)
int | GetFaceCount |
Material | GetFaceMaterial | Index (int)
Vector | GetFaceNormal | Index (int)
Vector | GetFaceVertex | FaceIndex (int) VIndex (int)
void | GetFaceVertexIndex | Index (int) Vertex1 (int) Vertex2 (int) Vertex3 (int)
int | GetFacesIndices |
int | GetFlags |
void | GetLine | LineIndex (int) VIndex1 (int) VIndex2 (int)
int | GetLineCount |
VXMESH_LITMODE | GetLitMode |
Bbox | GetLocalBox |
Material | GetMaterial | index (int)
int | GetMaterialCount |
void | GetModifierUV | Index (int) U (float) V (float) channel = -1 (int)
int | GetModifierUVCount | channel = -1 (int)
void | GetModifierVertex | Index (int) pos (Vector)
int | GetModifierVertexCount |
ptr | GetNormalsPtr | Stride (int)
int | GetPMGeoMorphStep |
ptr | GetPositionsPtr | Stride (int)
float | GetRadius |
ptr | GetSpecularColorsPtr | Stride (int)
ptr | GetTextureCoordinatesPtr | Stride (int) channel = -1 (int)
int | GetVertexColor | Index (int)
int | GetVertexCount |
void | GetVertexNormal | Index (int) Vector (Vector)
void | GetVertexPosition | Index (int) Vector (Vector)
int | GetVertexSpecularColor | Index (int)
void | GetVertexTextureCoordinates | Index (int) u (float) v (float) channel = -1 (int)
float | GetVertexWeight | index (int)
int | GetVertexWeightsCount |
float | GetVertexWeightsPtr |
int | GetVerticesRendered |
VXTEXTURE_WRAPMODE | GetWrapMode |
void | InverseWinding |
bool | IsChannelActive | Index (int)
bool | IsChannelLit | Index (int)
bool | IsPM |
bool | IsPMGeoMorphEnabled |
bool | IsTransparent |
void | LitChannel | Index (int) Lit = true (bool)
void | ModifierUVMove | channel = -1 (int)
void | ModifierVertexMove | RebuildNormals (bool) RebuildFaceNormals (bool)
void | NormalChanged |
void | RemoveAllCallbacks |
void | RemoveChannel | Mat (Material)
void | RemoveChannel | Index (int)
int | Render | Dev (RenderContext) Mov (Entity3D)
void | ReplaceMaterial | oldMat (Material) newMat (Material) merge = false (bool)
void | RotateVertices | Vector (Vector) Angle (float)
void | ScaleVertices | Vector (Vector) Pivot = 0 (Vector)
void | ScaleVertices | X (float) Y (float) Z (float) Pivot = 0 (Vector)
void | SetChannelDestBlend | Index (int) BlendMode (VXBLEND_MODE)
void | SetChannelFlags | Index (int) Flags (int)
void | SetChannelMaterial | Index (int) Mat (Material)
void | SetChannelSourceBlend | Index (int) BlendMode (VXBLEND_MODE)
void | SetDefaultRenderCallBack |
bool | SetFaceCount | Count (int)
void | SetFaceMaterial | FaceIndex (int) Mat (Material)
void | SetFaceMaterial | FaceIndices (int) FaceCount (int) Mat (Material)
void | SetFaceVertexIndex | FaceIndex (int) Vertex1 (int) Vertex2 (int) Vertex3 (int)
void | SetFlags | Flags (int)
void | SetLine | LineIndex (int) VIndex1 (int) VIndex2 (int)
bool | SetLineCount | Count (int)
void | SetLitMode | Mode (VXMESH_LITMODE)
void | SetModifierUV | Index (int) U (float) V (float) channel = -1 (int)
void | SetModifierVertex | Index (int) pos (Vector)
void | SetPMGeoMorphStep | gs (int)
void | SetTransparent | Transparency (bool)
void | SetVertexColor | Index (int) Color (int)
bool | SetVertexCount | Count (int)
void | SetVertexNormal | Index (int) Vector (Vector)
void | SetVertexPosition | Index (int) Vector (Vector)
void | SetVertexSpecularColor | Index (int) Color (int)
void | SetVertexTextureCoordinates | Index (int) u (float) v (float) channel = -1 (int)
void | SetVertexWeight | index (int) w (float)
void | SetVertexWeightsCount | count (int)
void | SetVerticesRendered | count (int)
void | SetWrapMode | Mode (VXTEXTURE_WRAPMODE)
void | TranslateVertices | Vector (Vector)
void | UVChanged | channel = -1 (int)
void | UnOptimize |
void | VertexMove |

OBB

Methods

Return | Function | Parameters
void | Create | box (Bbox) mat (Matrix)
Vector | GetAxes |
Vector | GetAxis | i (int)
Vector | GetCenter |
float | GetExtent | i (int)
float | GetExtents |

Object

Methods

Return | Function | Parameters
Object | CKGetObject | id (int)
int | CanBeHide |
ptr | GetAppData |
Object | GetCKObject | id (int)
int | GetID |
int | GetMemoryOccupation |
str | GetName |
int | GetObjectFlags |
bool | IsDynamic |
bool | IsHiddenByParent |
bool | IsHierarchicallyHide |
bool | IsInterfaceObj |
bool | IsNotToBeSaved |
bool | IsPrivate |
bool | IsUpToDate |
bool | IsVisible |
void | ModifyObjectFlags | add (int) remove (int)
void | SetAppData | Data (ptr)
void | SetName | Name (str) shared = false (bool)
void | Show | show = 1065353216 (CK_OBJECT_SHOWOPTION)

ObjectArray

Methods

Return | Function | Parameters
ObjectArray | += | iArray (ObjectArray)
ObjectArray | = | iArray (ObjectArray)
bool | Erase | iObject (Object)
bool | EraseAt | iIndex (int)
bool | IsHere | iObject (Object)
Object | PopBack |
void | PushBack | iObject (Object)
void | PushFront | iObject (Object)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
Object | [] | iIndex (int)

PatchMesh

Parents Classes

    Mesh

Methods

Return | Function | Parameters
void | BuildRenderMesh |
int | FromMesh | m (Mesh)
int | GetEdgeCount |
int | GetIterationCount |
int | GetPatchCount |
int | GetPatchFlags |
Material | GetPatchMaterial | index (int)
int | GetPatchSM | index (int)
void | GetTV | index (int) u (float) v (float) Channel = -1 (int)
int | GetTVCount | Channel = -1 (int)
int | GetTVPatchCount | Channel = -1 (int)
void | GetVec | index (int) cp (Vector)
int | GetVecCount |
Vector | GetVecs |
void | GetVert | index (int) cp (Vector)
int | GetVertCount |
Vector | GetVerts |
void | SetEdgeCount | count (int)
void | SetIterationCount | count (int)
void | SetPatchCount | count (int)
void | SetPatchFlags | Flags (int)
void | SetPatchMaterial | index (int) mat (Material)
void | SetPatchSM | index (int) smoothing (int)
void | SetTV | index (int) u (float) v (float) Channel = -1 (int)
void | SetTVCount | count (int) Channel = -1 (int)
void | SetTVPatchCount | count (int) Channel = -1 (int)
void | SetVec | index (int) cp (Vector)
void | SetVert | index (int) cp (Vector)
void | SetVertVecCount | VertCount (int) VecCount (int)
int | ToMesh | m (Mesh) stepcount (int)

Plane

Members

    m_Normal (Vector)
    m_D (float)

Methods

Return | Function | Parameters
float | Classify | p (Vector)
float | Classify | box (Bbox)
float | Classify | box (Bbox) mat (Matrix)
float | ClassifyFace | pt0 (Vector) pt1 (Vector) pt2 (Vector)
void | Create | n (Vector) p (Vector)
void | Create | a (Vector) b (Vector) c (Vector)
float | Distance | p (Vector)
Vector | GetNormal |
Vector | NearestPoint | p (Vector)
float | XClassify | boxaxis (Vector)

PointCloud

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
bool | CreateFromAscFile | iFileName (str)
void | EnableLighting | iEnable = true (bool)
int | GetCloudAttributeCount |
CloudAttribute | GetCloudAttributeDescription | iAttributeIndex (int)
int | GetCloudAttributeIndexByName | iName (BaseString)
float | GetGlobalPointSize |
int | GetIndexOfPointWithAttribute | iAttributeIndex (int) iPointIndex (int)
Vector | GetLoadOffset |
float | GetLoadScaleFactor |
int | GetMemorySize |
int | GetPointColor | iPointIndex (int)
float | GetPointFloatAttribute | iPointIndex (int) iAttributeIndex (int)
int | GetPointIntAttribute | iPointIndex (int) iAttributeIndex (int)
int | GetPointIntensity | iPointIndex (int)
Vector | GetPointNormal | iPointIndex (int)
int | GetPointRenderGroup | iPointIndex (int)
int | GetPointWithAttributeCount | iAttributeIndex (int)
int | GetPointsCount |
CloudRenderGroup | GetRenderGroup | iCode (int)
int | GetRenderGroupCount |
CloudIterator | GetRootIterator |
int | GetVertexBufferCount |
int | GetVertexBufferMemorySize |
bool | HasColors |
bool | HasNormals |
bool | IsAttributeOnPoint | iPointIndex (int) iAttributeIndex (int)
bool | IsCloudAttributeUsed | iAttributeIndex (int)
bool | IsLightingEnabled |
CloudIterator | RayPick | iRay (Ray) iRadius (float) iPutInRenderGroup = -1 (int)
int | RegisterCloudAttribute | iAttributeDesc (CloudAttribute)
bool | RemoveRenderGroup | iGroupIndex (int)
CloudIterator | SelectBox | iBox (Bbox) iPutInRenderGroup = -1 (int)
CloudIterator | SelectCylinder | iSegment (Ray) iRadius (float) iPutInRenderGroup = -1 (int)
CloudIterator | SelectHalfSpace | iPlane (Plane) iPutInRenderGroup = -1 (int)
CloudIterator | SelectSphere | iSphere (Sphere) iPutInRenderGroup = -1 (int)
void | SetAttributeOnPoint | iPointIndex (int) iAttributeIndex (int)
void | SetCloudAttributeDescription | iAttributeIndex (int) iDescription (CloudAttribute)
void | SetGlobalPointSize | iPointSize (float)
void | SetPointFloatAttribute | iPointIndex (int) iAttributeIndex (int) iValue (float)
void | SetPointIntAttribute | iPointIndex (int) iAttributeIndex (int) iValue (int)
void | SetPointRenderGroup | iPointIndex (int) iRenderGroup (int)
void | SetReferentialPosition | iPosition (Vector) iRef = 0 (Entity3D)
void | SetRenderGroup | iCode (int) iGroup (CloudRenderGroup)
void | SetRenderGroupCount | iGroupCount (int)
void | UnRegisterCloudAttribute | iAttributeIndex (int)
void | UseCloudAttribute | iAttributeIndex (int) iUse (bool)
void | UseColors | iUseColors (bool)
void | UseNormals | iUseNormals (bool)

Quaternion

Members

    x (float)
    y (float)
    z (float)
    axis (Vector)
    angle (float)

Methods

Return | Function | Parameters
Quaternion | * | q (Quaternion)
Quaternion | *= | s (float)
Quaternion | + | q (Quaternion)
Quaternion | + |
Quaternion | - | q (Quaternion)
Quaternion | - |
Quaternion | / | q (Quaternion)
void | FromEulerAngles | eax (float) eay (float) eaz (float)
void | FromMatrix | Mat (Matrix) MatIsUnit = true (bool) RestoreMat = true (bool)
void | FromRotation | Vector (Vector) Angle (float)
void | Multiply | Quat (Quaternion)
void | Normalize |
void | ToEulerAngles | eax (float) eay (float) eaz (float)
void | ToMatrix | Mat (Matrix)
void | ToRotation | Vector (Vector) Angle (float)
float | [] | i (int)

Ray

Members

    m_Origin (Vector)
    m_Direction (Vector)

Methods

Return | Function | Parameters
float | Distance | p (Vector)
Vector | GetDirection |
Vector | GetOrigin |
void | Interpolate | p (Vector) t (float)
float | SquareDistance | p (Vector)
void | Transform | dest (Ray) mat (Matrix)

Rect

Members

    left (float)
    top (float)
    right (float)
    bottom (float)

Methods

Return | Function | Parameters
Rect | *= | t (Vector2D)
Rect | += | t (Vector2D)
Rect | -= | t (Vector2D)
Rect | /= | t (Vector2D)
void | Bounding | p1 (Vector2D) p2 (Vector2D)
void | Clear |
bool | Clip | cliprect (Rect)
void | Clip | pt (Vector2D) excluderightbottom = true (bool)
Vector2D | GetBottomRight |
Vector2D | GetCenter |
float | GetHCenter |
Vector2D | GetHalfSize |
float | GetHeight |
Vector2D | GetSize |
Vector2D | GetTopLeft |
float | GetVCenter |
float | GetWidth |
void | HMove | h (float)
void | HTranslate | h (float)
void | Inflate | pt (Vector2D)
void | Interpolate | value (float) a (Rect)
int | IsInside | cliprect (Rect)
bool | IsInside | pt (Vector2D)
bool | IsNull |
bool | IsOutside | cliprect (Rect)
void | Merge | a (Rect)
void | Move | pos (Vector2D)
void | Normalize |
void | Scale | s (Vector2D)
void | SetBottomRight | v (Vector2D)
void | SetCenter | v (Vector2D)
void | SetCenter | center (Vector2D) halfsize (Vector2D)
void | SetCenter | cx (float) cy (float) hw (float) hh (float)
void | SetCorners | topleft (Vector2D) bottomright (Vector2D)
void | SetCorners | l (float) t (float) r (float) b (float)
void | SetDimension | position (Vector2D) size (Vector2D)
void | SetDimension | x (float) y (float) w (float) h (float)
void | SetHalfSize | v (Vector2D)
void | SetHeight | h (float)
void | SetSize | v (Vector2D)
void | SetTopLeft | v (Vector2D)
void | SetWidth | w (float)
void | Transform | destScreen (Rect) srcScreen (Rect)
void | Transform | destScreenSize (Vector2D) srcScreenSize (Vector2D)
void | TransformFromHomogeneous | dest (Vector2D) srchom (Vector2D)
void | TransformFromHomogeneous | screen (Rect)
void | TransformToHomogeneous | screen (Rect)
void | Translate | t (Vector2D)
void | VMove | v (float)
void | VTranslate | v (float)

RenderContext

Parents Classes

    Object

Methods

Return | Function | Parameters
void | AttachViewpointToCamera | cam (Camera)
void | ClientToScreen | pt (Vector2D)
int | DumpToFile | filename (str) rect (Rect) buffer (VXBUFFER_TYPE)
int | GetAmbientLight |
Camera | GetAttachedCamera |
Material | GetBackgroundMaterial |
void | GetBoundingBox | BBox (Bbox)
int | GetFogColor |
float | GetFogDensity |
float | GetFogEnd |
VXFOG_MODE | GetFogMode |
float | GetFogStart |
int | GetHeight |
void | GetViewRect | rect (Rect)
int | GetWidth |
void | GetWindowRect | rect (Rect) ScreenRelative = false (bool)
RenderObject | Pick | x (int) y (int) oRes (IntersectionDesc) iIgnoreUnpickable = false (bool)
Entity2D | Pick2D | v (Vector2D)
int | RectPick | r (Rect) oObjects (ObjectArray) Intersect = true (bool)
void | ScreenToClient | pt (Vector2D)
void | ScreenToViewpoint | i2DPosition (Vector2D) o3DPosition (Vector) iScreen = true (bool)
void | SetAmbientLight | R (float) G (float) B (float)
void | SetAmbientLight | Color (int)
void | SetCurrentMaterial | mat (Material) Lit = true (bool)
void | SetFogColor | Color (int)
void | SetFogDensity | Density (float)
void | SetFogEnd | End (float)
void | SetFogMode | Mode (VXFOG_MODE)
void | SetFogStart | Start (float)
void | Transform | Dest (Vector) src (Vector) Ref (Entity3D)

RenderManager

Methods

Return | Function | Parameters
void | RegisterAABB | iBox (Bbox) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix)
void | RegisterFrustum | iFrustum (Frustum) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix)
void | RegisterNormal | iRay (Ray) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix)
void | RegisterParabolic | iStartPos (Vector) iSpeed (Vector) iAcceleration (Vector) iDrawingTime (float) iSubdivisions (int) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix)
void | RegisterPlane | iPlane (Plane) iPoint (Vector) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix)
void | RegisterPoint | iPoint (Vector) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix)
void | RegisterRectangle | iRect (Rect) iColor (int) iRemainingTime = 0.000000 (float)
void | RegisterSphere | iSphere (Sphere) iColor (int) iRemainingTime = 0.000000 (float) iTransform = 0 (Matrix) iSubdivisions = 32 (int)

RenderObject

Parents Classes

    BeObject

Methods

Return | Function | Parameters
int | GetZOrder |
void | SetZOrder | order (int)

Scene

Parents Classes

    BeObject

Methods

Return | Function | Parameters
void | Activate | object (SceneObject) reset (bool)
void | AddObjectToScene | object (SceneObject) dependencies = true (bool)
void | DeActivate | object (SceneObject)
int | GetObjectCount |
bool | IsObjectActive | object (SceneObject)
bool | IsObjectHere | object (Object)
void | RemoveObjectFromScene | object (SceneObject) dependencies = true (bool)

ScriptContext

Methods

Return | Function | Parameters
void | ActivateObject | iObject (BeObject) activate (bool) reset (bool)
bool | ActivateScript | iObject (BeObject) iScriptName (str) activate (bool) reset (bool)
Object | Copy | iSrc (Object) iDynamic = true (bool) iDependencies = false (bool)
Array | CreateArray | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Camera | CreateCamera | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Curve | CreateCurve | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
CurvePoint | CreateCurvePoint | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Entity2D | CreateEntity2D | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Entity3D | CreateEntity3D | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Grid | CreateGrid | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Light | CreateLight | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Material | CreateMaterial | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Mesh | CreateMesh | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Object | CreateObject | iObjectID (CK_CLASSID) iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Sprite | CreateSprite | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Sprite3D | CreateSprite3D | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
Texture | CreateTexture | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
WaveSound | CreateWaveSound | iName (str) iDynamic = true (bool) iAddToCurrentScene = true (bool)
void | DestroyObject | iObject (Object) iDependencies = false (bool)
void | FillObjectArrayByType | array (ObjectArray) cid (CK_CLASSID) derived (bool) scene = 0 (Scene)
void | GetAttributeValue | iObject (BeObject) iAttributName (str) iValue (ptr)
ObjectArray | GetAttributedObjects | iName (str) iAnyScenes = false (bool)
ObjectArray | GetAttributedObjects | iAttr (Attribute) iAnyScenes = false (bool)
Level | GetCurrentLevel |
Scene | GetCurrentScene |
float | GetDeltaTime |
BaseManager | GetManagerByGuid | guid (GUID)
Object | GetObject | iObjID (int)
Object | GetObjectByName | name (str) previous = 0 (Object)
Object | GetObjectByNameAndClass | name (str) cid (CK_CLASSID) previous = 0 (Object)
Object | GetObjectByNameAndParentClass | name (str) pcid (CK_CLASSID) previous = 0 (Object)
RenderContext | GetPlayerRenderContext |
RenderManager | GetRenderManager |
bool | GetVariableValue | iVariable (str) oValue (int)
bool | GetVariableValue | iVariable (str) oValue (float)
bool | GetVariableValue | iVariable (str) oValue (String)
bool | HasAttribute | iObject (BeObject) iAttributName (str)
void | OutputToConsole | iMessage (String) iBeep = false (bool)
void | OutputToConsole | iMessage (str) iBeep = false (bool)
void | OutputToConsole | iInt (int) iBeep = false (bool)
void | OutputToConsole | iFloat (float) iBeep = false (bool)
void | OutputToScreen | iMessage (String) iCol = -1 (int) iTime = 0.000000 (float)
void | OutputToScreen | iMessage (str) iCol = -1 (int) iTime = 0.000000 (float)
void | OutputToScreen | iInt (int) iCol = -1 (int) iTime = 0.000000 (float)
void | OutputToScreen | iFloat (float) iCol = -1 (int) iTime = 0.000000 (float)
void | SetAttribute | iObject (BeObject) iAttributName (str) iValue (ptr)
bool | SetVariableValue | iVariable (str) iValue (int)
bool | SetVariableValue | iVariable (str) iValue (float)
bool | SetVariableValue | iVariable (str) iValue (str)
void | UserProfileEnd | iTimerIndex (int)
void | UserProfileStart | iTimerIndex (int)

Sphere

Methods

Return | Function | Parameters
Vector | Center |
int | IsPointInside | iPoint (Vector)
int | IsPointOnSurface | iPoint (Vector)
float | Radius |

Sprite

Parents Classes

    Entity2D

Methods

Return | Function | Parameters
bool | AlphaTestEnabled |
bool | BlendingEnabled |
bool | ColorModulateEnabled |
bool | Create | Width (int) Height (int) BPP = 32 (int) Slot = 0 (int)
bool | FilteringEnabled |
bool | FreeVideoMemory |
VXCMPFUNC | GetAlphaTestFunc |
char | GetAlphaTestRefValue |
int | GetCurrentSlot |
VX_PIXELFORMAT | GetDesiredVideoFormat |
VXBLEND_MODE | GetDestinationBlendMode |
int | GetHeight |
Color | GetModulateColor |
str | GetMovieFileName |
int | GetPickThreshold |
int | GetPixel | x (int) y (int) slot = -1 (int)
CK_BITMAP_SAVEOPTIONS | GetSaveOptions |
int | GetSlotCount |
str | GetSlotFileName | Slot (int)
VXBLEND_MODE | GetSourceBlendMode |
int | GetTransparentColor |
VX_PIXELFORMAT | GetVideoPixelFormat |
int | GetWidth |
bool | IsInVideoMemory |
bool | IsTransparent |
bool | LoadImage | Name (str) Slot = 0 (int)
bool | LoadMovie | Name (str) width = 0 (int) height = 0 (int) Bpp = 16 (int)
char | LockSurfacePtr | Slot = -1 (int)
bool | ReleaseAllSlots |
bool | ReleaseSlot | Slot (int)
bool | ReleaseSurfacePtr | Slot = -1 (int)
bool | Restore | Clamp = false (bool)
bool | SaveImage | Name (str) Slot = 0 (int) CKUseFormat = false (bool)
void | SetAlphaTest | Enable (bool) RefValue (char) AlphaTestFunc (VXCMPFUNC)
void | SetBlending | Enable (bool) SrcBlendMode (VXBLEND_MODE) DstBlendMode (VXBLEND_MODE)
void | SetColorModulate | Enable (bool) color (Color)
bool | SetCurrentSlot | Slot (int)
void | SetDesiredVideoFormat | pf (VX_PIXELFORMAT)
void | SetFiltering | Enable (bool)
void | SetPickThreshold | iPickThreshold (int)
bool | SetPixel | x (int) y (int) col (int) slot = -1 (int)
void | SetSaveOptions | Options (CK_BITMAP_SAVEOPTIONS)
bool | SetSlotCount | Count (int)
bool | SetSlotFileName | Slot (int) Filename (str)
void | SetTransparent | Transparency (bool)
void | SetTransparentColor | Color (int)
bool | SystemToVideoMemory | Dev (RenderContext) Clamping = false (bool)

Sprite3D

Parents Classes

    Entity3D

Methods

Return | Function | Parameters
Material | GetMaterial |
VXSPRITE3D_TYPE | GetMode |
void | GetOffset | vect (Vector2D)
void | GetSize | vect (Vector2D)
void | GetUVMapping | rect (Rect)
void | SetMaterial | Mat (Material)
void | SetMode | Mode (VXSPRITE3D_TYPE)
void | SetOffset | vect (Vector2D)
void | SetSize | vect (Vector2D)
void | SetUVMapping | rect (Rect)

String

Parents Classes

    BaseString

Methods

Return | Function | Parameters
int | != | iStr (str)
int | != | iStr (BaseString)
String | + | iString (str)
String | + | iString (BaseString)
String | + | iValue (char)
String | + | iValue (int)
String | + | iValue (float)
String | += | iValue (String)
String | += | iValue (int)
String | += | iValue (float)
String | += | iValue (char)
String | += | iValue (str)
int | - | iStr (str)
int | - | iStr (BaseString)
int | < | iStr (str)
int | < | iStr (BaseString)
int | <= | iStr (str)
int | <= | iStr (BaseString)
String | = | iSrc (String)
String | = | iSrc (str)
String | = | iSrc (BaseString)
int | == | iStr (str)
int | == | iStr (BaseString)
int | > | iStr (str)
int | > | iStr (BaseString)
int | >= | iStr (str)
int | >= | iStr (BaseString)
int | Capacity |
int | Compare | iStr (BaseString)
bool | Contains | iStr (BaseString)
String | Create | iString (str) iLength = 0 (int)
String | CreateTail | iString (BaseString) iStart = 0 (int)
String | Crop | iStart (int) iLength (int)
String | Cut | iStart (int) iLength (int)
int | Find | iCar (char) iStart = 0 (int)
int | Find | iStr (BaseString) iStart = 0 (int)
String | FormatTime | iFormat (str)
String | FormatTime | iTime (int) iFormat (str)
int | ICompare | iStr (BaseString)
bool | IContains | iStr (BaseString)
int | IFind | iStr (BaseString) iStart = 0 (int)
int | RFind | iCar (char) iStart = 0 (int)
int | Replace | iSrc (char) iDest (char)
int | Replace | iSrc (BaseString) iDest (BaseString)
void | Reserve | iLength (int)
void | Resize | iLength (int)
str | Str |
String | Strip |
String | Substring | iStart (int) iLength = 0 (int)
String | ToLower |
String | ToUpper |
String | Trim |
char | [] | i (int)
char | [] | i (int)

StringTokenizer

Methods

Return | Function | Parameters
str | NextToken | iPrevToken (str)

Texture

Parents Classes

    BeObject
    BitmapData

Methods

Return | Function | Parameters
int | Create | width (int) height (int) bpp = 32 (int) slot = 0 (int)
bool | FreeVideoMemory |
int | GetMipmapCount |
int | LoadImage | FileName (str) Slot = 0 (int)
int | LoadMovie | MovieName (str)
bool | SystemToVideoMemory | ctx (RenderContext) Clamping = false (bool)
bool | UseMipmap | MipmapCount = -1 (int)
bool | VideoToSystemMemory |

Timer

Methods

Return | Function | Parameters
float | Current |
void | Reset |
float | Split |

Vector

Members

    x (float)
    y (float)
    z (float)

Methods

Return | Function | Parameters
Vector | *= | v (Vector)
Vector | *= | s (float)
Vector | + | s (float)
Vector | += | v (Vector)
Vector | - | s (float)
Vector | -= | v (Vector)
Vector | /= | v (Vector)
Vector | /= | s (float)
void | Absolute |
float | Dot | iV (Vector)
float | Magnitude |
void | Normalize |
void | Rotate | M (Matrix)
void | Set | X (float) Y (float) Z (float)
float | SquareMagnitude |
float | [] | i (int)

Vector2D

Members

    x (float)
    y (float)

Methods

Return | Function | Parameters
bool | != | v1 (Vector2D) v2 (Vector2D)
Vector2D | * | v (Vector2D)
Vector2D | * | f (float)
Vector2D | *= | v (Vector2D)
Vector2D | *= | s (float)
Vector2D | + | v (Vector2D)
Vector2D | += | v (Vector2D)
Vector2D | - | v (Vector2D)
Vector2D | -= | v (Vector2D)
Vector2D | / | v (Vector2D)
Vector2D | / | f (float)
Vector2D | /= | v (Vector2D)
Vector2D | /= | s (float)
bool | < | v1 (Vector2D) v2 (Vector2D)
bool | <= | v1 (Vector2D) v2 (Vector2D)
bool | == | v1 (Vector2D) v2 (Vector2D)
Vector2D | Cross |
float | Dot | iV (Vector2D)
float | Magnitude |
float | Max | iSrc (Vector2D)
float | Min | iSrc (Vector2D)
Vector2D | Normalize |
void | Set | x (float) y (float)
void | Set | x (int) y (int)
float | SquareMagnitude |
float | [] | i (int)

Vector2DArray

Methods

Return | Function | Parameters
Vector2DArray | += | iArray (Vector2DArray)
Vector2DArray | = | iArray (Vector2DArray)
void | Clear |
bool | Erase | iValue (Vector2D)
bool | EraseAt | iPos (int)
bool | IsHere | iValue (Vector2D)
Vector2D | PopBack |
void | PushBack | iValue (Vector2D)
void | PushFront | iValue (Vector2D)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
Vector2D | [] | iPos (int)

Vector4

Parents Classes

    Vector

Members

    w (float)

Methods

Return | Function | Parameters
Vector4 | *= | v (Vector4)
Vector4 | *= | v (Vector)
Vector4 | *= | s (float)
Vector4 | + | s (float)
Vector4 | += | v (Vector4)
Vector4 | += | v (Vector)
Vector4 | - | s (float)
Vector4 | -= | v (Vector4)
Vector4 | -= | v (Vector)
Vector4 | /= | v (Vector4)
Vector4 | /= | v (Vector)
Vector4 | /= | s (float)
Vector4 | = | v (Vector)
float | Dot | iV (Vector4)
void | Set | X (float) Y (float) Z (float) W (float)
float | [] | i (int)

Vector4Array

Methods

Return | Function | Parameters
Vector4Array | += | iArray (Vector4Array)
Vector4Array | = | iArray (Vector4Array)
void | Clear |
bool | Erase | iValue (Vector4)
bool | EraseAt | iPos (int)
bool | IsHere | iValue (Vector4)
Vector4 | PopBack |
void | PushBack | iValue (Vector4)
void | PushFront | iValue (Vector4)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
Vector4 | [] | iPos (int)

VectorArray

Methods

Return | Function | Parameters
VectorArray | += | iArray (VectorArray)
VectorArray | = | iArray (VectorArray)
void | Clear |
bool | Erase | iValue (Vector)
bool | EraseAt | iPos (int)
bool | IsHere | iValue (Vector)
Vector | PopBack |
void | PushBack | iValue (Vector)
void | PushFront | iValue (Vector)
void | Reserve | iSize (int)
void | Resize | iSize (int)
int | Size |
Vector | [] | iPos (int)

WaveFormat

Members

    wFormatTag (int)
    nChannels (int)
    nSamplesPerSec (int)
    nAvgBytesPerSec (int)
    nBlockAlign (int)
    wBitsPerSample (int)
    cbSize (int)

WaveSound

Parents Classes

    BeObject

Methods

Return | Function | Parameters
Entity3D | GetAttachedEntity |
void | GetCone | InAngle (float) OutAngle (float) OutsideGain (float)
void | GetDirection | Dir (Vector)
bool | GetFileStreaming |
float | GetGain |
bool | GetLoopMode |
void | GetMinMaxDistance | MinDistance (float) MaxDistance (float) MaxDistanceBehavior (int)
void | GetOrientation | Dir (Vector) Up (Vector)
float | GetPan |
float | GetPitch |
int | GetPlayPosition |
int | GetPlayedMs |
void | GetPosition | Pos (Vector)
void | GetSound3DInformation | Pos (Vector) Dir (Vector) DistanceFromListener (float)
str | GetSoundFileName |
int | GetSoundFormat | Format (WaveFormat)
int | GetSoundLength |
CK_WAVESOUND_TYPE | GetType |
void | GetVelocity | Pos (Vector)
bool | IsPaused |
bool | IsPlaying |
void | Pause |
void | Play | FadeIn = 0.000000 (float) FinalGain = 1.000000 (float)
SoundHandle | PlayMinion | Background = true (bool) Ent = 0 (Entity3D) Position = 0 (Vector) Direction = 0 (Vector) MinDelay = 0.000000 (float) gain = 1.000000 (float)
void | PositionSound | Object (Entity3D) Position = 0 (Vector) Direction = 0 (Vector) Commit = false (bool)
void | Resume |
void | Rewind |
void | SetCone | InAngle (float) OutAngle (float) OutsideGain (float)
int | SetFileStreaming | Enabled (bool) RecreateSound = false (bool)
void | SetGain | Gain (float)
void | SetLoopMode | Enabled (bool)
void | SetMinMaxDistance | MinDistance (float) MaxDistance (float) MaxDistanceBehavior = 1 (int)
void | SetOrientation | Dir (Vector) Up (Vector)
void | SetPan | Pan (float)
void | SetPitch | Rate (float)
int | SetSoundFileName | const (str)
void | SetType | Type (CK_WAVESOUND_TYPE)
void | SetVelocity | Pos (Vector)
void | Stop | FadeOut = 0.000000 (float)

WebServerManager

Methods

Return | Function | Parameters
WebHandle | DownloadFile | iURL (str) iBlockSize = 10000 (int) iRelative (bool) iProxyLogin = (null) (str) iProxyPasswd = (null) (str) iServerLogin = (null) (str) iServerPasswd = (null) (str) iExtension = (null) (str)
void | EndDataRequest | iRequest (WebHandle)
void | EndDownloadRequest | iRequest (WebHandle)
WebHandle | GetDataFromUrl | iURL (str) iProxyLogin = (null) (str) iProxyPasswd = (null) (str) iServerLogin = (null) (str) iServerPasswd = (null) (str) iPostData = (null) (str)
void | GetDownloadProgress | iRequest (WebHandle) current (int) max (int)
String | GetRequestData | iRequest (WebHandle)
int | GetRequestError | iRequest (WebHandle)
int | GetRequestState | iRequest (WebHandle)
bool | ProcessRequestDataAsArray | iRequest (WebHandle) oArray (Array)


VSL

VSL <- SDK Binding Tables - Enumerations

CKAXIS

    CKAXIS_Z
    CKAXIS_Y
    CKAXIS_X

CKGRID_LAYER_FORMAT

    CKGRID_LAYER_FORMAT_NORMAL

CKKEYBOARD

    CKKEY_F3
    CKKEY_ESCAPE
    CKKEY_2
    CKKEY_3
    CKKEY_4
    CKKEY_5
    CKKEY_6
    CKKEY_7
    CKKEY_8
    CKKEY_9
    CKKEY_0
    CKKEY_MINUS
    CKKEY_EQUALS
    CKKEY_BACK
    CKKEY_TAB
    CKKEY_Q
    CKKEY_W
    CKKEY_E
    CKKEY_R
    CKKEY_T
    CKKEY_Y
    CKKEY_U
    CKKEY_I
    CKKEY_O
    CKKEY_P
    CKKEY_LBRACKET
    CKKEY_RBRACKET
    CKKEY_RETURN
    CKKEY_LCONTROL
    CKKEY_A
    CKKEY_S
    CKKEY_D
    CKKEY_F
    CKKEY_G
    CKKEY_H
    CKKEY_J
    CKKEY_K
    CKKEY_L
    CKKEY_SEMICOLON
    CKKEY_APOSTROPHE
    CKKEY_GRAVE
    CKKEY_LSHIFT
    CKKEY_BACKSLASH
    CKKEY_Z
    CKKEY_X
    CKKEY_C
    CKKEY_V
    CKKEY_B
    CKKEY_N
    CKKEY_M
    CKKEY_COMMA
    CKKEY_PERIOD
    CKKEY_SLASH
    CKKEY_RSHIFT
    CKKEY_MULTIPLY
    CKKEY_LMENU
    CKKEY_SPACE
    CKKEY_CAPITAL
    CKKEY_F1
    CKKEY_F2
    CKKEY_1
    CKKEY_F4
    CKKEY_F5
    CKKEY_F6
    CKKEY_F7
    CKKEY_F8
    CKKEY_F9
    CKKEY_F10
    CKKEY_NUMLOCK
    CKKEY_SCROLL
    CKKEY_NUMPAD7
    CKKEY_NUMPAD8
    CKKEY_NUMPAD9
    CKKEY_SUBTRACT
    CKKEY_NUMPAD4
    CKKEY_NUMPAD5
    CKKEY_NUMPAD6
    CKKEY_ADD
    CKKEY_NUMPAD1
    CKKEY_NUMPAD2
    CKKEY_NUMPAD3
    CKKEY_NUMPAD0
    CKKEY_DECIMAL
    CKKEY_F11
    CKKEY_F12
    CKKEY_F13
    CKKEY_F14
    CKKEY_F15
    CKKEY_KANA
    CKKEY_CONVERT
    CKKEY_NOCONVERT
    CKKEY_YEN
    CKKEY_NUMPADEQUALS
    CKKEY_CIRCUMFLEX
    CKKEY_AT
    CKKEY_COLON
    CKKEY_UNDERLINE
    CKKEY_KANJI
    CKKEY_STOP
    CKKEY_AX
    CKKEY_UNLABELED
    CKKEY_NUMPADENTER
    CKKEY_RCONTROL
    CKKEY_NUMPADCOMMA
    CKKEY_DIVIDE
    CKKEY_SYSRQ
    CKKEY_RMENU
    CKKEY_HOME
    CKKEY_UP
    CKKEY_PRIOR
    CKKEY_LEFT
    CKKEY_RIGHT
    CKKEY_END
    CKKEY_DOWN
    CKKEY_NEXT
    CKKEY_INSERT
    CKKEY_DELETE
    CKKEY_LWIN
    CKKEY_RWIN
    CKKEY_APPS

CKRST_TEXTURECAPS

    CKRST_TEXTURECAPS_SQUAREONLY
    CKRST_TEXTURECAPS_ALPHA
    CKRST_TEXTURECAPS_POW2
    CKRST_TEXTURECAPS_PERSPECTIVE

CKSPRITETEXT_ALIGNMENT

    CKSPRITETEXT_HCENTER
    CKSPRITETEXT_VCENTER
    CKSPRITETEXT_BOTTOM
    CKSPRITETEXT_TOP
    CKSPRITETEXT_RIGHT
    CKSPRITETEXT_LEFT
    CKSPRITETEXT_CENTER

CKSUPPORT

    CKSUPPORT_BACK
    CKSUPPORT_CENTER
    CKSUPPORT_FRONT

CK_2DENTITY_FLAGS

    CK_2DENTITY_CLIPTOCAMERAVIEW
    CK_2DENTITY_RESERVED3
    CK_2DENTITY_SIZECHANGED
    CK_2DENTITY_USESIZE
    CK_2DENTITY_VIRTOOLS
    CK_2DENTITY_USESRCRECT
    CK_2DENTITY_BACKGROUND
    CK_2DENTITY_NOTPICKABLE
    CK_2DENTITY_RATIOOFFSET
    CK_2DENTITY_USEHOMOGENEOUSCOORD
    CK_2DENTITY_POSITIONCHANGED
    CK_2DENTITY_UPDATEHOMOGENEOUSCOORD
    CK_2DENTITY_CLIPTOPARENT
    CK_2DENTITY_RESERVED0
    CK_2DENTITY_RESERVED1
    CK_2DENTITY_RESERVED2
    CK_2DENTITY_STICKLEFT
    CK_2DENTITY_STICKRIGHT
    CK_2DENTITY_STICKTOP
    CK_2DENTITY_STICKBOTTOM

CK_3DENTITY_FLAGS

    CK_3DENTITY_CAMERAIGNOREASPECT
    CK_3DENTITY_DISABLESKINPROCESS
    CK_3DENTITY_FRAME
    CK_3DENTITY_TARGETLIGHT
    CK_3DENTITY_TARGETCAMERA
    CK_3DENTITY_IGNOREANIMATION
    CK_3DENTITY_HIERARCHICALOBSTACLE
    CK_3DENTITY_UPDATELASTFRAME
    CK_3DENTITY_PARENTVALID
    CK_3DENTITY_ZORDERVALID
    CK_3DENTITY_PORTAL
    CK_3DENTITY_IKJOINTVALID
    CK_3DENTITY_PLACEVALID
    CK_3DENTITY_ENABLESKINOFFSET
    CK_3DENTITY_RESERVED0
    CK_3DENTITY_DUMMY
    CK_3DENTITY_CHARACTERDOPROCESS

CK_ANIMATION_FLAGS

    CKANIMATION_TRANSITION_LOOPIFEQUAL
    CKANIMATION_TRANSITION_WARPSTART
    CKANIMATION_CANBEBREAK
    CKANIMATION_ALIGNORIENTATION
    CKANIMATION_SECONDARYWARPER
    CKANIMATION_SUBANIMSSORTED
    CKANIMATION_TRANSITION_FROMWARPFROMCURRENT
    CKANIMATION_TRANSITION_TOSTART
    CKANIMATION_TRANSITION_WARPTOSTART
    CKANIMATION_TRANSITION_WARPTOBEST
    CKANIMATION_TRANSITION_WARPTOSAMEPOS
    CKANIMATION_TRANSITION_USEVELOCITY
    CKANIMATION_SECONDARY_LOOP
    CKANIMATION_SECONDARY_LASTFRAME
    CKANIMATION_ALLOWTURN
    CKANIMATION_TRANSITION_WARPSAMEPOS
    CKANIMATION_TRANSITION_ALL
    CKANIMATION_SECONDARY_ONESHOT
    CKANIMATION_SECONDARY_PRESET
    CKANIMATION_TRANSITION_PRESET
    CKANIMATION_SECONDARY_ALL
    CKANIMATION_SECONDARY_DOWARP
    CKANIMATION_SECONDARY_LOOPNTIMES
    CKANIMATION_TRANSITION_WARPBEST
    CKANIMATION_LINKTOFRAMERATE

CK_ANIMATION_TRANSITION_MODE

    CK_TRANSITION_USEVELOCITY
    CK_TRANSITION_LOOPIFEQUAL
    CK_TRANSITION_FROMWARPFROMCURRENT
    CK_TRANSITION_WARPTOSTART
    CK_TRANSITION_WARPTOBEST
    CK_TRANSITION_WARPTOSAMEPOS
    CK_TRANSITION_FROMANIMATION
    CK_TRANSITION_WARPMASK
    CK_TRANSITION_WARPSAMEPOS
    CK_TRANSITION_WARPBEST
    CK_TRANSITION_WARPSTART
    CK_TRANSITION_TOSTART
    CK_TRANSITION_FROMNOW

CK_ARRAYTYPE

    CKARRAYTYPE_PARAMETER
    CKARRAYTYPE_OBJECT
    CKARRAYTYPE_STRING
    CKARRAYTYPE_FLOAT
    CKARRAYTYPE_INT

CK_BINARYOPERATOR

    CKDIV
    CKMUL
    CKSUB
    CKADD

CK_BITMAP_SAVEOPTIONS

    IncludeOriginal
    UseGlobal
    ImageFormat
    External
    RawData

CK_BITMAP_SYSTEMCACHING

    CKBITMAP_DISCARD
    CKBITMAP_VIDEOSHADOW
    CKBITMAP_PROCEDURAL

CK_CLASSID

    CKCID_RENDEROBJECT
    CKCID_OBJECT
    CKCID_PARAMETEROPERATION
    CKCID_STATE
    CKCID_BEHAVIORLINK
    CKCID_BEHAVIOR
    CKCID_BEHAVIORIO
    CKCID_RENDERCONTEXT
    CKCID_KINEMATICCHAIN
    CKCID_SCENEOBJECT
    CKCID_OBJECTANIMATION
    CKCID_ANIMATION
    CKCID_KEYEDANIMATION
    CKCID_BEOBJECT
    CKCID_DATAARRAY
    CKCID_SCENE
    CKCID_LEVEL
    CKCID_PLACE
    CKCID_GROUP
    CKCID_SOUND
    CKCID_WAVESOUND
    CKCID_MIDISOUND
    CKCID_MATERIAL
    CKCID_TEXTURE
    CKCID_MESH
    CKCID_PATCHMESH
    CKCID_PARAMETERIN
    CKCID_2DENTITY
    CKCID_SPRITE
    CKCID_SPRITETEXT
    CKCID_3DENTITY
    CKCID_GRID
    CKCID_CURVEPOINT
    CKCID_SPRITE3D
    CKCID_CURVE
    CKCID_CAMERA
    CKCID_TARGETCAMERA
    CKCID_LIGHT
    CKCID_TARGETLIGHT
    CKCID_CHARACTER
    CKCID_3DOBJECT
    CKCID_BODYPART
    CKCID_PARAMETER
    CKCID_PARAMETERLOCAL
    CKCID_PARAMETERVARIABLE
    CKCID_PARAMETEROUT
    CKCID_INTERFACEOBJECTMANAGER
    CKCID_CRITICALSECTION
    CKCID_LAYER
    CKCID_PROGRESSIVEMESH
    CKCID_SYNCHRO
    CKCID_MAXCLASSID

CK_COMPOPERATOR

    CKGREATEREQUAL
    CKGREATER
    CKLESSEREQUAL
    CKLESSER
    CKNOTEQUAL
    CKEQUAL

CK_FLOORGEOMETRY

    CKFLOOR_BOX
    CKFLOOR_FACES

CK_FLOORNEAREST

    CKFLOOR_UP
    CKFLOOR_DOWN
    CKFLOOR_NOFLOOR

CK_FRAMERATE_LIMITS

    CK_FRAMERATE_MASK
    CK_FRAMERATE_LIMIT
    CK_FRAMERATE_FREE
    CK_FRAMERATE_SYNC
    CK_BEHRATE_MASK
    CK_BEHRATE_LIMIT
    CK_BEHRATE_SYNC
    CK_RATE_NOP

CK_GEOMETRICPRECISION

    CKCOLLISION_FACE
    CKCOLLISION_BOX
    CKCOLLISION_NONE

CK_GRIDORIENTATION

    CKGRID_YZ
    CKGRID_XY
    CKGRID_XZ
    CKGRID_FREE

CK_IMPACTINFO

    TOUCHINGVERTEX
    OBSTACLETOUCHED
    TOUCHEDFACE
    TOUCHINGFACE
    TOUCHEDVERTEX
    SUBOBSTACLETOUCHED
    IMPACTWORLDMATRIX
    IMPACTPOINT
    IMPACTNORMAL
    OWNERENTITY

CK_MOUSEBUTTON

    CK_MOUSEBUTTON_4
    CK_MOUSEBUTTON_MIDDLE
    CK_MOUSEBUTTON_RIGHT
    CK_MOUSEBUTTON_LEFT

CK_OBJECTANIMATION_FLAGS

    CK_OBJECTANIMATION_WARPER
    CK_OBJECTANIMATION_MERGED
    CK_OBJECTANIMATION_IGNORESCALEROT
    CK_OBJECTANIMATION_IGNOREMORPH
    CK_OBJECTANIMATION_IGNORESCALE
    CK_OBJECTANIMATION_IGNOREROT
    CK_OBJECTANIMATION_IGNOREPOS
    CK_OBJECTANIMATION_RESERVED

CK_OBJECT_FLAGS

    CK_OBJECT_SINGLEACTIVITY
    CK_OBJECT_INTERFACEOBJ
    CK_OBJECT_INTERFACEMARK
    CK_OBJECT_FREEID
    CK_OBJECT_TOBEDELETED
    CK_OBJECT_NOTTOBESAVED
    CK_OBJECT_VISIBLE
    CK_OBJECT_NAMESHARED
    CK_OBJECT_DYNAMIC
    CK_OBJECT_HIERACHICALHIDE
    CK_OBJECT_UPTODATE
    CK_OBJECT_TEMPMARKER
    CK_OBJECT_ONLYFORFILEREFERENCE
    CK_OBJECT_NOTTOBEDELETED
    CK_OBJECT_APPDATA
    CK_OBJECT_PRIVATE
    CK_OBJECT_LOADSKIPBEOBJECT
    CK_OBJECT_NOTTOBELISTEDANDSAVED
    CK_PARAMETEROUT_SETTINGS
    CK_PARAMETEROUT_PARAMOP
    CK_PARAMETERIN_DISABLED
    CK_PARAMETERIN_THIS
    CK_PARAMETERIN_SHARED
    CK_PARAMETEROUT_DELETEAFTERUSE
    CK_OBJECT_PARAMMASK
    CK_BEHAVIORIO_IN
    CK_BEHAVIORIO_OUT
    CK_BEHAVIORIO_ACTIVE
    CK_OBJECT_IOTYPEMASK
    CK_OBJECT_IOMASK

CK_OBJECT_SHOWOPTION

    CKHIERARCHICALHIDE
    CKSHOW
    CKHIDE

CK_PATCHMESH_FLAGS

    CK_PATCHMESH_AUTOSMOOTH

CK_PATCH_FLAGS

    CK_PATCH_QUAD
    CK_PATCH_TRI

CK_PATHMANAGER_CATEGORY

    SOUND_PATH_IDX
    DATA_PATH_IDX
    BITMAP_PATH_IDX

CK_RAYINTERSECTION

    CKRAYINTERSECTION_FIRSTCONTACT
    CKRAYINTERSECTION_IGNOREALPHA
    CKRAYINTERSECTION_SEGMENT
    CKRAYINTERSECTION_DEFAULT

CK_RENDER_FLAGS

    CK_RENDER_CLEARVIEWPORT
    CK_RENDER_BACKGROUNDSPRITES
    CK_RENDER_USECAMERARATIO
    CK_RENDER_CLEARZ
    CK_RENDER_CLEARBACK
    CK_RENDER_CLEARSTENCIL
    CK_RENDER_DOBACKTOFRONT
    CK_RENDER_DEFAULTSETTINGS
    CK_RENDER_FOREGROUNDSPRITES
    CK_RENDER_WAITVBL
    CK_RENDER_SKIPDRAWSCENE
    CK_RENDER_DONOTUPDATEEXTENTS
    CK_RENDER_SKIP3D
    CK_RENDER_OPTIONSMASK
    CK_RENDER_PLAYERCONTEXT
    CK_RENDER_USECURRENTSETTINGS

CK_SCENEOBJECTACTIVITY_FLAGS

    CK_SCENEOBJECTACTIVITY_DONOTHING
    CK_SCENEOBJECTACTIVITY_DEACTIVATE
    CK_SCENEOBJECTACTIVITY_ACTIVATE
    CK_SCENEOBJECTACTIVITY_SCENEDEFAULT

CK_SCENEOBJECTRESET_FLAGS

    CK_SCENEOBJECTRESET_DONOTHING
    CK_SCENEOBJECTRESET_RESET
    CK_SCENEOBJECTRESET_SCENEDEFAULT

CK_SECONDARYANIMATION_FLAGS

    CKSECONDARYANIMATION_FROMANIMATION
    CKSECONDARYANIMATION_DOWARP
    CKSECONDARYANIMATION_LOOPNTIMES
    CKSECONDARYANIMATION_LASTFRAME
    CKSECONDARYANIMATION_LOOP
    CKSECONDARYANIMATION_ONESHOT

CK_TEXTURE_SAVEOPTIONS

    CKTEXTURE_INCLUDEORIGINALFILE
    CKTEXTURE_USEGLOBAL
    CKTEXTURE_IMAGEFORMAT
    CKTEXTURE_EXTERNAL
    CKTEXTURE_RAWDATA

CK_WAVESOUND_TYPE

    CK_WAVESOUND_POINT
    CK_WAVESOUND_BACKGROUND

CloudAttributeType

    ATTRIBUT_ENUM
    ATTRIBUT_FLOAT
    ATTRIBUT_INT

PGUID

    GUID_DIRECTION
    GUID_NONE
    GUID_FLOAT
    GUID_ANGLE
    GUID_PERCENTAGE
    GUID_INT
    GUID_KEY
    GUID_BOOL
    GUID_STRING
    GUID_RECT
    GUID_VECTOR
    GUID_2DVECTOR
    GUID_QUATERNION
    GUID_EULERANGLES
    GUID_MATRIX
    GUID_COLOR
    GUID_BOX
    GUID_OBJECTARRAY
    GUID_OBJECT
    GUID_BEOBJECT
    GUID_MESH
    GUID_MATERIAL
    GUID_TEXTURE
    GUID_SPRITE
    GUID_3DENTITY
    GUID_CURVEPOINT
    GUID_LIGHT
    GUID_TARGETLIGHT
    GUID_ID
    GUID_CAMERA
    GUID_TARGETCAMERA
    GUID_SPRITE3D
    GUID_OBJECT3D
    GUID_BODYPART
    GUID_CHARACTER
    GUID_CURVE
    GUID_2DCURVE
    GUID_LEVEL
    GUID_PLACE
    GUID_GROUP
    GUID_2DENTITY
    GUID_RENDEROBJECT
    GUID_SPRITETEXT
    GUID_SOUND
    GUID_WAVESOUND
    GUID_MIDISOUND
    GUID_OBJECTANIMATION
    GUID_ANIMATION
    GUID_KINEMATICCHAIN
    GUID_SCENE
    GUID_BEHAVIOR
    GUID_MESSAGE
    GUID_SYNCHRO
    GUID_CRITICALSECTION
    GUID_STATE
    GUID_ATTRIBUTE
    GUID_CLASSID
    GUID_VOIDBUF
    GUID_BLENDMODE
    GUID_FILTERMODE
    GUID_BLENDFACTOR
    GUID_FILLMODE
    GUID_LITMODE
    GUID_SHADEMODE
    GUID_GLOBALEXMODE
    GUID_ZFUNC
    GUID_ADDRESSMODE
    GUID_WRAPMODE
    GUID_3DSPRITEMODE
    GUID_FOGMODE
    GUID_LIGHTTYPE
    GUID_SPRITEALIGN
    GUID_SCRIPT
    GUID_LAYERTYPE
    GUID_STATECHUNK
    GUID_DATAARRAY
    GUID_COMPOPERATOR
    GUID_BINARYOPERATOR
    GUID_SETOPERATOR
    GUID_SPRITETEXTALIGNMENT
    GUID_OBSTACLEPRECISION
    GUID_OBSTACLEPRECISIONBEH
    GUID_OBSTACLE
    GUID_PATCHMESH
    GUID_POINTER
    GUID_ENUMS
    GUID_STRUCTS
    GUID_FLAGS
    GUID_FILTER
    GUID_TIME
    GUID_OLDTIME
    GUID_COPYDEPENDENCIES
    GUID_DELETEDEPENDENCIES
    GUID_SAVEDEPENDENCIES
    GUID_REPLACEDEPENDENCIES
    GUID_SCENEACTIVITYFLAGS
    GUID_SCENEOBJECT
    GUID_SCENERESETFLAGS
    GUID_ARRAYTYPE
    GUID_RENDEROPTIONS
    GUID_PARAMETERTYPE
    GUID_MATERIALEFFECT
    GUID_TEXGENEFFECT
    GUID_TEXGENREFEFFECT
    GUID_COMBINE2TEX
    GUID_COMBINE3TEX
    GUID_BUMPMAPPARAM
    GUID_TEXCOMBINE
    GUID_PIXELFORMAT
    GUID_AXIS
    GUID_SUPPORT
    GUID_BITMAP_SYSTEMCACHING
    GUID_OLDMESSAGE
    GUID_OLDATTRIBUTE

QuatPart

    Quat_W
    Quat_Z
    Quat_Y
    Quat_X

VXBLEND_MODE

    VXBLEND_INVDESTALPHA
    VXBLEND_ZERO
    VXBLEND_SRCCOLOR
    VXBLEND_INVSRCCOLOR
    VXBLEND_SRCALPHA
    VXBLEND_INVSRCALPHA
    VXBLEND_DESTALPHA
    VXBLEND_ONE
    VXBLEND_DESTCOLOR
    VXBLEND_INVDESTCOLOR
    VXBLEND_SRCALPHASAT
    VXBLEND_BOTHSRCALPHA
    VXBLEND_BOTHINVSRCALPHA
    VXBLEND_MASK

VXBUFFER_TYPE

    VXBUFFER_STENCILBUFFER
    VXBUFFER_ZBUFFER
    VXBUFFER_BACKBUFFER

VXCHANNEL_FLAGS

    VXCHANNEL_LAST
    VXCHANNEL_RESERVED1
    VXCHANNEL_MONO
    VXCHANNEL_NOTLIT
    VXCHANNEL_SAMEUV
    VXCHANNEL_ACTIVE

VXCLIP_FLAGS

    VXCLIP_ALL
    VXCLIP_BACKFRONT
    VXCLIP_BACK
    VXCLIP_FRONT
    VXCLIP_BOTTOM
    VXCLIP_TOP
    VXCLIP_RIGHT
    VXCLIP_LEFT

VXCMPFUNC

    VXCMP_GREATER
    VXCMP_MASK
    VXCMP_ALWAYS
    VXCMP_GREATEREQUAL
    VXCMP_NOTEQUAL
    VXCMP_LESSEQUAL
    VXCMP_EQUAL
    VXCMP_LESS
    VXCMP_NEVER

VXCURSOR_POINTER

    VXCURSOR_LINKSELECT
    VXCURSOR_MOVE
    VXCURSOR_BUSY
    VXCURSOR_NORMALSELECT

VXFILL_MODE

    VXFILL_SOLID
    VXFILL_WIREFRAME
    VXFILL_POINT

VXFOG_MODE

    VXFOG_LINEAR
    VXFOG_EXP2
    VXFOG_EXP
    VXFOG_NONE

VXLIGHT_TYPE

    VX_LIGHTPARA
    VX_LIGHTDIREC
    VX_LIGHTSPOT
    VX_LIGHTPOINT

VXMESH_FLAGS

    VXMESH_COLOR_CHANGED
    VXMESH_BOUNDINGUPTODATE
    VXMESH_OPTIMIZED
    VXMESH_HASTRANSPARENCY
    VXMESH_PRELITMODE
    VXMESH_WRAPU
    VXMESH_WRAPV
    VXMESH_FORCETRANSPARENCY
    VXMESH_TRANSPARENCYUPTODATE
    VXMESH_UV_CHANGED
    VXMESH_NORMAL_CHANGED
    VXMESH_VISIBLE
    VXMESH_POS_CHANGED
    VXMESH_HINTDYNAMIC
    VXMESH_GENNORMALS
    VXMESH_PROCEDURALUV
    VXMESH_PROCEDURALPOS
    VXMESH_STRIPIFY
    VXMESH_MONOMATERIAL
    VXMESH_PM_BUILDNORM
    VXMESH_BWEIGHTS_CHANGED
    VXMESH_ALLFLAGS

VXMESH_LITMODE

    VX_LITMESH
    VX_PRELITMESH

VXSHADE_MODE

    VXSHADE_PHONG
    VXSHADE_GOURAUD
    VXSHADE_FLAT

VXSPRITE3D_TYPE

    (null)
    VXSPRITE3D_ORIENTABLE
    VXSPRITE3D_YROTATE
    VXSPRITE3D_XROTATE
    VXSPRITE3D_BILLBOARD

VXTEXTURE_ADDRESSMODE

    VXTEXTURE_ADDRESSMASK
    VXTEXTURE_ADDRESSMIRRORONCE
    VXTEXTURE_ADDRESSBORDER
    VXTEXTURE_ADDRESSCLAMP
    VXTEXTURE_ADDRESSMIRROR
    VXTEXTURE_ADDRESSWRAP

VXTEXTURE_BLENDMODE

    VXTEXTUREBLEND_MODULATEMASK
    VXTEXTUREBLEND_COPY
    VXTEXTUREBLEND_MODULATE
    VXTEXTUREBLEND_MODULATEALPHA
    VXTEXTUREBLEND_DECALMASK
    VXTEXTUREBLEND_MASK
    VXTEXTUREBLEND_MAX
    VXTEXTUREBLEND_DOTPRODUCT3
    VXTEXTUREBLEND_ADD
    VXTEXTUREBLEND_DECALALPHA
    VXTEXTUREBLEND_DECAL

VXTEXTURE_FILTERMODE

    VXTEXTUREFILTER_MASK
    VXTEXTUREFILTER_ANISOTROPIC
    VXTEXTUREFILTER_LINEARMIPLINEAR
    VXTEXTUREFILTER_LINEARMIPNEAREST
    VXTEXTUREFILTER_MIPLINEAR
    VXTEXTUREFILTER_MIPNEAREST
    VXTEXTUREFILTER_LINEAR
    VXTEXTUREFILTER_NEAREST

VXTEXTURE_WRAPMODE

    VXTEXTUREWRAP_UV
    VXTEXTUREWRAP_V
    VXTEXTUREWRAP_U
    VXTEXTUREWRAP_NONE

VXWRAP_MODE

    VXWRAP_MASK
    VXWRAP_T
    VXWRAP_S
    VXWRAP_V
    VXWRAP_U

VX_EFFECT

    VXEFFECT_MASK
    VXEFFECT_3TEXTURES
    VXEFFECT_2TEXTURES
    VXEFFECT_DP3
    VXEFFECT_BUMPENV
    VXEFFECT_TEXGENREF
    VXEFFECT_TEXGEN
    VXEFFECT_NONE

VX_MOVEABLE_FLAGS

    VX_MOVEABLE_RENDERFIRST
    VX_MOVEABLE_PICKABLE
    VX_MOVEABLE_UPTODATE
    VX_MOVEABLE_USERBOX
    VX_MOVEABLE_EXTENTSUPTODATE
    VX_MOVEABLE_BOXVALID
    VX_MOVEABLE_RENDERLAST
    VX_MOVEABLE_HASMOVED
    VX_MOVEABLE_WORLDALIGNED
    VX_MOVEABLE_NOZBUFFERWRITE
    VX_MOVEABLE_VISIBLE
    VX_MOVEABLE_NOZBUFFERTEST
    VX_MOVEABLE_INVERSEWORLDMATVALID
    VX_MOVEABLE_DONTUPDATEFROMPARENT
    VX_MOVEABLE_INDIRECTMATRIX
    VX_MOVEABLE_ZBUFONLY
    VX_MOVEABLE_STENCILONLY
    VX_MOVEABLE_HIERARCHICALHIDE
    VX_MOVEABLE_CHARACTERRENDERED
    VX_MOVEABLE_RESERVED2

VX_PIXELFORMAT

    _24_BGR888
    UNKNOWN_PF
    _32_RGB888
    _24_RGB888
    _16_RGB565
    _16_RGB555
    _16_ARGB1555
    _16_ARGB4444
    _8_RGB332
    _8_ARGB2222
    _32_ABGR8888
    _32_RGBA8888
    _32_BGRA8888
    _32_BGR888
    _32_ARGB8888
    _16_BGR565
    _16_BGR555
    _16_ABGR1555
    _16_ABGR4444
    _DXT1
    _DXT2
    _DXT3
    _DXT4
    _DXT5
    _16_V8U8
    _32_V16U16
    _16_L6V5U5
    _32_X8L8V8U8

WEB_MANAGER_ERROR

    WSME_NETWORKINITFAILED
    WSME_NOAUTH
    WSME_TMPFILE
    WSME_THREAD
    WSME_URL
    WSME_STOPPED
    WSME_NETWORKREAD
    WSME_INVALIDDATA
    WSME_SERVERAUTH
    WSME_PROXYAUTH
    WSME_ARRAY
    WSME_INTERNALERROR
    WSME_NOMANAGER
    WSME_NETWORK
    WSME_NOERROR

WEB_REQUEST_STATE

    WSMDR_FAILED
    WSMDR_FINISHED
    WSMDR_DOWNLOADING
    WSMDR_INITIALE


VSL

VSL <- SDK Binding Tables - Global Functions

Return | Function | Parameters
int | != | v1 (Vector) v2 (Vector)
int | != | v1 (Vector4) v2 (Vector4)
int | != | q1 (Quaternion) q2 (Quaternion)
int | != | r1 (Rect) r2 (Rect)
int | != | col1 (Color) col2 (Color)
bool | != | v1 (GUID) v2 (GUID)
Vector | * | v (Vector) s (float)
Vector | * | s (float) v (Vector)
Vector | * | v1 (Vector) v2 (Vector)
Vector4 | * | v (Vector4) s (float)
Vector4 | * | s (float) v (Vector4)
Vector4 | * | v1 (Vector4) v2 (Vector4)
Vector2D | * | f (float) v (Vector2D)
Vector | * | m (Matrix) v (Vector)
Vector4 | * | m (Matrix) v (Vector4)
Vector | * | m (Vector) v (Matrix)
Vector4 | * | m (Vector4) v (Matrix)
Quaternion | * | f (float) q (Quaternion)
Quaternion | * | q (Quaternion) f (float)
Color | * | col1 (Color) col2 (Color)
Color | * | col (Color) s (float)
Vector | + | v (Vector)
Vector | + | v1 (Vector) v2 (Vector)
Vector4 | + | v (Vector4)
Vector4 | + | v1 (Vector4) v2 (Vector4)
Color | + | col1 (Color) col2 (Color)
Vector | - | v (Vector)
Vector | - | v1 (Vector) v2 (Vector)
Vector4 | - | v (Vector4)
Vector4 | - | v1 (Vector4) v2 (Vector4)
Color | - | col1 (Color) col2 (Color)
Plane | - | p (Plane)
Vector | / | v (Vector) s (float)
Vector | / | v1 (Vector) v2 (Vector)
Vector4 | / | v (Vector4) s (float)
Vector4 | / | v1 (Vector4) v2 (Vector4)
Vector2D | / | f (float) v (Vector2D)
Color | / | col1 (Color) col2 (Color)
int | < | v1 (Vector) v2 (Vector)
bool | < | v1 (GUID) v2 (GUID)
int | <= | v1 (Vector) v2 (Vector)
bool | <= | v1 (GUID) v2 (GUID)
int | == | v1 (Vector) v2 (Vector)
int | == | v1 (Vector4) v2 (Vector4)
int | == | q1 (Quaternion) q2 (Quaternion)
int | == | r1 (Rect) r2 (Rect)
int | == | col1 (Color) col2 (Color)
bool | == | v1 (GUID) v2 (GUID)
bool | > | v1 (GUID) v2 (GUID)
bool | >= | v1 (GUID) v2 (GUID)
Vector | Absolute | iiV1 (Vector)
Vector | CrossProduct | iiV1 (Vector) iiV2 (Vector)
float | DotProduct | iiV1 (Vector) iiV2 (Vector)
float | DotProduct | p (Quaternion) q (Quaternion)
GUID | GetCollisionManagerGuid |
GUID | GetFloorManagerGuid |
GUID | GetGUID | iGuidEnum (PGUID)
GUID | GetInputManagerGuid |
int | GetTime |
str | GetTimeAndDate |
GUID | GetWebServerManagerGuid |
Vector | Interpolate | step (float) v1 (Vector) v2 (Vector)
float | InvMagnitude | iV (Vector)
float | InvSquareMagnitude | iV (Vector)
int | Is2Power | iPow (int)
float | Magnitude | iV (Vector)
float | Magnitude | q (Quaternion)
float | Max | v (Vector)
Vector | Maximize | v1 (Vector) v2 (Vector)
float | Min | v (Vector)
Vector | Minimize | v1 (Vector) v2 (Vector)
int | Near2Power | iPow (int)
Vector | Normalize | iV (Vector)
Vector | Reflect | iiV1 (Vector) iiV2 (Vector)
Vector | Rotate | iM (Matrix) iPt (Vector)
Vector | Rotate | iV (Vector) (Vector) (float)
float | SquareMagnitude | iV (Vector)
void | Vx3DDecomposeMatrix | iStep (float) oMat (Matrix) iMat1 (Matrix) iMat2 (Matrix)
void | Vx3DDecomposeMatrixTotal | iStep (float) oMat (Matrix) iMat1 (Matrix) iMat2 (Matrix)
void | Vx3DInterpolateMatrix | iStep (float) oMat (Matrix) iMat1 (Matrix) iMat2 (Matrix)
void | Vx3DInterpolateMatrixNoScale | iStep (float) oMat (Matrix) iMat1 (Matrix) iMat2 (Matrix)
void | Vx3DInverseMatrix | oMat (Matrix) iMat (Matrix)
float | Vx3DMatrixDeterminant | iMat (Matrix)
void | Vx3DMatrixFromEulerAngles | oMat (Matrix) eax (float) eay (float) eaz (float)
void | Vx3DMatrixFromRotation | oMat (Matrix) iV (Vector) iValue (float)
void | Vx3DMatrixFromRotationAndOrigin | oMat (Matrix) iVector (Vector) iOrigin (Vector) iValue (float)
void | Vx3DMatrixIdentity | mat (Matrix)
void | Vx3DMatrixToEulerAngles | iMat (Matrix) eax (float) eay (float) eaz (float)
void | Vx3DMultiplyMatrix | oMat (Matrix) iMat1 (Matrix) iMat2 (Matrix)
void | Vx3DMultiplyMatrix4 | oMat (Matrix) iMat1 (Matrix) iMat2 (Matrix)
void | Vx3DMultiplyMatrixVector | oV (Vector) iMat (Matrix) iV (Vector)
void | Vx3DMultiplyMatrixVector4 | oV (Vector4) iMat (Matrix) iV (Vector4)
void | Vx3DMultiplyMatrixVector4 | oV (Vector4) iMat (Matrix) iV (Vector)
void | Vx3DMultiplyMatrixVectorMany | oV (Vector) iMat (Matrix) iV (Vector) iCount (int) iStride (int)
void | Vx3DRotateVector | oV (Vector) iMat (Matrix) iV (Vector)
void | Vx3DRotateVectorMany | oV (Vector) iMat (Matrix) iV (Vector) iCount (int) iStride (int)
float | abs | f (float)
float | acos | f (float)
int | and | iValue1 (int) iValue2 (int)
float | asin | f (float)
float | atan | f (float)
float | atan2 | f1 (float) f2 (float)
float | ceil | f (float)
int | ceili | f (float)
float | cos | f (float)
float | cosh | f (float)
void | div | iNumer (int) iDenom (int) oQuot (int) oRemain (int)
float | exp | f (float)
float | floor | f (float)
int | floori | f (float)
float | log | f (float)
float | log10 | f (float)
float | max | iValue1 (float) iValue2 (float)
float | max | iValue1 (float) iValue2 (float) iValue3 (float)
int | max | iValue1 (int) iValue2 (int)
int | max | iValue1 (int) iValue2 (int) iValue3 (int)
ptr | memcpy | Dest (ptr) iSrc (ptr) Count (int)
ptr | memset | Dest (ptr) iValue (int) Count (int)
float | min | iValue1 (float) iValue2 (float)
float | min | iValue1 (float) iValue2 (float) iValue3 (float)
int | min | iValue1 (int) iValue2 (int)
int | min | iValue1 (int) iValue2 (int) iValue3 (int)
void | minmax | iValue1 (float) iValue2 (float) oMin (float) oMax (float)
void | minmax | iValue1 (float) iValue2 (float) oMin (float) oMed (float) oMax (float)
void | minmax | iValue1 (float) iValue2 (float) iValue3 (float) oMin (float) oMax (float)
void | minmax | iValue1 (float) iValue2 (float) iValue3 (float) oMin (float) oMed (float) oMax (float)
void | minmax | iValue1 (int) iValue2 (int) oMin (int) oMax (int)
void | minmax | iValue1 (int) iValue2 (int) oMin (int) oMed (int) oMax (int)
void | minmax | iValue1 (int) iValue2 (int) iValue3 (int) oMin (int) oMax (int)
void | minmax | iValue1 (int) iValue2 (int) iValue3 (int) oMin (int) oMed (int) oMax (int)
float | mod | f (float)
int | not | iValue (int)
int | or | iValue1 (int) iValue2 (int)
float | pow | f1 (float) f2 (float)
int | rand |
float | randf |
float | randf2 |
float | randg | iMean (float) iDev (float)
int | randi | iMin (int) iMax (int)
float | randu | iMean (float) iDev (float)
int | rol | iValue (int) iDecal (int)
int | ror | iValue (int) iDecal (int)
int | roundi | f (float)
int | shl | iValue (int) iDecal (int)
int | shr | iValue (int) iDecal (int)
float | sin | f (float)
float | sinh | f (float)
float | sqrt | f (float)
void | swap | iValue1 (float) iValue2 (float)
void | swap | iValue1 (int) iValue2 (int)
float | tan | f (float)
float | tanh | f (float)
int | xor | iValue1 (int) iValue2 (int)


Shaders

Virtools Shaders

Introduction

Introduction to Shaders
Shaders Inside Virtools
- Rendering Pipeline Overview
- DirectX 9.0 High-Level Shader Language
- Introducing the Shader Editor
- Passing Parameters To Shaders
- Shader Building Blocks and Scriptable Rendering
Getting Started
- Prerequisites
- Sample 1: Basic
- Sample 2: Light and Texture
- Sample 3: Vertex Shader

Reference

HLSL Reference
 Parameters
 Shader Editor
 Scriptable Rendering

Appendix

FAQ
Recommendations
 Troubleshooting
 Shader Compliant Hardware
 Glossary

Shader Sample Compositions

You will find many shader sample compositions in the Virtools Minisite (accessible from the Start menu).

The CMO files are located in Dev's Documentation folder (Cmos\TechnicalSamples\Shaders), categorized according to subject and complexity.

Note: some of them require the Virtools Resources to be open.


Introduction to Shaders

The Origins of Shaders
What is a Shader?
Shader Languages

The Origins of Shaders

Before the invention of 3D cards, programmers computed 3D renderings using only CPU instructions and system memory, because there was no other choice. Nowadays, this method may seem obsolete, but it still provides a great degree of flexibility and control. These "handmade" algorithms are used to produce voxels, soft shadows, ray tracings, exotic projections, screen transitions, pixel deformations, etc. They can provide a very personalized aesthetic touch to end productions, but they consume a large amount of CPU processing time.

While pre-calculated applications (e.g. not in real-time) continued using CPU instructions to maintain this flexibility and control, Pixar invented Renderman - a standard way to describe a 3D scene through Shaders - in the late 1980's.

The real-time 3D industry for its part, started building specialized chipsets (GPU - Graphic Processor Unit) meant to relieve the CPU from computing most common 3D tasks (flat shading, gouraud shading, perspective, texture mapping and some blending operations). Many of those chipsets made the success of SGI workstations, whose technology quickly trickled down to the game industry via 3D card manufacturers like 3dfx, NVidia and ATI.

Until recently, the main drawback of these inexpensive 3D cards was that rendering algorithms were limited to the hard-coded functions (called Fixed-Functions - used in the Fixed-Pipeline) implemented by card manufacturers. This constraint is one of the reasons many 3D games look and feel alike.

Increasing technological power (and frustration) has prompted 3D card manufacturers to build a Programmable-Pipeline within their chipset, bringing back flexibility in real-time rendering algorithms. This effectively means that certain Shader rendering techniques once exclusively reserved for precalculated images are now possible in real-time.

What is a Shader?

A Shader is a small piece of code that describes the way a surface is rendered (e.g.: shader language for Quake surfaces, or Renderman shaders). Nowadays (and in Dev), a Shader is a small piece of code executed by the GPU (on certain 3D graphics cards) for each vertex and/or each pixel, hence the terms Vertex Shaders and Pixel Shaders.

A Shader can contain three very distinct parts:

  1. States: This portion defines the states of Fixed-Pipeline variables like the material's colors, material's texture or blending options, and also allows some predefined 3D transformations, as well as 2D texture coordinate transformations called TexGen (i.e. environment mapping).
    - States are the basic way to describe a material. States are not executed for each vertex, nor are they for each pixel, but set only once per material/object.
    - Programmers need to understand States in order to fully master Shaders (See Shaders Inside Virtools > DirectX 9.0 High-Level Shader Language).
  2. Vertex Shader Instructions: This portion defines operations to execute on the vertices of the faces being rendered. This part is optional, and if omitted, the GPU will only use the States to define vertices' attributes (like vertex color, vertex normal or texture coordinate).
  3. Pixel Shader Instructions: This portion defines operations to execute on the pixels of the faces being rendered. This part is also optional, and if omitted, the GPU will only use the Render States to define pixels attributes (like pixel color, pixel blending, or depth value).

Shader Languages

Shaders were first coded using assembly language, and were used on the XBox and in DirectX 8; however, this approach proved to be a very unintuitive way of dealing with rendering algorithms.

Together, NVidia and Microsoft sought to remedy this situation by creating a C-like language that could be compiled into GPU assembly code. NVidia's first version was called Cg. Microsoft waited until DirectX 9's release to integrate this language in their HLSL (High Level Shader Language) - already used in DirectX 8 to describe shader effects and their assembly instructions. The combination of HLSL with this C-like language is called the Microsoft's Effect Format, which is equivalent to Cg Fx - an enhanced version of Cg created by NVidia afterwards.

HLSL has been retained as the integrated shader language within Virtools' 3D Engine.

Before going any further, you should be familiar with Virtools concept such as the Material Setup, 3D view rendering, and of course a general understanding of basic 3D Engine concepts (vertex, faces, pixels, rendering pipeline).

Ready? Now read Shaders Inside Virtools.


Shaders Inside Virtools

Introduction
 Rendering Pipeline Overview
DirectX 9.0 High-Level Shader Language
Introducing the Shader Editor
Passing Parameters To Shaders
Shader Building Blocks and Scriptable Rendering

Introduction

Microsoft's DirectX 9 High-Level Shading Language (also called HLSL) is the integrated shader language within Virtools' 3D Engine.

Before we dive in, we need to address terminology issues to clear up any possible confusion. DirectX 9 users should understand that the term Shader in Virtools has the same meaning as Effect in DirectX9 (and ShaderFx for NVidia).

In Virtools Dev, the word Effect is already used to refer to certain special Material fixed-functions like BumpMapping Effect, Environment Mapping Effect, etc. (Effects are accessed at the far right border of the material's setup) Therefore, in Virtools Dev, the term Effect refer to Virtools Material Effects, while the term Shader describe the new programmable vertex and pixel shaders.

We must stress the importance of distinguishing Effects from Shaders in Dev. The only similarity between Shaders and Effects comes from the fact they both override the material's attributes (diffuse, texture, blending modes...etc), but similarities end there.

Though they can both override a material's attributes, Effects in Virtools are completely unrelated to Shaders!

In Virtools Dev, Shaders exist only through the Shader Manager. This means that Shaders are not real CK objects and will not appear in the Level View; however, they can still be listed in the Material's Setup through the upper combo box as shown in the screenshot above.

Shaders have their own editor in the Virtools GUI interface - the Shader Editor - where shaders are all listed. The Shader Editor is where shaders can be created, deleted, edited, compiled, etc.

Once created inside the Shader Editor, a Shader can be used by several materials, while a material can only use one shader. To understand how Shaders are related to Materials in Virtools, consider the scene graph below. It explains the hierarchical order in which the Virtools 3D engine parses the scene elements in order to render them.

As you can see from the diagram above, Blue Water and Yellow Water materials use the same Water Fx Shader. On the other hand, Brick and Wood materials do not use any Shader; they are considered as standard materials by the 3D engine.

Important: While referencing the same exact Shader, two different materials (here Blue Water and Yellow Water) can still influence the Shader's appearance (in our case, the color). As discussed in the chapter Passing Parameters To Shaders, this is due to the fact that certain shader variables, called exposed variables, are able to be modified from the outside.

Rendering Pipeline Overview

When the Virtools' 3D Engine parses a scene graph and reaches a mesh's material - also called render group - it selects the appropriate rendering method depending on the material's type: Standard, Effect or Shader. The diagram below summarizes the 3 potential rendering paths.

Once a Shader is applied to a material, the material stops behaving like a standard material, and all material attributes (diffuse, texture, blending mode...etc) are skipped by the render engine. Note: some of these attributes can still be passed to the Shader (see the Shader's Automatic Parameters).

Virtools 3D engine, with help of its Shader Editor interface, lets a programmer/scripter focus on the shader's code creation without handling the heavy procedures surrounding shaders or dealing with DirectX 9; however, it is unlikely that a user could be initiated to shader programming without understanding the programmable pipeline execution steps inside a shader, so let's take an in-depth look inside the programming pipeline, to see what happens when a Shader is to be executed.

A Shader's Programmable Pipeline Execution Steps

Step 1: Execute the Default Shader
As shown in the diagram above, the shader rendering's first step is to execute the Default Shader. The Default Shader is automatically created and executes first to ensure all DirectX 9 states are initialized. The Default Shader allows you to only define certain specific Shader render states (that differ from their default values) without having to concern yourself with defining every state, and it ensures that certain states do not retain undefined values from the previous rendering.

Note: The Default Shader's secondary purpose is to be a reference program, so that users can take it as a model since all states and default values are listed, plus standard and additional Automatic Parameters (e.g. semantics). Also note that the Default Shader can be read in the Shader Editor but cannot be modified.

Step 2: Update the Exposed Shader Parameters
The shader rendering's second step is to update the exposed shader parameters. Virtools enables each material to customize its shader through exposed parameters. Those parameters act just like a shader's internal variables, but can also be modified by outside intervention - by the user (via the Material Setup or Shader BBs), or automatically by the 3D engine via material attributes and scene properties. (See Passing Parameters To Shaders).

Step 3: Shader Execution Process
The final and third step is the actual shader execution. A Shader is made of one or more Techniques: top level statement containing the rest of the Shader's instructions. Even if several Techniques are defined inside a Shader, one and only one Technique is used to render a Shader. Generally, it is the first Technique that the 3D card is capable of supporting.

A Technique is simply a container for at least one Pass. Every Pass inside a Technique is executed in the order of their definition. Basically Passes match rasterizing layers, and their layering produces the final rendering result.

Finally, each Pass contain State initializations. One of these States is reserved to point to a potential Vertex Shader (VS) function - the VS function is executed for all vertices of the currently rendered mesh's material - and one other is reserved to point to a potential Pixel Shader (PS) function; the PS function is executed for all pixels of the currently rasterized mesh's material. Note: Techniques, Passes, States, Vertex Shaders and Pixel Shaders are all described in the DirectX 9.0 High-Level Shader Language.

The diagram below summarizes the shader's execution process, and will also help us understand the Shader's program structure.

Now that we have a general view of how Shaders work and how they are executed, we are ready to learn about the Shader language itself: HLSL.

DirectX 9.0 High-Level Shader Language

In the previous chapter, we looked at the programmable pipeline execution steps that take place inside a Shader. DirectX 9.0's High-Level Shader Language (HLSL) is the language that lets the user define those steps, as well as the algorithms taking place within Vertex Shaders and Pixel Shaders. HLSL is based on the C language and was conceived in a joint effort by Microsoft and NVidia; therefore, you can easily translate an NVidia Cg/CgFx shader program into HLSL.

HLSL Program Structure

A HLSL program structure is very similar from one Shader to another. Before we take an in-depth look into HLSL's keywords and syntax, first take a look at this typical HLSL Shader program structure:

//
// Shader Program Structure
//
// Note: This Shader will compile but is not intended to be used,
// it just illustrates typical HLSL program block arrangement.

//--- Exposed Variables Declaration / Initialization
//...

//--- Static Variables Declaration / Initialization
//...

//--- Vertex Shader(s) Function(s) Definition
//...

//--- Pixel Shader(s) Function(s) Definition
//...

//--- Technique(s) Statement(s)
technique T1
{
    //--- Pass(es) Statement(s)
    pass P1
    {
        //--- States Initialization
        //...
    }
    /*
    ... There can be other Passes here
    */
}
/*
... There can be other Techniques here
*/

This standard HLSL program structure will also help you understand and reverse-engineer other Shader samples.

If you compare this pseudo-code with the shader execution diagram we described previously, you will notice the connection between execution steps and code blocks. Once again, that is because an HLSL program is nothing more than the formalized definition of a Shader's execution pipeline.

Let's translate all those abstract concepts seen until now into a concrete and fully commented Shader sample code, and take a tour of the main HLSL features.

//
// HLSL Shader Introduction
//
// Note: This Shader will compile but is not intended to be used,
// it illustrates HLSL keywords and syntax features.

//--- Exposed Parameters

///// Standard Automatic Parameters
float4x4 WorldView  : WORLDVIEW;
float4x4 Projection : PROJECTION;

///// Additional Automatic Parameters
texture tex : TEXTURE;
float4  col : DIFFUSE;

///// Manual Parameters
float4 intensity;
float3 lightPos <string type="3dentity";>;

Exposed parameters are set externally either by the 3D engine (Automatic) or by the user (Manual).

Standard Automatic Parameters: mapped to standard 3D engine variables (most CgFx and HLSL samples will use them).

Additional Automatic Parameters: mapped to special features proper to Virtools (material's texture, behavioral engine time..etc).

Note: WORLDVIEW, PROJECTION, TEXTURE and DIFFUSE are examples of semantics. (explained below)

Manual Parameters: mapped to exposed behavioral parameters the user can access and change via Shader BBs or the Material Setup.

Note: the second Manual Parameter has an Annotation invisible to the Shader that is used by the Virtools engine.

//--- Static Parameters
static float4 colFactor = {0.9, 0.9, 0.5, 1};
static float3 offsetVect = {1, 1, 0};
Static Parameters are not exposed, can only be used inside the shader program, and start with the static keyword.

//--- Vertex Shader
///// Output Structure
struct VS_OUTPUT {
    float4 Position : POSITION;
    float4 Diffuse  : COLOR;
};

///// Vertex Shader Function
VS_OUTPUT mainVS
  (
    float4 Position : POSITION,
    float3 Normal   : NORMAL,
    float2 TexCoord : TEXCOORD0
  )
{
    VS_OUTPUT Out = (VS_OUTPUT)0;
    /* ... VS Code */
    return Out;
}

The Vertex Shader part generally starts with the definition of a VS Output Structure. This structure defines what kind of vertex attributes will be computed by the Vertex Shader (here the vertex' position and vertex' color).

The Vertex Shader function computes vertex operations from given input vertex attributes, and returns as a result a VS Output Structure.

In most cases you do not need to define a VS Input Structure as input vertex' attributes are passed directly as parameters of the Vertex Shader function and associated with an intrinsic semantic.

Note: POSITION, NORMAL and TEXCOORD0 are examples of intrinsic semantics. (explained in Passing Parameters to Shaders)

//--- Pixel Shader Function
float4 mainPS( VS_OUTPUT VSOut ) : COLOR0
{
    float4 pixelColor = (1,1,1,1);
    /* ... PS Code */
    return pixelColor;
}

The Pixel Shader function generally takes as an input the previously defined VS Output Structure; just because the input pixel's attributes are interpolations of the output vertex attributes.

As a result, the pixel's shader function can returns a pixel color, a depth value, or a structure containing them both. The return function value is associated with a intrinsic semantic.

Note: COLOR0 is an example of an intrinsic semantic (explained in Passing Parameters to Shaders).

//--- Technique Statement
technique TStudy {
Beginning of Technique statement. In our case there's only one technique.

    //--- Pass Statement
    pass PStudy1 {
Beginning of the first Pass statement. In our case there are two passes.

      //--- Set Shader States
      VertexShader = compile vs_1_1 mainVS();
      PixelShader  = compile ps_1_1 mainPS();

      //--- Set Standard States
      Texture[0] = <tex>;
      // ...
      // ... etc
    }
Inside a Pass, States are set.

Shader States define if Vertex and Pixel Shaders are to be used in the pass and with which instructions set they should be compiled.

Standard States define all other states like the texture stage states, transform state, light states, material states, etc.

    pass PStudy2 {
      //--- Set Standard States
      Texture[0]       = NULL;
      AlphaBlendEnable = TRUE;
      SrcBlend         = ONE;
      DestBlend        = ONE;
      // ...
      // ... etc
    }
}

In our example we decided to define a second pass. This pass does not define vertex shader or pixel shader. It simply modifies some standard states.

Note: just a few states need to be modified; those differing from their pre-defined values set in the Default Shader.

Clarifying Language Concepts

About Automatic Parameters and Semantics
To define a variable as an Automatic Parameter (exposed) you need to add a Semantic at the end of the line.
Example: this is an automatic parameter because it has the WORLDVIEW semantic(identified in red)
float4x4 WorldView  : WORLDVIEW;

A semantic should not be associated with more than one variable. This is because a semantic defines a direct link between an existing 3D engine feature and a shader's variable.

About Static Parameters and Manual Parameters
A Static Parameter (not exposed) must be defined with the static prefix modifier, otherwise, it'll be consider as a Manual Parameter (exposed).

Example: this is a static parameter because of the static prefix
static float3 offsetVect = {1, 1, 0};

Example: this is a manual parameter
float4 intensity;

About Annotations

Manual parameters can also get an Annotation added at the end of their definition line. An annotation adds some information that is invisible to the Shader code but that may be relevant for the 3D/game engine.

Example: this is a manual parameter with an annotation
float3 lightPos <string type="3dentity";>;

Note: In some cases annotations can also be added to Passes or Techniques.

You can find additional information about HLSL, parameter's syntax and states here:

  • Parameters Reference
  • HLSL Reference > States
  • Microsoft DirectX 9 HLSL Reference

Introducing the Shader Editor

The Shader Editor provides the Virtools Dev interface for the Shader Manager. The Shader Editor is used to create, organize, edit, compile and delete Shaders. Shader code can be save to and loaded from ".fx" files. You can also use the Shader Editor to generate and see the Assembly code of a Shader function.

Below is an overview of Shader Editor features.

The Default Shader is present in the Shader List window and can be used for reference purposes, since your Shader will need to address States that differ from their default values. However, the Default Shader cannot be modified.

The Shader creation process follows a logical order:

  1. First create a shader (create icon).
  2. Insert variables declaration, states values and shader's code.
  3. Compile.
  4. Check that the code is correct with the help of the output window, technique/pass list and also the exposed parameter list.
  5. Assign it to a Material by selecting it in the Material Setup's shader combo box (the one we highlighted previously).
    Note: Details will be explained in Passing Parameters To Shaders or can be found in Material Setup > Shaders.

Shader Setup Miscellaneous:

  • The Shader Editor can be accessed through:
    • The top menu Editors > Shader Setup
    • The Material Setup's Shader Setup button
    • Right-Click in the 3D View on an object which material use a shader, and select Shader Setup.
  • The Parameter List and Technique/Pass List are refreshed after each compilation.
  • Automatic keyword completion is available when you hit Ctrl+Enter, e.g. this works for types, semantic, states, enums, etc.
  • You'll find in-depth information on the subject in the Shader Editor chapter.

Passing Parameters To Shaders

Passing parameters to a Shader means being able to modify a shader's "exposed" variables from the outside. As shown at the top of the previous shader execution diagram, exposed parameters are updated and transferred once per rendering just before the shader code gets executed.

Exposed Parameters, can either be Automatic Parameters or Manual Parameters.

Automatic

Values of Automatic Parameters are modified automatically by Virtools' 3D Engine once per rendering.
Examples: World matrix will take as a value the world matrix of the object currently being rendered, and the View matrix will take as a value the view matrix of the camera currently rendering the scene.
Among Automatic Parameters you'll find non-standard ones like the Time parameter linked to the Virtools' behavioral time or the Power linked to the material's specular power. All semantics used to define a variable as being Automatic are listed at the top of the default shader source code.

Manual

Values of Manual Parameters are not modified automatically. Instead, they are linked to real Virtools parameters. Those parameters are attached to each material linked to Shader. This is the reason why Manual Parameters can be modified from inside the Material Setup (or with Shader BBs like Set Shader Parameters), and why the same shader is able to render differently depending on the material used on an object (e.g. Blue Water and Yellow Water in the scene graph diagram).

Working with Manual Parameters in the Material Setup
Once a Shader is selected in the shader combo box of the Material Setup, a button named Shader Params appears on the right of the combo box.

Once clicked, this button opens the Shader Params modeless dialog box. This dialog box contains two permanent parameters:

  1. Technique - Lets the user choose which technique should be executed by this shader.
  2. Find Next Valid Technique- Lets the user decide whether that following techniques should be used as a replacement if the chosen technique isn't supported by the hardware.

once a shader is selected, the Shader Params button appears on the right

Important: All other parameters of the Shader Params dialog box are linked to the exposed Manual variables defined in the Shader program.

Note: This dialog box is modeless, it means the dialog does not need to be closed in order to give focus to the rest of the interface. Furthermore, if you add new manual exposed parameters in the shader program and compile it, the Shader Params dialog box will update automatically to reflect the changes.

Other: Intrinsic

It is worth mentioning the last kind of variable transfer; it is the intrinsic transfer between shader functions. While we will not go into much detail here, intrinsic parameters are not an exposed process like Automatic and Manual Parameters. Instead, an Intrinsic Semantic is intrinsic to shader functions (pixel or vertex shader function), and the user can only decide which variables will be transferred between functions, using the same kind of semantic syntax as for Automatic Parameters. If you look at the previously written Vertex Shader function and Pixel Shader function, there are examples of intrinsic semantics.

Find additional information on parameters and their syntax in the Parameters chapter.

Shader Building Blocks and Scriptable Rendering

Considering all the concepts we've covered, you are ready to roll up your sleeves and start using Shaders. But before that, be aware of the various Shaders Building Blocks features. They are the interactive way to control the Shader Manager, but also a unique way to create Post-Processing Effects.

Shader BBs are organized in two categories:

General:

  • Set Shader Parameters: Modifies exposed parameters value on-the-fly.
  • Set Shader Technique: Switchs between techniques on-the-fly.
  • Build Tangent Space: Flags the mesh as needing tangent space in order to compute bump mapping and other "tangent-eaters" correctly.
  • Get Shader Capabilities: Gets hardware capabilities related to shaders.

Rendering:

  • Render Scene In RT View: Renders the whole scene into a Render Target View (RT View).
  • Combine RT Views: Renders a combination of Render Targets Views into a destinaion Render Target View (can be the screen).

Render Target and Render Target View concept:

A Render Target is just an internal texture where rendering is supposed to be done, while a Render Target View (also called RT View in Virtools) is the combination of a Render Target and a Viewport (a rectangle inside the Render Target).

You can find documentation on Shader building blocks and learn about using them to achieve more complex effects with render targets:

  • Scriptable Rendering
  • Shaders Building Blocks Online Reference
To get off on the path, be sure to read the Getting Started to walkthrough you first Shader.


Shaders - Getting Started

Getting Started

Prerequisites

Sample 1: Basic
Sample 2: Light and Texture
Sample 3: Vertex Shader

Prerequisites

Once you have read Shaders Inside Virtools, you are ready to dive in, but first you need to make sure that the prerequisites are covered as well:

  • DirectX 9 is installed
     Shaders in Virtools are based exclusively on the DirectX 9 API and its high-level shader language (HLSL). DirectX 9 (or higher) must be installed on your computer; otherwise, you will not be able to compile Shaders in the Virtools Shader Editor or see any shader rendering.
  • DirectX 9 is selected as the current Virtools rasterizer/rendering device
    under Options > General Preferences > 3D Layout - Rendering > Rendering Device.
  • A Shader Compliant Graphics Card (GPU capable of supporting HLSL) and its most recent drivers are installed
    Your 3D graphics card must be Shader compliant, i.e. capable of supporting vertex and pixel shaders. Pay particular attention to vertex shader and pixel shader version (2.0, 1.1, etc.) that is supported by your card. (c.f. Recommendations > Shaders Troubleshooting for more details).
  • Familiarity with a C-like language
    While HLSL is much more user-friendly than writing Assembly code, HLSL is still a programming language, so coding Shaders from scratch currently remains an activity for programmers.
If you are a Virtools Scripter, we recommend that you read "Getting Started" first, and then reuse/reverse engineer existing Technical Samples in the Virtools Minisite. CMOs are located in Virtools Dev 3.0 > Documentation > CMOs > Technical Samples > Shaders.

1. Basic

In this tutorial, you will learn to:

  1. Create and apply a shader to a material.
  2. Set States and link them to static parameters.
  3. Expose Parameters (Automatic and Manual).

1.1. Open Tutorial Start File

1.1.1. Open the tutorial file "torusknot - 01 - start.cmo"

This composition contains a torus knot mapped with a simple checkered texture, as well as a hidden light (that will be used later on).

1.2. Create New Shader

1.2.1. Open the Shader Editor

The Shader Editor can be accessed via the "Editors" pulldown menu. (Once open, the Shader Editor resembles the VSL Editor.)

Note: The Default Shader appears at the very start since no other Shader has been created, and it appears in grey since it cannot be edited (i.e. it is hard-coded).

1.2.2. Click the New Shader icon

The Shader program is initialized with a simple technique tech containing an single empty pass p.

technique tech
{
   pass p
   {
   }
}

Note: You should also see a new item named "New Shader" in the shader list (located on the left), as well as the corresponding items in the technique/pass list (on the right).
1.2.3. Rename "New Shader" to "Shader 01"

Double-Click the shader item (located in shader list on the left), or press the F2 key to edit the shader's name.

1.2.4. Compile

Click the Compile button (located in the Shader Editor toolbar), or press F7 key to compile the shader.

The shader editor's output window (bottom) will flash and should display a "compilation successful" message.

1.3. Apply Shader To Material

In order to see the "Shader 01" rendering result, we need to apply it to a material.

1.3.1. Select TorusKnot's material

Right-Click on the TorusKnot object in the 3D Layout, and select "Material Setup (Check)".

The Material Setup will open.

At the top of this setup, you will find a button named "Shader Editor", and to the right of this button, you should see the Shader Combo Box. At the beginning "-- None --" is selected because no shader has been applied on the material.

1.3.2. Select "Shader 01" in the shader's combo box

Note: Once a shader is selected, instead of "-- None --", a button named "Shader Params" will appear at the right of the combo box. (We will use it later.)

As soon as "Shader 01" is selected as the current shader for this material, the torusknot's color will turn to black.

Note: Since the shader we coded does not redefine (override) any states, it takes the exact same State values as the Default Shader. So what you see is the rendering result of the Default Shader: no light influence, no emissive color, no texture. Just an empty black form.

Now, let's put some color inside.

1.4. Set Emissive State

1.4.1. Add a "MaterialEmissive" state

Return to the Shader Editor, and add a MaterialEmissive state inside the pass as shown bellow.

technique tech
{
   pass p
   {
       MaterialEmissive = {1,1,0,0};
   }
}

Note: The color is a kind of vector value made of four float components (float4). Therefore, color values are given using the following syntax: {r, g, b, a}.

1.4.2. Compile

Click the Compile button, or press F7 key to compile the shader.

The TorusKnot object will turn yellow, since {1,1,0,0} stands for yellow.

Note: Modifications inside the shader source code only take effect after compilation.

1.4.3. Use a static variable

At the top of the shader program, add a static float4 variable named colEmi as follows:

static float4 colEmi = {1,1,0,0};

To allow this variable to be used by the MaterialEmissive state, we must insert it between '<' and '>' symbols. The shader source code should look like this:

static float4 colEmi = {1,1,0,0};

technique tech
{
   pass p
   {
       MaterialEmissive = <colEmi>;
   }
}

Important: '<' and '>' symbols must be used to convert a variable into a state.

1.4.4. Compile

The shader should compile with no error messages, and no rendering changes should be noticeable.

Note: Static variables - even if not exposed - are often used to compute values that change only once per rendering frame (and not for every vertices).

1.5. Expose Variable

We will now make this variable visible from the outside (exposed); first as a Manual Parameter, then as an Automatic Parameter.

1.5.1. Convert the Static Variable to a Manual Parameter

To do so, select the keyword static from the definition line of colEmi...

static float4 colEmi = {1,1,0,0};

... and remove it from the declaration line.

float4 colEmi = {1,1,0,0};
1.5.2. Compile

Once compiled, the shader will expose the colEmi variable as a Manual parameter, as shown in the Exposed Parameter list at the right.

1.5.3. Show Material's Shader Parameters

Return to the Material Setup and Click on the "Shader Params" button (on the right of the shader combo box)

The Shader Params Dialog Box should open and display the exposed parameter colEmi.

Note: The first two parameters "Technique" and "Find Next Valid Technique" will not be discussed in this tutorial. Simply note that they are not part of the exposed parameter list.

Note: As you can see, the exposed Manual Parameter colEmi appears yellow in the Shader Params dialog box. When exposed for the first time, a Manual Parameter takes the constant value it has been initialized with (in the shader's source code) as its default value.

1.5.4. Change colEmi to Green

Open the Color Picker Dialog Box by Double-Clicking on the yellow color rectangle standing for 'colEmi' in the Shader Params dialog. Once the Color Picker Dialog Box is opened, change the color to green as shown bellow:

1.5.5. Click "Apply" or "OK" button

Now the TorusKnot should appear green.

1.5.6. Remove yellow value from shader's source code

Once exposed, a variable is no longer influenced by its source code value. Instead, it will take its value exclusively from the exposed parameter (the one in the Shader Params dialog box). In order to avoid any misunderstandings, we should remove this initial value from the shader's source code...

float4 colEmi = {1,1,0,0} ;

..and just keep this.

float4 colEmi;

1.6. Link Color To Material's Emissive

Now we will see how to transform this Manual Parameter to an Automatic Parameter.

1.6.1. Add EMISSIVE semantic to colEmi

Adding a valid semantic to the end of the variable declaration will transform a Manual Parameter into an Automatic Parameter. In our case, we want colEmi to be extended with the EMISSIVE semantic.

float4 colEmi : EMISSIVE;
1.6.2. Compile

As show bellow, colEmi no longer appears in the Manual category of Exposed Parameters, but instead is part of the Automatic category now.

1.6.3. Test

A valid semantic hides the parameter from the user and exposes it to the 3D engine. In our case, EMISSIVE semantic tells the 3D engine to link colEmi variable to the material's emissive color. Thus, if you go to the Material Setup and change the Emissive component, you should see that the TorusKnot's color is similarly altered.

Note: For efficiency, not all material attributes can be linked to shader's semantics. You can find a complete list of valid semantics in the Parameters chapter.

2. Light and Texture

The next step of this tutorial is to see how lighting and texturing can be achieved through states values. So you will learn to:

  1. Manipulate lighting states
  2. Use an Annotation
  3. Set a Texture

Note: If you had trouble with sample 1, feel free to open the tutorial file "torusknot - 02 - emissive.cmo"; it contains a finished sample of everything we have done up until now.

2.1. Set Diffuse Color

2.1.1. Add the diffuse Automatic Parameter

Just like we did for colEmi, we will create an Automatic Parameter called colDif and linked to the material's diffuse color using the DIFFUSE semantic.

Note: To use automatic completion press Ctrl + Enter.

2.1.2. Use "colDif" as the MaterialDiffuse state

The default diffuse state (defined in the Default Shader) is set to black, so once again we must override this state. Add a line in the pass statement to tell the state called MaterialDiffuse to take <colDif> as a value.
So, the pass statement should now look like this:

   pass p
   {
       MaterialEmissive = <colEmi>;
       MaterialDiffuse = <colDif>;

Note: If you compile now, you won't see any difference because lighting is still disabled (default states).

Note: Keep the material's diffuse color white for the incoming steps.

2.2. Enable Lighting

Lighting is proper to each shader. A shader can be influenced by one light, another by two lights, and a third one may not be influence by any. That's why the lighting process must be not only specified for each shader (and each pass) but also for each light.

Note: Most 3D cards cannot handle more than 8 lights per pass.

2.2.1. Add lighting states

Each light state is indexed. For example, LightEnable must be followed by the light's index: LightEnable[0]. Override each relevant light state until the pass statement looks like this:

technique tech
{
   pass p
   {
       MaterialEmissive = <colEmi>;
       MaterialDiffuse = <colDif>;

       LightEnable[0] = true;
       LightAttenuation0[0] = 1;
       LightDiffuse[0] = {1, 1, 1, 0};
       LightRange[0] = 1000;
       LightPosition[0] = {0, 0, -100};
       LightType[0] = POINT;
   }
}

LightEnable enables/disables all lighting states for the indexed light.

LightAttenuation0 has the same meaning as the light constant in the Light Setup.

LightDiffuse is the light's diffuse color.

LightRange is the light's range.

LightPosition is the light's position.

LightType has the same meaning as the light type in the Light Setup.

Note: A light is not an object for the state system. The lighting is defined by a series of lighting states, and that's why you must even specify the light's position (i.e. you did not need to do this from the Light Setup since the light was an object). But we will see in paragraph 2.4 that a position can be linked to a Virtools object position (a Virtools light position for example).

Note: If one of the light states listed above is not set, it's highly likely that your object will not be lit at all.

2.2.2. Compile

Once compiled, the shader should render to something like the image below: a dark green emissive color, combined with a white diffuse color, and lit by a pseudo light whose range would be 1000 units and rays would come from a theoretical position (0,0,-100).

Note: Make sure the emissive color (linked to the material's emissive color) is set to a dark green in order to get the same result.

2.3. Expose Light Position

As we did for theMaterialEmissive state initially, we will now link the LightPosition state to a Manual Parameter.

2.3.1. create lightPos Manual Parameter

We will called this Manual Parameter lightPos and define it as a float3 (3D Vector). You should be getting used to creating Manual Parameters by now. Just add this line beneath the colDif declaration and make sure that you do not declare lightPos as a static. (That's all!)

float3 lightPos;
2.3.2 Link LightPosition state to lightPos

Here, don't forget the '<' and '>' symbols to use lightPos as a State value.

       LightPosition[0] = <lightPos>;
2.3.3. Compile

The shader should still compile without error messages. You should notice a lighting difference on the TorusKnot since the ray of light is no longer supposed to come from (0,0,-100).

Note: If an error message appears in the Shader Editor's output window, just Double-Click on the message to see where it came from.

2.3.4. Test

Open the Shader Params dialog box (if you closed it), and set lightPos vector to (0,0,-50).

Note: Shader Params dialog box does not need to be closed and opened again in order to be updated with Shader modifications. Once compiled, a shader automatically updates the Shader Params dialog.

2.4. Link Position to 3D Entity's Position

An annoying issue with exposed position parameter is that every time the user needs to change its location, the user has to enter a new 3d vector value - which is far from being intuitive. To resolve this issue we'll use an Annotation whose role is to tell the 3D engine that the position must be automatically bound to a 3D entity's position.

2.4.1. Add Annotation

This Annotation is of type string, is named type and takes as a value the string "entity3d". Add it as shown bellow.

float3 lightPos <string type="entity3d";>;

Note: Just like a Semantic, an Annotation is an information embedded within a variable, within a pass or within a technique. They take place at the end of the line and must be surrounded by '<' and '>' symbols. There can be several Annotations per line; they just need to be separated by a semicolon ( ';' ). An Annotation is defined by a type, a name, and a value (See Parameters chapter for an in-depth description).

2.4.2. Compile

Compilation is needed to get the Shader Params dialog box updated.

Now lightPos is exposed to the user as a 3D Entity while still used as a float3 inside the shader's code. The 3D engine will automatically take the specified 3D Entity's position and link it to the exposed variable.

2.4.3. Give light01 as the 3D Entity

Open the Shader Params dialog box (if you closed it), and set lightPos to light01.

Now if you move light light01, you should notice the same kind of light variation that occurs between a standard material and a standard omni light.

2.5. Apply Material's Texture

We have almost finished with parameters, states, and all these rendering manipulations that look (desperately) like any standard material rendering!
But before tackling the vertex programmable pipeline, let's just see how to put some texture on the TorusKnot.

2.5.1. Create and expose a texture parameter

A texture is exposed through the use of the texture variable type. We could expose the texture as a Manual Parameter, but since we just need one texture, we can expose it more conveniently as an Automatic Parameter linked to the material's texture. To achieve this, simply add the TEXTURE semantic at the end of the texture variable declaration line.

texture tex : TEXTURE;
2.5.2. Link Texture state to tex

Add the Texture state to the pass p, and link it to the texture defined by tex.

       Texture[0] = <tex>;

Note: The Texture state is indexed by the texture stage number. There can be up to 8 texture stages, but many 3D cards will not support that many (see Texture Stage).

2.5.3. Compile

Once compiled, the shader will render with the checkered texture.

We have finished with parameters, states and fixed pipeline manipulation (for in-depth information see Parameters and HLSL Reference).

Now we will start the tutorial chapters dealing with programmable pixel pipeline.

3. Vertex Shader

Instead of restarting from scratch, we will take the final result of the previous chapter and study Vertex Shader implementation through the usage of a second pass. This second pass will use a Vertex Shader to set vertices color and increase the TorusKnot volume size, in order to get a edge surrounding the initial TorusKnot rendering.

In this tutorial, you will learn to:

    1. Define a Vertex Shader
    2. Use Intrinsic Vertex Shader Parameters
    3. Use additional states

Note: If you had trouble with sample 2, feel free to open the tutorial file "torusknot - 03 - lit texture.cmo"; it contains what we have done up until now.

3.1. Add Empty "edge" Pass

Add a pass called edge after the first pass p.

   pass edge
   {
   }

Important: Passes are execute in the order in which they appear in their Technique statement.

3.2. Add Automatic Parameters

The incoming Vertex Shader function will expect some variables to be defined.

3.2.1. Add colEdge color

First add a color (float4) called colEdge to define the edge's color, and link it to the material's specular color through the SPECULAR semantic.

float4 colEdge   : SPECULAR;
3.2.2. Add Thickness factor

Then add a factor (float) called Thickness to define the edge's thickness, and link it to the material's specular power through the POWER semantic.

float  Thickness : POWER;

Note: We choose to link colEdge to the material's specular color and Thickness to the material's power factor mostly for convenience (since those two material attributes are not often used). We also wanted to show that there is no contra-indication linking a shader's variable to a material attribute that is not in direct relation with the variable's purpose.

3.2.3. Add Wvp WorldViewProjection Matrix

The incoming Vertex Shader function will need the transformation matrix which combines the World, the View and the Projection matrix. If you look at the Default Shader source code, you will see how a matrix (float4x4) can be linked to the 3D engine's WorldViewProjection matrix through the WORLDVIEWPROJECTION semantic. We will do the same here, and create a standard automatic parameter called Wvp as shown below.

float4 colEdge   : SPECULAR;
float  Thickness : POWER;

//--- Standard Automatic Parameters
float4x4 Wvp : WORLDVIEWPROJECTION;

3.3. Define Vertex Shader Output Structure

Most Vertex Shader functions need to output several attributes (e.g. vertex color and position). That is why a structure must be defined to contain these output values.

In our case, the Vertex Shader function will change the vertices position (for the volumetric scale) as well the vertices color, thus we must create a structure containing a 3D vector and a color.

Create the EdgeVSOut structure as shown below:

//--- Vertex Shader Output Structure
struct EdgeVSOut
{
   float4 Pos : POSITION;
   float4 Col : COLOR;
};

Note: Pos is the vertex position (3D vector) in the homogeneous camera space, that's why it is defined as a float4 parameter.

Note: The name and order in which parameters appear in the VS Output Structure are not relevant. The compiler will only look for the vertex shader intrinsic semantic to decide which parameter stands for the vertex position, and which parameter stands for the vertex color. Here POSITION and COLOR are the intrinsic semantics used for that purpose.

See Parameters and HLSL Reference chapters for in-depth information about intrinsic semantics.

3.4. Define Vertex Shader Function

Now comes the harder part - the actual vertex shader function we will call EdgeVS().

EdgeVS() function will return an EdgeVSOut structure like we saw above. This structure must be instantiated and filled inside EdgeVS() statement.

The input vertex attributes needed by EdgeVS() are defined in the same way as the output vertex attributes (i.e. using intrinsic semantics). The main difference comes from the fact that in most cases, it is useless to create a Vertex Shader Input Structure since all input vertex attributes can be passed as the function's parameters to EdgeVS(). You can put intrinsic semantics directly to those function's parameters as shown below:

//--- Edge Vertex Shader Function
EdgeVSOut EdgeVS
   (
      float4 Pos : POSITION,
      float4 Norm : NORMAL
   )
{
   EdgeVSOut vsOut;
   float3 p = Pos + Norm * Thickness * 0.002f;
   vsOut.Pos = mul( float4(p,1) , Wvp );
   vsOut.Col = colEdge;
   return vsOut;
}

EdgeVS needs only the vertex position and normal in order to produce a volumetric scale.

p takes the vertex position shift with a fraction of the vertex normal vector.

vsOut.Pos takes as a value the homogeneous 4D value of p, transformed by the WorldViewProjection (the output vertex position must be given in the homogeneous camera space).

vsOut.Col simply takes colEdge color.

Note: Notice that Thickness * 0.002f gives the exact same result for all vertices, and thus it wastes GPU processing time and memory to keep this operation inside the vertex shader function. Creating a static float tmp = Thickness * 0.002f; variable on the outside of the vertex shader function and this tmp instead of Thickness * 0.002f will optimize the Vertex Shader function.

3.5. Complete "edge" Pass

The last thing to do is to complete the edge pass.

If kept empty, the pass edge will render exactly like the first pass because states are set by the first pass, and no instructions is given by pass edge to modify them.

This pass needs neither texturing nor lighting, so you must start by disabling them. Then give the state CullMode the value CW to ask for the pass edge to render in the opposite side of the TorusKnot (that way only overflowing parts will display).

Finally you must ask to compile the EdgeVS() function with 1.1 vertex shader instruction set, and set the returned value to the VertexShader state, as shown below:

   pass edge
   {
       Texture[0] = NULL;
       LightEnable[0] = false;
       CullMode = CW;

       VertexShader = compile vs_1_1 EdgeVS();
   }

Note: Always remember that states are kept from on pass to another. They are initialized just once per shader before the shader gets executed (with the Default Shader states values).

3.6. Finalize

3.6.1. Compile

Compilation should not provide very relevant results, because we have not yet customized the material's specular color (linked to the edge color) or the material's specular power factor (linked to the edge thickness).

3.6.2. Modify material's attributes

Go to the material's setup, and change the specular color until you get a yellow color. Change the emissive color until you get a dark blue, and move the specular power slider until you reach the thickness shown in the following picture:

Note: Linking shader parameters to material attributes gives the end-user a very flexible way to tune its rendering and is a very convenient way of exposing variables during the prototyping stage.

3.6.3. Experiment further

You can experiment with other things from here. For example, try changing the value of vsOut.Col and make it take the vertex X position as a color.

   vsOut.Col = Pos.x;

You should get this rendering as a result.

Note: If you had trouble with sample 3, feel free to open the tutorial file "torusknot - 04 - VS edge.cmo"; it contains everything we have done up to now.

See also

For moving forward with Shaders, you are strongly encouraged to:

  • Continue learning HLSL by reading Microsoft DirectX 9 HLSL Reference
  • Investigate shader samples located inside the Virtools MiniSite (CMOs are located in Virtools Dev 3.0 > Documentation > CMOs > Technical Samples > Shaders), or other samples found on the web.

    • Comments


Shader Editor

Overview
Opening the Shader Editor
Shader Editor Interface
Shader Area in Material Setup
Assembly Code Generation

Overview

The Shader Editor provides the Virtools Dev interface for the Shader Manager. In the Shader Editor, Shaders are created, edited, organized, compiled and deleted. You can also use the Shader Editor to generate and see the Assembly code of a Shader function and to load/save shader source code in .fx files.

Opening the Shader Editor

The Shader Editor can be accessed:

1. From the Pulldown Menu

Drop-down Editors menu and select Shader Editor.

2. From the Material Setup

Click on the Shader Editor button to see the source code of the shader currently used by the material (current item of the shader combo box).

3. From the 3D Layout

Right-Click in the 3D Layout on an object which material uses a shader.

The Shader Editor Interface

Click on Shader Setup items beneath to link to the item's description.

click to show description click to show description click to show description click to show description click to show description click to show description click to show description click to show description click to show description click to show description click to show description click to show description

Create New Shader

Create New Shader button.

  • Click on the new Shader button to create a new shader.
  • Note: The shader's name will be "New Shader" or "New Shader 001" , "... 002", etc.
Load / Save Shader

Load/Save shader source code buttons to/from an .fx file.

  • Click on the Load button to load an external shader from a .fx file.
  • Click on the Save button to save a shader to an external .fx file.
  • Note: When a shader is loaded - either from a .fx or from .nmo/.cmo - it extends its name with 001, 002, etc. if another shader uses the same name. If both the shader's name and source code are identical to another shader already in the list, then it is not loaded but replaced by the existing one.
Compile / Compile All

Compile source code(s) buttons.

  • Click on the Compile button or press F7 key to compile the current shader source code.
  • Click on the Compile All button to compile all shaders' source codes.
Generate Assembly

Generate Assembly code button

  • See Assembly Window section to understand how to use this button
Techniques

List of all techniques defined inside the shader source code.

  • Note: There is an asterisk at the end of the technique's name if the technique is not valid on the user's 3D card.
  • Note: Techniques are represented as the list categories (bold items).
  • Note: The technique list is updated after each compilation.
Passes

List of all passes defined inside the technique.

  • Note: The pass list is updated after each compilation.
Automatic Parameters

List of all Automatic Parameters defined in the current shader.

  • Click on the Automatic item to expand or collapse the list.
  • Note: The Automatic Parameters list is updated after each compilation.
Manual Parameters

List of all Manual Parameters defined in the current shader.

  • Click on the Manual item to expand or collapse the list.
  • Note: The Manual Parameters list is updated after each compilation.
Output Window

List of all error/warning/info messages.

  • Double-Click to jump to the line inside the source code that generates the error messages.
  • Note: The Output Window flashes every time a message is to be displayed.
Main Window

Window containing the editable source code of the currently selected shader.

  • Ctrl+Enter to use auto-completion.
  • Ctrl+V or Shift+Insert to paste text field.
  • Ctrl+C or Ctrl+Insert to copy text field.
  • Ctrl+X to cut text field.
Title Bar

Shows the currently selected shader's name.

Shader List

List of all created/loaded shaders.

  • Double-Click or press F2 to rename the selected shader.
  • Press Delete to remove the selected Shader.
  • Click or press Up and Down keys to select the current shader to be edited inside the Main Window.
Close

Close button

  • Click on it to close the Shader Editor.

Automatic Completion

There is an automatic keyword completion when you hit Ctrl+Enter. This works for types, semantic, states, enums, etc.

Here automatic completion is used to complete
the DIFFUSE semantic.

Important: Some automatic completion may not capitalize correctly, or may appear in a different color than expect, because certain words can have several usages. For instance, the word "texture" can either be a state (Texture), a type (texture) or a semantic (TEXTURE). The shader source-code is not color-sensitive; however, it is case-sensitive (in most cases).

Shader Area in Material Setup

The Shader Area located in the Material Setup's toolbar contains three items. The first two items are always visible.

1. The Shader Setup Button

Click it to open the Shader Editor and see the selected shader's source code.

2. The Shader Combo Box

Select an item from this combo box to apply a shader to the material, or Select "-- None --" for standard material.

If the item selected in this combo box is a valid shader, then a third button will appear:

3. The Shader Params button

Shown only if a valid shader is selected in the combo box, the Shader Params button opens the Shader Params Dialog Box from which the user can customize the shader by modifying Manual Parameters.

Assembly Code Generation

Assembly Code Generation is an advanced feature reserved to programmers who would like to optimize a shader's code in special circumstances.

By default, the Generate Assembly button will open a single-lined popup menu (to remind the user that to generate the assembly code of a function, the user must select the function's name in the shader's source code.

You must first Select a function's name inside the Main Window.

Once the function's name has been selected, Click on the Generate Assembly button to open the contextual menu, and choose the vertex/pixel shader instruction set you want the function to be called with.

If the assembly code generation succeeds, the Assembly Window will open and show a non-editable text window (in grey). This is the assembly language translation of the selected shader's function.

Note: From the generated assembly source code, a user can retrieve a lot of useful information like the register mapping, and the remaining free slots. From there, advanced users can copy assembly code and paste it in an inline assembly statement located somewhere in the shader source code. In order to do that, one must be sure to force variables to be mapped to assembly registers.

To close the Assembly Window click again on the Assembly Generator button to open the popup menu, and select the "Close ASM window" item.

Note: You can also close the Assembly Window by Double-Clicking on the Assembly Window title's name.


HLSL - High level Shader Language

HLSL Reference

HLSL Reference
Cg, CgFx, DX8 HLSL and DX9 HLSL
States
Shader Versions

HLSL Reference

Instead of writing shaders in assembly language, Virtools chose to adopt the DirectX 9.0 High-Level Shader Language (HLSL) for developing shaders in a C-like language. The High-Level Shader Language supports shaders development using C-like functions. HLSL supports many standard language features such as functions, expressions, statements, standard data types, user-designed data types, and preprocessor directives.

To find out about HLSL Data Types, Statements and Expressions, Functions, Shader Semantics, Examples, Language Syntax, Lexical Conventions, Keywords and Preprocessor Directives, you should read online Microsoft's online HLSL reference.

  • DirectX 9.0 > DirectX Graphics > Reference > Shaders > High-Level Shader Language
  • DirectX 9.0 > DirectX Graphics > Reference > Effects > Effect Format

Cg, CgFx, DX8 HLSL and DX9 HLSL

Below is a highlight of the four primary types of shader languages developed in joint effirt by Microsoft and NVidia.

Cg

  • Cg is the language used by NVidia to describe vertex and pixel shader functions in a C-like style.
  • Cg was a first generation language made to free programmers from writing shader source code in assembly language.
  • Cg does not describe passes, techniques or states; those must be defined.

CgFx

  • CgFx is an enhanced version of Cg which includes techniques, passes, states and exposed parameters concepts.
  • CgFx functionalities are very similar to DirectX9 HLSL functionalities.

DirectX 8 HLSL

  • DirectX 8 HLSL is the language used by Microsoft to describe techniques, passes, states and exposed parameters concepts - used on the Xbox.
  • DirectX 8 HLSL describes shader functions through assembly statements.
  • DirectX 8 HLSL does not use C-like language to define shader functions.

DirectX 9 HLSL

  • DirectX 9 HLSL is an enhanced version of DirectX 8 HLSL which includes a C-like language (like Cg) to define shader functions.
  • DirectX9 HLSL functionalities are very similar to CgFx functionalities.

States

Why Use States?

States represent the fixed-pipeline instructions that initialize 3D card states before each mesh's material rendering. Even when using a programmable-pipeline compatible 3D card, many states must still be used.

States like MaterialDiffuse or TextureMag will be emulated by vertex/pixel shader instructions by programmable-pipeline compatible 3D cards, and they will be overriden if the shader uses vertex/pixel shader functions. But states like CullMode or PointSize cannot be replaced by vertex/pixel shader functions.

HLSL uses different kinds of states, and you need to understand them to use shader states efficiently. You can find the exhaustive list of DirectX 9 HLSL States here:

  • DirectX 9.0 > DirectX Graphics > Reference > Effects > Effects Format

    Enhanced rendering with States

Still using the fixed-pipeline, many enhanced rendering effects can be achieved.

For instance, pseudo-environment mapping can be achieved by setting the TexCoordIndex state to CAMERASPACENORMAL. This is done by Virtools' 3D engine when using the material's effect TexGen with Chrome value.

Texture Stage States

Texture Stage States is an important feature to master. It allows you combine several texture stages in one pass before they get applied to the screen. While some similarities exist with blending modes (SrcBlend and DestBlend) in that blending operations can be defined between stages, Texture Stage States are also different from blending modes because Texture Stage states combination occurs before the material gets drawn on screen.

Here is a diagram that summarize a typical texture combination using 2 texture stages:

Note: DirectX allows up to 8 texture stages, but depending on the targeted 3D card pixel pipeline capabilities, all may not be available.

Shader Versions

Shader functions are compiled using a series of machine coded instructions taken from an Instruction Set. A Vertex/Pixel Shader 1.1 compatible 3D card can only execute shader functions compiled with 1.1 Vertex/Pixel Instruction Set.
If a shader function uses an instruction that is only available from the 2.0 Instruction Set, this shader function could only be compiled using 2.0 (or higher) vertex/pixel shader version (and of course will only work on 2.0 compatible cards).

Differences between shader versions not only involves Instruction Set differences, it also involves differences in the number of instructions that can be executed (instruction slots), and the number of registers that can be used.

Please refer to DirectX 9 Documentation to get an exhaustive list of differences between all shader versions.

  • DirectX 9.0 > DirectX Graphics > Reference > Shader Reference


Shader Parameters

Parameters

Automatic Parameters
Semantics
Manual Parameters
Annotations
Static Variables
Intrinsic Vertex Shader Parameters
Intrinsic Pixel Shader Parameters

Automatic Parameters

Automatic Parameters let the user create a link between a variable located inside the shader source code and an engine-side attribute (like the material diffuse color or the behavioral timer).

Automatic Parameters generally appear at the top of the shader source code.

Syntax:

 type id : SEMANTIC;

type: Can be a float3, int, texture, ...etc.

id: Case sensitive name.

SEMANTIC: Indicates the meaning of the variable for the application. See Semantics paragraph to see the exhaustive list of valid semantics for Virtools.

Examples:

texture tex : TEXTURE;
A texture object linked to the material's texture

float time : TIME;
A floating point real number linked to the behavioral timer

float4 colDif : DIFFUSE;
A color linked to the material's diffuse color

float4x4 world : WORLD;
A 4x4 matrix linked to the object world matrix

Note: All semantics used to define variables as being Automatic Parameters are listed at the top of the Default Shader source code.

Note: A (non-intrinsic) semantic should appear only once inside a shader source code. (c.f. intrinsic semantics are explained later.)

Note: Do not mix up semantics used for Automatic Parameters and intrinsic semantics used for intrinsic Vertex/Pixel Shader function parameters. (c.f. intrinsic semantics are explained later.)

Semantics

A Semantic provides the Virtools engine with an exposed variable's special meaning.

Some semantics are common to most 3d engines - called Standard Semantics - while other ones are particular to Virtools - called Additional Semantics. Each semantic has a particular meaning for the engine; below is the complete list:

Standard Semantics:
WORLD
 Object World Matrix
VIEW
 Camera View Matrix
PROJECTION
 Projection Matrix
WORLDVIEW
 World and View Matrix
WORLDVIEWPROJECTION
 World, View and Projection Matrix
EYEPOS
 Position Vector expressed in world space
Additional Semantics:
OBJECTPOS

Object Position expressed in world space
TEXTURE
 Material's Texture
TEXTUREi
 Texture of Channel i (with i between 0 and 7)
DIFFUSE
 Material's Diffuse Color
EMISSIVE
 Material's Emissive Color
SPECULAR
 Material's Specular Color
AMBIENT
 Material's Ambient Color
POWER
 Material's Specular Power Value
TIME
 Time elapsed since play event (in seconds)
PASSCOUNT
 Pass count defined in the rendered Technique
PASSINDEX
 Current rendered pass index

Note: Another type of semantic exists, called Intrinsic Semantics. They have no relation to exposed parameters, are meaningless to the engine, and are used to define pixel and vertex shader function's input/output parameters. See Intrinsic Vertex Shader Parameters and Intrinsic Pixel Shader Parameters paragraphs for more information about Intrinsic Semantics.

Manual Parameters

If a variable is not defined as an Automatic (i.e. it has no valid semantic at the end), and if its usage is not static, then it is considered a Manual Parameter.

A Manual Parameter is linked to a real Virtools parameter stored inside the material. This parameter is saved with the material, and if several materials use the shader, then each material owns its own version of the parameter.

Examples:

float3 lightPos;
lightPos will be exposed through a Virtools' 3D vector parameter

texture tex;
tex will be exposed through a Virtools' texture parameter

Note: It is always better to compute big calculations outside the shader code and pass the result to an exposed parameter, rather than making big calculations inside the shader code. Remember that a vertex shader function is called for every vertex, and a pixel shader function is called for every pixel! So if part of the code can be computed once for all vertices/pixels, then use a Manual Parameter and compute its value during a Virtools graph or VSL program.

Note: sampler, sampler2D, and sampler3D variables are not exposed at all. They will always be considered as static variables.

Annotations

Annotations add information to a variable that is invisible (and irrelevant) to the Shader code, but that are relevant to the 3D engine. Manual Parameters can be extended with an Annotation in some special cases (see further list of available annotations).

Syntax:

< type id = value; [type id = value;] [type id = value;] ...etc >;

type: Can be a float3, int, texture, etc.

id: Case sensitive name.

Examples:

float3 lightPos <string type="entity3d";>;
lightPos has been added a string annotation named type with value "entity3d"
float3 lightPos <string type="entity3d"; int uselessValue=0; >;
Two annotations can be set in the same line
float3 lightPos <string type="entity3d";> = {0,0,-100};
An initialization value can still be added while using annotations

float4 vec <string type="vector";>;
vec is exposed as a 4D Vecor, not as a color.

texture tex;
static float2 texelSize <bool istexelsize=true;>;
texelSize will receive the computed texel size of exposed tex texture

Available Annotations:

Syntax
Applies To
Meaning
string type="entity3d";
 float3 The Manual Parameter will be exposed as a 3D entity, and the float3 variable will be set to the 3D entity's position.
string type="vector";
float4 The Manual Parameter will be exposed as a 4D vector, not as a color (by default a float4 is exposed as a RGBA color).
bool istexelsize=true;
static float2 As the parameter is supposed to be static the float2 will not be exposed, but will received instead the texel size of the last defined texture.

Difference with Semantics:

Aside from their syntax, Annotations and Semantics are very different. The same Annotation can be used on several variables, and several Annotations can be added to the same variable. On the other hand, a Semantic cannot be used more than once in the shader source code, and at most, one (and only one) Semantic should be applied to a variable.

Note: Grammatically an Annotation could be added to Passes and Techniques, yet Virtools does not associate such annotations with any functionnality (for the moment).

Note: Grammatically an Annotation could even be added to a variable defined with a Semantic (...just in case you come to find this syntax in a source code).

Static Variables

A Static Variable is not exposed, and so is only known and understood by the shader source code. In other words, a static variable is "local" to the shader's code, just like a local variable inside a statement.

Example:

static float4 colEmi = {1,1,0,0};
A static color initialized to yellow

Static Variables are very useful to precalculate values that just change once per shader execution (not at every vertex/pixel shader function execution).

Example:

static float tmp = sin(colEmi.r) * 150.0f;
A floating point number processed just once for all vertices

Note: Variables that do not need to be exposed should always be defines as static variables to avoid useless processing.

Note: The static keyword is only necessary in the global scope of the shader source code. Once inside a function, a variable is always compiled as a local variable whether or not the static keyword is used.

Intrinsic Vertex Shader Parameters

Intrinsic Vertex Shader Parameters are the input/output parameters handled by a vertex shader function. Intrinsic semantics are used to give their meaning to these parameters so the Vertex Shader function can understand how to use them.

Examples:

struct EdgeVSOut
{
   float4 Pos : POSITION;
   float4 Col : COLOR;
};
A Vertex Shader can use this structure to output the Vertex Position and Vertex Color

EdgeVSOut EdgeVS
   (
      float4 Pos : POSITION;
      float4 Norm : NORMAL;
   )
{
    /* ... code ... */
}
This Vertex Shader takes the Vertex Position and the Vertex Color as Input Parameters.

Vertex Shader Input Semantics:
POSITION[n]
 Vertex position expressed in the mesh's referential.POSITION (without brackets) is an alias for POSITION[0]. Virtools manages only one set of vertices positions, so POSITION[1..n] are not supported by Virtools.
BLENDWEIGHT[n]
 Vertex blend weights. Not supported by Virtools.
BLENDINDICES[n]
 Vertex blend indices. Not supported by Virtools.
NORMAL[n]
 Vertex normal vector expressed in the mesh's referential.NORMAL (without brackets) is an alias for NORMAL[0]. Virtools manages only one set of vertices normals, so NORMAL[1..n] are not supported by Virtools.
PSIZE[n]
 Vertex point size. Not supported by Virtools.
DIFFUSE[n]
 Vertex diffuse color. DIFFUSE (without brackets) is an alias for DIFFUSE[0]. Virtools manages only one set of vertices diffuse colors, so DIFFUSE[1..n] are not supported by Virtools.
SPECULAR[n]
 Vertex specular color. SPECULAR (without brackets) is an alias for SPECULAR[0]. Virtools manages only one set of vertices specular colors, so SPECULAR[1..n] are not supported by Virtools.
TEXCOORD[n]
 Vertex texture coordinate. TEXCOORD (without brackets) is an alias for TEXCOORD[0]. There is as many texture coordinate sets as zero channels on the mesh (a zero channel is a channel which is not active and which blending modes have both been set to zero).
TANGENT[n]
 Vertex tangent. TANGENT (without brackets) is an alias for TANGENT[0]. Virtools manages only one set of tangents, so TANGENT[1..n] are not supported by Virtools. The tangent set can be build through Build Tangent Space building block. Tangents are often used for bump mapping.
BINORMAL[n]
 Vertex binormal. BINORMAL (without brackets) is an alias for BINORMAL[0]. Virtools manages only one set of binormals, so BINORMAL[1..n] are not supported by Virtools. The binormal set can be built through Build Tangent Space building block. Binormals are often used for dot3 bump mapping.
TESSFACTOR[n]
 Vertex tessellation factor. Not supported by Virtools.
Vertex Shader Output Semantics:
POSITION
 Vertex position expressed in world space.
PSIZE
 Vertex point size.
FOG
 Vertex fog.
COLOR[n]
 Vertex color. COLOR (without brackets) is an alias for COLOR0.
TEXCOORD[n]
 Vertex texture coordinate. TEXCOORD (without brackets) is an alias for TEXCOORD0.

See Microsoft DirectX 9 HLSL Reference > Shader Semantics for additional information on Intrinsic Vertex Shader Semantics.

Intrinsic Pixel Shader Parameters

Intrinsic Pixel Shader Parameters are the input/output parameters handled by a Pixel Shader Function. Intrinsic semantics are used to give their meaning to these parameters so the Pixel Shader Function can understand how to use them.

Pixel Shader Input Semantics:
COLOR[n]
 Pixel color (interpolated from output vertex color). COLOR (without brackets) is an alias for COLOR0.
TEXCOORD[n]
 Pixel texture coordinate (interpolated from output texture coordinates). TEXCOORD (without brackets) is an alias for TEXCOORD0.
Pixel Shader Output Semantics:
COLOR[n]
 Pixel color. COLOR (without brackets) is an alias for COLOR0.
TEXCOORD[n]
 Pixel texture coordinate. TEXCOORD (without brackets) is an alias for TEXCOORD0.

See Microsoft DirectX 9 HLSL Reference > Shader Semantics for additional information on Intrinsic Vertex Shader Semantics.


Shader Building Blocks and Scriptable Rendering

Scriptable Rendering

Introduction
Post-Processing
 Shader Related Parameter Types
 Shader Related Parameter Operations

Introduction

The term scriptable rendering refers to controlling the rendering process and rendering result using Virtools building blocks. In most cases, the goal is to alter the final rendering using vertex and pixel shaders, but to do so, the user must be able to control the rendering process loop. Unlike vertex and pixel shaders which have a clearly defined and closed context, manipulations to the rendering process loop require the ability to render the scene at a given time, use this rendering as the source for image processing, and finally replace the standard rendering with the processed combination.

Obviously, such high-level controls cannot be defined simply from Annotations or Semantics inside Shaders; that is why Virtools created a powerful yet intuitive way for the user to control the rendering process loop: two building blocks called Render Scene In RT View and Combine RT Views.

Combining these two primary building blocks is the key to creating Post-Processing Effects within Virtools.

Note: The word effect in this chapter describes visual features like Motion Blur, Depth Of Field, Image Processing, Deformation, etc.

Post-Processing

Post-Processing effects are achieved by assembling and combining Render Scene In RT View and Combine RT Views building blocks together (as many times as needed). The result of a Render Scene In RT View BB can only be put inside a texture (the Render Target), while the result of a Combine RT Views BB can either be drawn directly on the screen or put inside a texture for further manipulations.

For instance, a camera fading transition will simply consist of two Render Scene In RT View BBs (one rendering from Camera1 and the other from Camera2), followed by a single Combine RT Views BB that will combine them both directly onscreen using a vertex (or pixel) shader to calculate the color blending.

1. Render Scene In RT View BB

Instead of describing this building block (please refer to its online reference for a full description), we will explain its purpose.

The Render Scene In RT View BB is very similar to the Texture Render BB. They both render the scene as it is seen from the current view or from another camera, into a 2D texture or a cube map. In fact Render Scene In RT View BB is an advanced version of Texture Render BB, more suitable for post-processing effects based on shaders since it allows you to not to take the whole texture as the destination area, but just a rectangle, if needed. This useful feature lets the user fully control the location and memory footprint its rendering takes inside video memory. For example, if the texture is 512x512 pixels, and you only need to render inside its top-left first 512x386 rectangle, Render Scene In RT View BB allows you to still use the 512x126 remaining rectangle for another job.

Render Scene In RT View BB can also be used to render the whole scene using a single material, which is useful for many post-processing effects like global outlines, or depth of field (rendering only depth pixels).

Unlike Combine RT View BB, Render Scene In RT View BB only accepts a valid texture as Render Target. This also means that the rendering occurs as soon as the building block is executed (unless it is deferred). If certain objects where hidden before entering the building block, they won't appear in the Render Target!

2. Combine RT Views

Like the previous paragraph, the goal here is to understand Combine RT Views BB's purpose. (Please refer to its online reference for a full description).

Combine RT Views BB is more complex. Combine RT Views BB renders a quad geometry either on screen (pIn Render Target = NULL) or into a texture (pIn Render Target = texture). Like Render Scene In RT View BB, Combine RT Views BB can render only into a sub-area of the Render Target (e.g. the top-left 128x128 square inside a 256x256 texture).

But this BB's main feature is the fact it can associate as many texture coordinates sets (UVs) and corresponding textures as needed to the rendered quad (up to 8). Those are specified to the building block through additional RT Views pIns. Each additional RT View then contains a texture coordinates set (the Rectangle sub-parameter) and a texture (the Render Target sub-parameter). Then the rendered quad acts as if it were a standard billboard mesh built from 2 triangles on which we have applied one or more channels. Those textures, vertices and UVs can then be used by the Shader (the one specified as pIn of Combine RT Views BB) as if they came from an existing mesh.

If the Shader includes a Vertex Shader function, then vertex processing will be done on quad's corners as if the quad was a standard mesh. In most cases those vertex processes will limit themselves to UV alterations (e.g. jittering effects).
The vertex shader will apply to the quad corners' vertices - generally to modify UVs - and the pixel shader will use samplers on input textures - defined by TEXTURE0, TEXTURE1, ...TEXTUREi semantics - to compute the final pixel color.

Note: Always do as much of the work as possible inside vertices before starting pixel processes, because pixel based post-processing effects quickly drop down the fill rate since they are executed for each pixels of the screen.

Example:
Suppose that for each pixel, you need to know the color of its 4 neighboring pixels taken from texture tex. To do so you will use a texture sampler TS on tex, and called tex2D() function 4 times with TS as the sampler parameter and 4 different float2 positions: p1, p2, p3 and p4, all computed from the current interpolated pixel position p.

There is two way to compute p1, p2, p3 and p4.

Slow Method: inside the pixel shader, compute:

p1 = p + float2( texSize.x, 0);
p2 = p + float2(-texSize.x, 0);
p3 = p + float2( 0, texSize.y);
p4 = p + float2( 0,-texSize.y);

This method will work, but doing this inside the pixel shader is quite slow.

Fast Method: Define in the vertex shader output structure 4 Texture Coordinates Sets and compute UVs for each sets as above. The main advantage of this method is that offsets are computed during vertex processing, and the pixel processing does not need to compute them at all!

Another important feature of the Combine RT Views BB is that it can render directly on screen (simply put NULL inside the Render Target sub-parameter of pIn RT View). But this is also a very big modification to the standard Virtools rendering process loop. When Combine RT Views BB is set to render the quad directly to the screen, rendering options defined in the building block totally replace the standard rendering options, and the quad drawing is deferred to the end of behavioral processing. This means that the rendering will not occur when the building block is actually activated unless the destination Render Target is a real texture.
This also means that rendering options defined in the Combine RT Views BB in this case will stand for the complete scene rendering (which in most cases is disabled anyways).

When Virtools Render Engine starts rendering the scene, it then renders the quad and skips the rest of the scene (in most frequent case). Foreground 2D sprites are often the only remaining features of standard rendering that a user may want to keep.

While scriptable rendering can seems very abstract and confusing, please be sure to read the Shaders Building Blocks Online Reference to precisely understand the effect of each BBs.

You can also investigate and learn about Post-Processing Effects from samples located in Virtools Dev 3.0 > Documentation > CMOs > Technical Samples > Shaders > 4_Advanced.

Shader Related Parameter Types

In addition to shader building blocks, some new parameter types have been added to Virtools. They are used in shader related building blocks, but can also - like any other Virtools parameter - be created from scratch as Local Parameters (Alt+L in Schematic View).

RenderTarget View

This is a structure parameter, compound of a Texture (called RenderTarget) and a Rectangle (called RenderTarget Viewport). Don't be confused by the term RenderTarget: it can stand for a source or a destination texture (generally the term RenderTarget refer to a destination, but depending on the building block usage, it can be a source).
In most case, the RenderTarget sub-parameter must not be NULL, the only building block allowing a NULL RenderTarget is Combine RT Views (in which case it means the RenderTarget is the screen).

Shader

A Shader parameter appears as a combo box where the user can choose a shader among the list of all shaders. This parameter is derived from the String type, and is in fact no more than a string with a customized dialog box. It means you can link any string to this parameter without conversion, and have this parameter built from strings concatenation.

Shader Technique

A Shader Technique parameter appears as a combo box where the user can choose a shader's technique among the list of all compiled techniques. If a Shader Technique parameter is edited without any Shader parameter or Material parameter around (in the same window), it will list all existing techniques of all existing shaders. If such a combo box appears above the Shader Technique parameter, then the Shader Technique's combo box will only list the techniques used either by the found Shader or by the found Material.

Like a Shader parameter, a Shader Technique parameter is directly derived from the String type, implying everything we've mentioned for Shader parameters.

Shader Pass

A Shader Pass parameter appears as a combo box where the user can choose a technique's pass among the list of all compiled passes in all compiled techniques. If a Shader Pass parameter is edited without any Material parameter around (in the same window), it will list all existing passes in all techniques used. If such a combo box appears above the Shader Pass parameter, then the Shader Pass's combo box will only list the related passes of the technique chosen in the material.

Like a Shader parameter, a Shader Technique parameter is directly derived from the String type, implying everything we've mentioned for Shader parameters.

Shader Related Parameter Operations

On top of that, Virtools has created new Parameter Operations dedicated to simplify shader related operations.

Set RTView

pOut = RenderTarget View
pIn1 = Texture
pIn2 = Rectangle

Creates a RenderTarget View from a Texture and a Rectangle.

Get Rect

pOut = Rectangle
pIn1 = RenderTarget View
pIn2 = None

Retrieves the Rectangle parameter from a RenderTarget View.

Get Texture Rect

pOut = Texture
pIn1 = RenderTarget View
pIn2 = None

Retrieves the Texture parameter from a RenderTarget View.

Get Texel Size

pOut = Vector 2D
pIn1 = RenderTarget View
pIn2 = None

Computes the texel size of a RenderTarget View.

Note: The texel size is simply (1/textureWidth, 1/textureHeight).

Note: Computing the texel size from this parameter operation, and passing it to a Set Shader Parameter or a Combine RTViews building block is not very convenient, but at least in that way your sure not to waste shader processing time just to compute it. The more standard way (and much more convenient, too) is not to use this parameter operation, but the <bool istexelsize=true;> Annotation instead. (See Parameters for more info.)


Shaders Glossary

In addition to the glossary presented here, there are more definitions related to more general 3D notions available in the Glossary in the Virtools Dev Online Reference .

A
Annotation
D
Default Shader
E
Effect
F
Fixed-Function
Fixed-Pipeline
H
High-Level Shader Language
HLSL

I
 Instruction Set
T
Texture Stage
TexGen
Technique
P
Pass
Pixel Shader
Programmable-Pipeline
Post-Processing Effect
         R
Render States
Render Target
Render Target View
Render Group
S
Semantic
Scene Graph
Shader
Shader Manager
States
V
Vertex Shader

Annotation

Annotations add some information invisible to the Shader code, but that may be relevant for the 3D engine. Manual parameters can get an Annotation added at the end of their definition line. Note that in some cases annotations can also be added to Passes or Techniques.

See: Parameters

Default Shader

In the shader rendering execution process, the first step is to execute the Default Shader. The Default Shader is automatically created and executes first to ensure all states are initialized. The Default Shader allows you to only define certain specific Shader states (that differ from their default values) without having to concern yourself with defining every state, and it ensures that certain states do not retain undefined values from the previous rendering order.

The Default Shader's secondary purpose is to be a reference program, so that users can take it as a model, since all states and default values are listed, plus standard and additional Automatic Parameters (via semantics) are listed at the top. The Default Shader can be read in the Shader Editor, and one may copy elements from the Default Shader for pasting into a custom shader.

Note: Values of the Default Shader cannot be modified.

Effect

In DirectX 9, Effects are the enhanced version of DirectX 8 HLSL. In Virtools, Effects are special fixed-pipeline rendering functions like TexGen, BumpMapping, etc. For coherency, DirectX 9's Effects are simply called HLSL programs or Shaders within Virtools, while the term Effect is kept for fixed-pipeline rendering functions.

Fixed-Function

Hard coded rendering algorithms used by GPU on 3D graphics cards.

The real-time 3D card industry started building specialized chipsets (GPU - Graphic Processor Unit) meant to relieve the CPU from computing most common 3D tasks (flat shading, gouraud shading, perspective, texture mapping and some blending operations). Many of those chipsets made the success of SGI workstations, whose technology quickly trickled down to the game industry via 3D card manufacturers like 3dfx, NVidia and ATI. Until recently, the main drawback of these inexpensive 3D cards was that rendering algorithms were limited to the hard-coded functions (called Fixed-Functions - used in the Fixed-Pipeline) implemented by card manufacturers. This constraint is one of the reasons many 3D games look and feel alike.

See: Shaders Inside Virtools > Rendering Pipeline Overview

Fixed-Pipeline

Rendering path using only fixed-functions to perform the final rendering. Some Fixed-Functions of the Fixed-Pipeline are often replaced in recent cards by Programmable-Pipeline shaders.

See: Shaders Inside Virtools > Rendering Pipeline Overview

High-Level Shader Language

Also called HLSL, this C-like language developed by Microsoft and NVidia can be compiled into GPU assembly code. As integral part of Microsoft DirectX 9, HLSL has been retained as the integrated shader language within Virtools' 3D Engine.

See also: DirectX 9's Online Reference

HLSL

High-Level Shader Language (see above)

Instruction Set

An Instruction Set is a group of shader instructions that can be used to compile a shader function.

See Compliant Hardware chapter to get a list of Vertex/Pixel Instruction Set per 3D chip.

Pass

A Technique is simply a container for at least one Pass, and Passes are execute in the order in which they appear in their Technique statement. Basically Passes match rendering layers, and their layering produces the final rendering result.

Each Pass contain State initializations. One of these States is reserved to point to a potential Vertex Shader (VS) function - in which case the VS function is executed for all vertices of the currently rendered mesh's material - and the other is reserved to point to a potential Pixel Shader (PS) function, in which case the PS function is executed for all pixels of the currently rasterized mesh's material.

A Pass can be seen as a channel, but there's two main differences. First, a Pass can define more states (and thus be more customized) than a channel (which only define the texture and the blending modes). Secondly, a channel can be automatically combined with the first material rendering in order to make them render in one Pass, whereas a Pass can't be combined (it is a Pass...). However, several texture stages can be combined in the same Pass in order to achieve multi-layer rendering (see Texture Stage).

Pixel Shader

A Pixel Shader is a function defining operations to execute on each pixel of the faces being rendered. This part is optional, and if omitted, the GPU will only use the Render States to define pixels attributes (like pixel color, pixel blending, or depth value).

Programmable-Pipeline

The Programmable-Pipeline is the rendering path that uses programmable functions.

Increasing technological power (and frustration) prompted 3D card manufacturers to build a Programmable-Pipeline within their chipset, bringing back flexibility in real-time rendering algorithms. This effectively means that certain Shader rendering techniques once exclusively reserved for precalculated images are now possible in real-time.

See: Shaders Inside Virtools > Rendering Pipeline Overview

Post-Processing Effect

Mostly based on pixel shader(s), a Post-Processing Effect will always wait for a rendering to be done (Post), modify the resulting image (Processing), and display the altered image in place of the expected scene rendering. It is the basic idea behind effects such as Motion Blur, Global Antialiasing, Depth Of Field, Transition Screens, Convolution ...etc.

See: Render Target, Render Target View

Render States

States related to rendering process. Among Render States, we can find Vertex Pipe Render States (ex: vertex diffuse color) and Pixel Pipe Render States (ex: blending operations).

All other states are not considered Render States (ex: Transformation States, Light States, Sampler States, Shader States and Texture Stage States).

Render Target

A Render Target is an internal texture where renderings can be done through Shader BBs.

Render Target View

A Render Target View is the combination of a Render Target and a Viewport (rectangle in the Render Target).

Render Group

Group of faces sharing the same material. In most cases, a Render Group won't include faces of two separate meshes.

Semantic

To define a variable as an Automatic Parameter the user needs to add a Semantic at the end of the line. These are listed at the top of the Default Shader. A semantic should not be associated with more than one variable because a semantic defines a direct link between an existing 3D engine feature and a shader's variable.

Semantics are also used to define pixel and vertex shader function's input/output parameters. These semantics are not listed in the Default Shader, and are called intrinsic semantics.

See: Parameters .

Scene Graph

A diagram representing the hierarchical order in which 3D engine parses the scene elements in order to render them.

Shader

A Shader is a small piece of code that describes the way a surface is rendered (e.g.: shader language for Quake surfaces, or Renderman shaders). Nowadays (and in Dev), a Shader is a small piece of code executed by the GPU (on most 3D graphics cards) for each vertex and/or each pixel, hence the terms programmable Vertex Shaders and Pixel Shaders.

Shader Manager

The Shader Manager is a Virtools Manager that allows the Shader library (.dll) to communicate with the rest of Virtools' engine. The Shader Manager manages all Shaders and should not be confused with the Shader Editor (which is the user interface inside Virtools used to create, edit, compile and delete Shaders).

States

States are simple values (i.e. neither structures nor function, but just single type values) defining the Fixed-Pipeline behavior (i.e. which Fixed-Functions the Fixed-Pipeline should use).

States can define variables like the material's colors, material's texture or blending options, and also allows some predefined 3D transformations, as well as 2D texture coordinate transformations called TexGen (i.e. environment mapping).

- Standard Materials as well as Effect Materials in Virtools are only made of States.

- States are not evaluated for each vertex, nor are they for each pixel, but set only once per render group.

- Programmers need to understand States in order to fully master Shaders.

See: Shaders Inside Virtools > DirectX 9.0 High-Level Shader Language .

Texture Stage

A Texture Stage contain a texture, its blending with other stages, and its filtering. Depending on the 3D card capabilities, several texture stages can be combined inside the same pass to achieve multi-layer rendering.

It is always better to perform pixel operations in the same pass (like a diffuse texture combined with a lightmap); however, each 3D card has its own combination limit. It means that if you try to combine 4 Texture Stages (with Texture[n], ColorOp[n], ColorArg1[n], ColorArg2[n], AlphaOp[n], AlphaArg1[n] and AlphaArg2[n] states for example) while your 3D card only supports a maximum of 2 Texture Stages, then the effect won't work.

See Shader Compliant Hardware chapter to get a list of Maximum Texture Stages (pixel pipeline) per 3D chip.

TexGen

TexGen (Texture Coordinates Generators) are Fixed-Functions defined through States, that modify object's texture coordinates according to certain State values. Pseudo environment mapping, chrome effect or planar mapping can be achieved with TexGens.

Technique

A Shader is made of one or more Techniques: top level statement containing the rest of the Shader's instructions. A Technique is simply a container for at least one Pass.

Even if several Techniques are defined inside a Shader, one and only one Technique is used to render a Shader. If more than one technique is defined, the first Technique that the 3D card is capable of supporting is the one that is executed.

Note: A Shader may need more than one technique to ensure that cards supporting older ps and vs versions are accommodated. Techniques should be listed by their preferable order of execution (generally most recent vs/ps versions first). See: Shader Compliant Hardware for more details.

Vertex Shader

A Vertex Shader is a function defining operations to execute on each the vertex of the faces being rendered. This part is optional, and if omitted, the GPU will only use the States to define vertices' attributes (like vertex position, vertex color, vertex normal or vertex texture coordinate).


Shader Compliant Hardware

Overview

Some vertex/pixel shaders need enhanced instructions that are incompatible with previous vertex/pixel shader instruction set. In that case, if you try to compile with a vertex/pixel version instruction that is not supported by your card, you will get an error message and will be forced to compile with an appropriate instruction set.

Important: Even if a shader compiles on your PC with no errors, this does not mean it will execute on every 3D chip.

This is why - when coding an advanced shader - you should create several Techniques. If the first Technique cannot be executed on a particular 3D card, then the second one may work if it uses more basic instruction set (supported by an earlier shaders version). In order to let you target/code your shader for the right public, the list below shows which vertex/pixel shader versions are currently supported by major 3D cards.

Legend for the charts below:

- : Not supported.

TnL: No Vertex Shader support, but hardware Transform and Lightning is supported.

Vertex/Pixel Shader: Version listed is the best supported version (earlier shader versions are also supported).

Pixel Pipelines: Defines the number of pixels the 3D chip can process at the same time. This is useful information since it often matches the maximum Texture Stage supported in one rendering pass.

Manufacturer's Charts

ATI Technologies | NVIDIA | Matrox | STM / PowerVR
XGI | SiS | S3 Graphics | Trident | Intel | 3DLabs | 3dfx

ATI Technologies
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
3D Rage
-
-
1
3D Rage II
-
-
1
3D Rage Pro
-
-
1
Rage 128
-
-
2
Rage 128 Pro
-
-
2
Fury MAXX
-
-
2
Radeon SDR
TnL
-
2
Radeon DDR
TnL
-
2
Radeon LE
TnL
-
2
Radeon VE
TnL
-
1
7000
TnL
-
1
7200
TnL
-
2
7500
TnL
-
2
8500
1.1
1.4
4
8500 LE
1.1
1.4
4
AIW 8500
1.1
1.4
4
8800
1.1
1.4
4
9000
1.1
1.4
4
9000 Pro
1.1
1.4
4
AIW 9000 Pro
1.1
1.4
4
9100
1.1
1.4
4
9200 SE
1.1
1.4
4
9200
1.1
1.4
4
9200 Pro
1.1
1.4
4
9500
2.0
2.0
4
9500 Pro
2.0
2.0
8
9600 SE
2.0
2.0
4
9600
2.0
2.0
4
9600 Pro
2.0
2.0
4
9700
2.0
2.0
4
AIW 9600 Pro
2.0
2.0
4
9600 XT
2.0
2.0
4
9700 Pro
2.0
2.0
8
AIW 9700 Pro
2.0
2.0
8
9800 SE
2.0
2.0
4
9800
2.0
2.0
8
9800 Pro
2.0
2.0
8
AIW 9800 Pro
2.0
2.0
8
9800 XT
2.0
2.0
8

NVIDIA
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
Riva 128 ZX
-
-
1
TNT
-
-
2
TNT2
-
-
2
TNT2 Pro
-
-
2
TNT2 m64
-
-
2
TNT2 Ultra
-
-
2
TNT2 Vanta
-
-
2
TNT2 Vanta LT
-
-
2
GeForce SDR
TnL
-
4
GeForce DDR
TnL
-
4
GF2 GTS
TnL
-
4
GF2 Pro
TnL
-
4
GF2 MX
TnL
-
2
GF2 MX200
TnL
-
2
GF2 MX400
TnL
-
2
GF2 Ti
TnL
-
4
GF3
1.1
1.1
4
GF3 Ti200
1.1
1.1
4
GF3 Ti500
1.1
1.1
4
GF4 MX420
TnL
-
2
GF4 MX440
TnL
-
2
GF4 MX460
TnL
-
2
GF4 Ti4200
1.1
1.3
4
GF4 Ti4400
1.1
1.3
4
GF4 Ti4600
1.1
1.3
4
GF4 Ti4800SE
1.1
1.3
4
GF4 Ti4800
1.1
1.3
4
GeForceFx 5200
2.0
2.0
4
5200 Ultra
2.0
2.0
4
5600 SE
2.0
2.0
4
5600
2.0
2.0
4
5600 Ultra rev1
2.0
2.0
4
5600 Ultra rev2
2.0
2.0
4
5700 Ultra
2.0
2.0
4
5800
2.0
2.0
4
5900 SE / Value
2.0
2.0
4
5900
2.0
2.0
4
5900 Ultra
2.0
2.0
4
5950 Ultra
2.0
2.0
4

Matrox
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
G200
-
-
1
G400 Max
-
-
2
G450
-
-
2
G550
-
-
2
Parphelia 512
2.0
1.3
4
P 650
2.0
1.3
2
P 750
2.0
1.3
2

STM / PowerVR
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
PCX1
-
-
1
PCX2
-
-
1
Neon 250
-
-
1
Kyro
-
-
2
Kyro II
-
-
2
Kyro II SE
-
-
2

XGI
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
Volari V3
1.1
1.4
2
Volari V5
2.0
2.0
4
Volari V5 Ultra
2.0
2.0
4
Volari V8
2.0
2.0
8
Volari V8 Ultra
2.0
2.0
8
Duo V5 Ultra
2.0
2.0
8
Duo V8 Ultra
2.0
2.0
16

SiS
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
6326
-
-
1
300
-
-
1
305
-
-
1
315
TnL
-
2
Xabre 80
TnL
1.3
4
Xabre 200
TnL
1.3
4
Xabre 400
TnL
1.3
4
Xabre 600
TnL
1.3
4

S3 Graphics
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
Savage 3D
-
-
1
Savage 4
-
-
1
Savage 2000
TnL
-
2
Savage XP
TnL
-
2
Delta Chrome S4
2.0+
2.0+
4
Delta Chrome S8
2.0+
2.0+
8
Delta Chrome F1
2.0+
2.0+
8

Trident
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
Blade 3D
-
-
1
Blade XP
-
-
2
XP4 T1
1.1
1.3
4
XP4 T2
1.1
1.3
4
XP4 T3
1.1
1.3
4

Intel
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
i740
-
-
1
Extreme
-
-
1
Extreme2
-
-
2

3DLabs
3D Card Name
Vertex
Shader
Pixel
Shader
PS
Pipelines
Permedia
-
-
1
Permedia 2
-
-
1
Permedia 3
-
-
1
Wildcat VP560
1.1
1.2
(array)
VP760
1.1
1.2
(array)
VP870
1.1
1.2
(array)

3dfx
3D Card Name
Vertex
Shader
Pixel
Shader
Pixel
Pipelines
Voodoo (SST)
-
-
1
Voodoo Rush
-
-
1
Voodoo2
-
-
1
Banshee
-
-
1
Voodoo3 1000
-
-
1
Voodoo3 2000
-
-
1
Voodoo3 3000
-
-
1
Voodoo3 3500
-
-
1
Voodoo4 4500
-
-
2
Voodoo5 5500
-
-
4
Voodoo5 6000
-
-
8

Credits

Special thanks to N D Evanson who maintains the wonderfully helpful and informative 3D Chipset Specifications website: http://freespace.virgin.net/neeyik.uk/3dspecs/


Shader Recommendations

Recommendations

General HLSL Recommendations
Shaders Troubleshooting
Relevant readings

General HLSL Recommendations

- Investigate shaders sample compositions located inside the Virtools MiniSite (CMOs are located in Virtools Dev 3.0 > Documentation > CMOs > Technical Samples > Shaders).

- Shaders being a fast moving, recent technological advancement, the internet is an invaluable source to help you investigate further into HLSL programming, by browsing some of the many Shader articles that can be found online. The Microsoft website is particulary helpful in that regard for its DirectX 9.0 HLSL online reference.

- HLSL Programming Recommendation

It is always wiser to compute big caculations outside the shader code and pass the result in an exposed parameter, instead of making this big calculation inside the shader code. Remember: a vertex shader function is called for every vertices, and a pixel shader function is called for every pixels! So if a part of the code can be computed once for all vertices/pixels, then use Manual Parameters and compute its value from a virtools graph or VSL.

Shaders Troubleshooting

- A Shader may not compile in vs1.1 if it uses operations only available since vs2.0. Obviousy this is also true for pixel shaders and any piece of code needing recent operations. Go to the DirectX 9.0 > DirectX Graphics > Shader Reference (on the Microsoft website) to find out about standards and shader differences (between the various shader versions).

- A Shader may compile, but may not work in a 3D card if the 3D card does not support the compiled instuction (i.e. if it is not ps2.0 compliant for example)

- A Shader may compile and work, but not as fast as expected. This can happend if, for example, the Shader use ps2.0 instructions, and the 3D card doesn't support ps2.0. Note: This Pixel Shader may then be emulated by DirectX 9.0 or the driver itself, which is much slower than using the 3D card's GPU.

Relevant readings

  • Read the DirectX 9.0 HLSL Reference to read about HLSL Data Types, Statements and Expressions, Functions, Shader Semantics, Examples, Language Syntax, Lexical Convetions, Keywords and Preprocessor Directives.

    • DirectX 9.0 > DirectX Graphics > Shader Reference > HLSL reference
  • The Microsoft DirectX 9 Programmable Graphics Pipeline by Kris Gray; Microsoft Press; Book and CD-ROM edition (July 30, 2003).


Shaders FAQ

In addition to the answers presented here, more answers may be found in the Virtools' Swap-Meet Forum.

Q1. Can I create a function with States inside ?
Q2. Is the Default Shader called between Passes ?
Q3. Pass "B" is executed before Pass "A", why ?
Q4. Some of my States do not work, why ?
Q5. Can I see what's being rendered inside a Render Target View ?
Q6. How can I send more than one UV set to a Shader ?
Q7. Can I use a Shader and still use channel on my object ?

Q1. Can I create a function with States inside ?

No, because you cannot call a function from within a Pass, and States can only be defined inside a Pass.

Q2. Is the Default Shader called between Passes ?

As described in the Shader Execution Process chapter of Shaders Insider Virtools, the Default Shader is not called between passes; therefore, states set in the first pass are kept in the second Pass (unless of course, they are explicitly reset).

Q3. Pass "B" is executed before Pass "A", why ?

Every Pass inside a Technique is executed in the order of their definition in the shader source code. The name of the Pass has no influence on the order of execution.

Q4. Some of my States do not work, why ?

- Make sure your hardware supports that Direct3D capability (e.g. most cards do not support bump states for instance).

- A few states need additional processing that the Virtools engine may not provide (e.g., TweenFactor State needs an additional position set, while Virtools only provides one position set).

Q5. Can I see what's being rendered inside a Render Target View ?

Yes, just create a 2D Sprite and you will see the rendering result inside a Render Target View. It is a very handy way to debug typical post-process rendering.

The Render Scene In RT View building block offers an additional way to see the result of its RenderTarget rendering, through the pIn "Update System Memory". Checking this flag will force downloading the texture into system memory. This is quite a slow method and it requires that you checked the "Realtime setup update" flag in Virtools 3D Layout's Preferences window, however it still can be handy as you will then be able to see the texture be modified directly in the Texture Setup window.

 Q6. How can I send more than one UV set to a Shader ?

Just add a channel to the mesh, deactivate it and set source and destination blend modes to zero.
When a mesh's base material uses a Shader, all zero channels of the mesh are passed to the Shader as an additional UV set (in the same order as they appear in the channel list).
A zero channel is a channel which is not active and which blending modes have both been set to zero.

The Combine RT Views building block can also get several UV sets even if no real mesh is used. As described in the BB's online reference to do so simply add RT Views pIns.

Q7. Can I use a Shader and still use channels on my object ?

Yes, just ensure those channels are enabled.
When a mesh's base material uses a Shader, all non-zero channels of the mesh are skipped by the Shader (no UV set is created for them), and differed so they can be rendered separately.
A non-zero channel is a channel which is not deactivated or which blending modes have not been both set to zero (in other words, it's a standard channel).


Delivering Content

  • Exporting from Virtools

  • Virtools Web Player

  • Virtools Web Player Commands and Properties

  • Publishing a standalone executable


Exporting from Virtools

Overview

There are three types of file you can save from Virtools:

  • Composition Files (.cmo, .vmo)
  • Object Files (.nmo)
  • Script Files (.nms)

    • Saving and exporting a Composition (.cmo, .vmo)

    To save your composition in an editable format (.cmo), select Save or Save As from the File menu. CMO files can be edited in Virtools Dev, and played in your browser if you have already installed the Virtools Web Player.

    To save your composition in a read-only format (.vmo), select Export to Virtools Player from the File menu. Once a composition has been saved as a VMO it can no longer be opened in Virtools Dev. This means that your work is protected, as it is not possible to see what media or behaviors have been used. If you try to open a VMO, you will receive an error message "This content can only be opened in Virtools Player" in the Event Log.

    One advantage of exporting to the VMO format is that files are are consequently smaller than CMO files, as they contain no script representation.

    You can save Virtools files using compression, either for the CMO as a whole and/or for textures (individually or collectively). See General Preferences for further information.

    See the Virtools Web Player page for more information on the Virtools Web Player.

    Producing .exe files

    Executable files can only be produced by using the Software Development Kit (SDK). You should refer to the Virtools Dev SDK documentation for more information.

    Protecting Virtools Object (.nmo) and Virtools Script Files (.nms)

    In addition to being able to protect your compositions by using Export to Virtools Player described above, Virtools allows you to protect your scripts and entities (.nms and .nmo files) as well. When you choose to save either scripts or entities, you have the choice of selecting Hide script representation in Schematic. This means that your files may still be imported and used in Virtools Dev, only the BGs created in Schematic will not be visible.


Virtools Web Player Commands and Properties

1. Introduction
2. Virtools Web Player Properties
3. Virtools Web Player Commands - Overview
 4. Loading Commands
5. Fullscreen Commands
6. Run-Time Commands
7. Virtools ClassID

Introduction

This document describes the commands and properties you can use with the Virtools Web Player, Version 2.5. These commands and properties work with the following browsers:

- Microsoft Internet Explorer 4.0 and above
- Netscape Navigator/Communicator 4.5 and above.

You can call the commands or change the properties described here via JavaScript (both IE and Netscape) or VB Script (IE only).

Virtools Web Player

Most new properties and commands have been introduced with the Virtools Web Player 2.1 and 2.5. In addition to being listed here, these commands and properties are also documented in the MiniSite along with all other commands and properties. A (2.1) or (2.5) in brackets after a method or property indicates that the method or property was introduced with which Virtools Dev release.

Virtools Web Player Properties

AllowFullScreen
If set to 1, users can switch between Fullscreen and Windowed modes.

AllowPause (2.1)
If set to 1, the end user may pause the composition.

AutoPlay (2.1)
If set to 1, the Web Player will play the composition as soon as it has been loaded.

BackColor
Background color of the Web Player window before composition is launched. Specify the color as you would normally for HTML elements: "#rrggbb".

CompositionLoaded (2.1)
The Web Player sets this property to 1 when the composition has finished loading.

KeepKeyboard
If set to 0, the Web Player will only detect keyboard strokes if the composition is the active application/window.

RenderOptions (2.1)
Sets several rendering options for the Virtools Web Player.

SRC
Specifies the URL to the file to open. The path can be explicit or relative. In the case of a relative path, e.g. test1.cmo, the web player tries to download it in the same path as the web page. For example, with the web page http://www.virtools.com/test/test1.htm, the control will try to download the file http://www.virtools.com/test/test1.cmo.

Virtools Web Player Commands - Overview

There is a single method for all commands: String DoCommand(String Command).
DoCommand executes the command described by the Command parameter.
The format of this Command parameter is: CommandName 'CommandParam1' 'CommandParam2' ... 'CommandParamX'
This method returns a string describing the result of the command execution.

Loading Commands

Load: Stops any current playback, loads the file specified in the "FileName" parameter and starts playback when loading is complete.
Syntax: Load 'FileName'
Return value: "1" if successful, "0" else.

Play: Calling this command will start the playback of the loaded Virtools file.
Syntax: Play
Return value: "1".

Pause: Calling this command will pause the playback of the loaded Virtools file.
Syntax: Pause
Return value: "1".

Reset: Calling this command will reset the loaded Virtools file; play must be called afterwards to restart playback.
Syntax: Reset
Return value: "1".

CompositionLoadedEvents: (2.5) Show the path of the loaded composition.
Syntax: CompositionLoadedEvent (param)

VirtoolsError: (2.5) Show the potential message error from the Web Player.
Syntax: VirtoolsError (param1,param2)

Fullscreen Commands

FullScreen: Switch from Windowed mode to Fullscreen mode (ESCAPE to return to Windowed mode).
Syntax: FullScreen
Return value: "1" if successful, "0" else.

StopFullScreen: Switch back from Fullscreen mode to Windowed mode.
Syntax: StopFullScreen
Return value: "1" if successful, "0" else.

IsFullScreen: Returns the screen mode, "1" if the Web Player is in Fullscreen mode, "0" otherwise.
Syntax: IsFullScreen
Return value: "1" if the Web Player is in Fullscreen mode, "0" otherwise.

Run-Time Commands

For some of the commands presented here, you can choose to use a ClassID to optimise searching. ClassIDs are listed here in "8. Appendix A - Virtools ClassID" for your conveniance; for more detailed information on ClassIDs please refer to the Virtools SDK docuemntation.

Avoid having duplicate names in your composition when using ObjectName.

ActivateScript: Activates a script.
Syntax: ActivateScript 'ObjectName' 'ScriptName' ['Reset'] ['ClassID']
ObjectName: name of the script owner.
ScriptName: name of the script to activate.
Reset (optional): 1 to reset the script. 0 does nothing.
ClassID (optional): ClassID of the script owner. Optimizes the search of the object.
Return value: "1" if successful, "0" else.

DeactivateScript: Deactivates a script.
Syntax: DeactivateScript 'ObjectName' 'ScriptName' ['ClassID']
ObjectName: name of the script owner.
ScriptName: name of the script to deactivate.
ClassID (optional): ClassID of the script owner. Optimizes the search of the object.
Return value: "1" if successful, "0" else.

ActivateObject: Activates an object's script.
Syntax: ActivateObject 'ObjectName'
ObjectName: name of the object to activate.
Return value: "1" if successful, "0" else.

DeactivateObject: Deactivates an object's script.
Syntax: DeactivateObject 'ObjectName'
ObjectName: name of the object to deactivate.
Return value: "1" if successful, "0" else.

GetAttribute: Returns the value of the "AttributeName" attribute of an object identified by "ObjectName".
Syntax: GetAttribute 'ObjectName' 'AttributeName'

SetAttribute: This function returns "1" if the attribute has been correctly set; otherwise "0" is returned.
Syntax: SetAttribute 'ObjectName' 'AttributeName' 'Value'
ObjectName: name of attribute owner.
AttributeName: attribute to set.
Value: value to set.

SendMessage: Sends a message defined in the string "MessageName" to the object identified by "ObjectName".
Syntax: SendMessage 'ObjectName' 'MessageName'
ObjectName: object to send the message to.
MessageName: message to send.
Return value: "1" if successful, "0" else.

SwitchToCamera: Activates a Camera.
Syntax: SwitchToCamera 'CameraName'
CameraName: name of camera to be activated.
Return value: "1" if successful, "0" else.

GetCurrentScene: Returns the name of the current Scene or "NULL" if an error occurred.
Syntax: GetCurrentScene

GetLevel: Returns the name of the current Level or "NULL" if an error occurred.
Syntax: GetLevel

LaunchScene: Starts the scene named "SceneName" in the current content.
Syntax: LaunchScene 'SceneName'
Return value: "1" if successful, "0" else.

GetObjectID (2.1) : Returns the unique ID associated with the object of the given name. If you plan to use this command, you MUST avoid using duplicate names in Virtools (this means you cannot use the same name for an object and mesh for example).
Syntax: GetObjectID 'ObjectName' ['ClassID']
ObjectName: name of the object.
ClassID (optional): ClassID of the object. Optimizes the research of it.

GetObjectName: Returns the name associated with the object of the given ID.
Syntax: GetObjectName 'ObjectID'
ObjectID: ID of the object.

Virtools ClassID

For more information on Virtools ClassID, please see the Virtools SDK documentation.

// {PartOf:Class Identifiers}
#define CKCID_OBJECT 1
// {PartOf:Class Identifiers}
#define CKCID_PARAMETERIN 2
// {PartOf:Class Identifiers}
#define CKCID_PARAMETEROUT 3
// {PartOf:Class Identifiers}
#define CKCID_PARAMETEROPERATION 4
// {PartOf:Class Identifiers}
#define CKCID_STATE 5
// {PartOf:Class Identifiers}
#define CKCID_BEHAVIORLINK 6
// {PartOf:Class Identifiers}
#define CKCID_BEHAVIOR 8
// {PartOf:Class Identifiers}
#define CKCID_BEHAVIORIO 9
// {PartOf:Class Identifiers}
#define CKCID_SCENE 10
// {PartOf:Class Identifiers}
#define CKCID_SCENEOBJECT 11
// {PartOf:Class Identifiers}
#define CKCID_RENDERCONTEXT 12
// {PartOf:Class Identifiers}
#define CKCID_KINEMATICCHAIN 13
// {PartOf:Class Identifiers}
#define CKCID_OBJECTANIMATION 15
// {PartOf:Class Identifiers}
#define CKCID_ANIMATION 16
// {PartOf:Class Identifiers}
#define CKCID_KEYEDANIMATION 18
// {PartOf:Class Identifiers}
#define CKCID_BEOBJECT 19
// {PartOf:Class Identifiers}
#define CKCID_SYNCHRO 20
// {PartOf:Class Identifiers}
#define CKCID_LEVEL 21
// {PartOf:Class Identifiers}
#define CKCID_PLACE 22
// {PartOf:Class Identifiers}
#define CKCID_GROUP 23
// {PartOf:Class Identifiers}
#define CKCID_SOUND 24
// {PartOf:Class Identifiers}
#define CKCID_WAVESOUND 25
// {PartOf:Class Identifiers}
#define CKCID_MIDISOUND 26
// {PartOf:Class Identifiers}
#define CKCID_2DENTITY 27
// {PartOf:Class Identifiers}
#define CKCID_SPRITE 28
// {PartOf:Class Identifiers}
#define CKCID_SPRITETEXT 29
// {PartOf:Class Identifiers}
#define CKCID_MATERIAL 30
// {PartOf:Class Identifiers}
#define CKCID_TEXTURE 31
// {PartOf:Class Identifiers}
#define CKCID_MESH 32
// {PartOf:Class Identifiers}
#define CKCID_3DENTITY 33
// {PartOf:Class Identifiers}
#define CKCID_CAMERA 34
// {PartOf:Class Identifiers}
#define CKCID_TARGETCAMERA 35
// {PartOf:Class Identifiers}
#define CKCID_CURVEPOINT 36
// {PartOf:Class Identifiers}
#define CKCID_SPRITE3D 37
// {PartOf:Class Identifiers}
#define CKCID_LIGHT 38
// {PartOf:Class Identifiers}
#define CKCID_TARGETLIGHT 39
// {PartOf:Class Identifiers}
#define CKCID_CHARACTER 40
// {PartOf:Class Identifiers}
#define CKCID_3DOBJECT 41
// {PartOf:Class Identifiers}
#define CKCID_BODYPART 42
// {PartOf:Class Identifiers}
#define CKCID_CURVE 43
// {PartOf:Class Identifiers}
#define CKCID_PARAMETERLOCAL 45
// {PartOf:Class Identifiers}
#define CKCID_PARAMETER 46
// {PartOf:Class Identifiers}
#define CKCID_RENDEROBJECT 47
// {Secret}
#define CKCID_INTERFACEOBJECTMANAGER 48
// {PartOf:Class Identifiers}
#define CKCID_CRITICALSECTION 49
// {PartOf:Class Identifiers}
#define CKCID_GRID 50
// {PartOf:Class Identifiers}
#define CKCID_LAYER 51
// {PartOf:Class Identifiers}
#define CKCID_DATAARRAY 52
// {PartOf:Class Identifiers}
#define CKCID_PATCHMESH 53
// {PartOf:Class Identifiers}
#define CKCID_PROGRESSIVEMESH 54


Virtools Web Player

Overview

The Virtools Web Player allows users to view and interact with your content via the web. To place content in a HTML page, you just need to include a few tags (check latest version on Virtools , listed and explained below. If a user does not already have Virtools Web Player on their system, they will be directed to the Virtools Web Player download page.

Virtools provides a number of commands and properties that allow you to enhance the user experience. For detailed information and examples, check out the Virtools MiniSite (from the Start menu, select Programs, Virtools Dev, Virtools MiniSite).

NOTE: The Virtools MiniSite is installed by default, however if you chose not to install this component you will have to run the Virtools Dev setup.exe again

Web Player and System Resources

On some systems playing a composition can occupy a large part of available system resources, possibly causing the user's system to appear 'sluggish'. You are recommended to limit the playback possibilities of the Web Player by setting Time Settings in Virtools Dev before exporting your composition.

  1. Right-click Play
    the Time Settings dialog box opens

  2. In the Frame section, select the Limit radio button.
    The default is 60 FPS, which is sufficient in most cases.

  3. In the Behavior section, ensure the Linked to Frame Rate radio button is selected.

    Recommended Time Settings for web bound content

  4. Click OK.

These settings are saved along with the composition. Note that you can change any of the Time Settings at run-time using the Time Settings BB.

Creating a Web Page

First export your composition in a read only file format (.vmo). Choose the Export to Virtools Player command from the File menu.

From the File menu you can also choose Create a Web Page, a web page and a VMO file will then be created. The web page created contains the HTML Tags that will make the web browser start the Virtools Web Player.

You can also insert VMOs into a web page by manually inserting the HTML Tags described below.

Tags to Insert in a Web Page

To insert a VMO into a web page, embed the tag below into your HTML document, specifying the URL and the resolution of the Virtools file. This tag contains two statements, one for Internet Explorer and one for Netscape:

<OBJECT
CLASSID="CLSID:C4925E65-7A1E-11D2-8BB4-00A0C9CC72C3"
ID="Virtools" WIDTH=700 HEIGHT=200
CODEBASE=http://player.virtools.com/downloads/player/Install2.5/Installer.exe#Version=2,5,0,0">
<PARAM NAME="SRC" VALUE="http://www.yoursite.com/path/content.vmo">
<EMBED
SRC="http://www.yoursite.com/path/content.vmo"
TYPE="application/x-virtools"
PLUGINSPAGE="http://player.virtools.com/"
WIDTH="700" HEIGHT="200"
NAME="Virtools">
</EMBED>
</OBJECT>

Note: Go to http://player.virtools.com/downloads/update.asp for the most up-to-date embed tag of the latest Virtools Web Player.

Details:

  • The <object> tag is used for Internet Explorer while the <embed> tag is used for Netscape.

  • param name="SRC" value="" identifies the Virtools composition to be opened in Internet Explorer. You can use either a relative or absolute URL.

  • embed SRC="" identifies the Virtools composition to be opened in Netscape. You can use either a relative or absolute URL.

  • width="" and height="" define the size of your Virtools composition inside of the web browser window.

  • codebase="" identifies the Virtools Web Player for Internet Explorer to use with your composition. Note the #Version part of the attribute - for more details about the current version of the player visit: http://player.virtools.com/downloads/update.asp

  • pluginspage="" identifies the URL to download the Virtools Web Player for Netscape. For more details about the current version of the player, and how to detect the version of your user visit: http://player.virtools.com/downloads/update.asp

Inserting more than one VMO in a Page

You can insert more than one VMO in the same webpage, but each VMO must call a separate instance of the Virtools Web Player. To do this you just need to use a different ID (for Internet Explorer) and Name (Netscape) for each Web Player. For example, for instance 1 of the Web Player you would use the code as above, but for instance 2 you would change the Name/ID as shown below:

<OBJECT
CLASSID="CLSID:C4925E65-7A1E-11D2-8BB4-00A0C9CC72C3"
ID="Virtools2" WIDTH=700 HEIGHT=200
CODEBASE=http://player.virtools.com/downloads/player/Install2.5/Installer.exe#Version=2,5,0,x">
<PARAM NAME="SRC" VALUE="http://www.yoursite.com/path/content.vmo">
<EMBED
SRC="http://www.yoursite.com/path/content.vmo"
TYPE="application/x-virtools"
PLUGINSPAGE="http://player.virtools.com/"
WIDTH="700" HEIGHT="200"
NAME="Virtools2">
</EMBED>
</OBJECT>

The number of Web Players you can instance in a webpage depends entirely on the capabilities of the target machine.

Note: Go to http://player.virtools.com/downloads/update2.5.asp for the most up-to-date embed tag of the latest Virtools Web Player.

Linking your Website to our Web Player Installation Page

To let your visitors know that you have Virtools content on your site, and that they may need to download the Virtools Web Player, use a Virtools Web Player button linked to the Virtools Download Center (http://player.virtools.com).

For example:

<a href="http://player.virtools.com/" target="_blank" border="0">Button Graphic Here</a>

You will find a selection of Virtools logos in the Virtools Logos folder of the Virtools Dev CD.

Get Virtools Web Player! (opens new page)


Delivering Standalone Executable Applications

Standalone Executable Applications and DLLs

To publish your Virtools Dev composition as a standalone executable, you will need to use the Virtools SDK and have basic C++ programming experience. (Note: The creation of standalone executables falls under the EULA publishing rights described on the Virtools Website.)

For creating standalone executables, you have two possible solutions:

  1. Create a static executable (including DLL source code in the executable) using:
    - The source code provided in Virtools Dev\SDK\Samples\Standalone Player folder.
    - The .lib files provided in Virtools Dev\SDK\staticlib.
  2. Create an executable that calls DLL files:
    - using source code provided in the Virtools Dev\SDK\Samples\Standalone Player folder.

    In this case, you will have to deliver specific runtime version DLLs, found in the Virtools Dev\Redist\BuildingBlocks folder.

    Authoring version DLLs use the Virtools Dev interface, while runtime version DLLs do not use the Virtools Dev interface and are therefore optimized for runtime use. As stated in the Virtools Dev End User License Agreement, any distribution of standalone executables (that uses DLLs) requires that the executable use only runtime version DLLs, not authoring version dlls. (See the Virtools Dev End User License Agreement in your Dev root folder for more information.)

    IMPORTANT: In order to optimize your standalone player, do not include runtime DLLs listed below unless your composition actually uses a specific Dev addon pack (i.e. they are runtime DLLs for the Dev addon Packs):
    • Virtools Dev\Redist\BuildingBlocks\CryptedLoader.dll: VBS download module loader
    • Virtools Dev\Redist\BuildingBlocks\DatabaseClientModule2.dll: VBS Database module
    • Virtools Dev\Redist\BuildingBlocks\DownloadMediaClient2.dll: VBS download module
    • Virtools Dev\Redist\BuildingBlocks\MultiuserClient.dll: VBS multiuser module
    • Virtools Dev\Redist\BuildingBlocks\Physics.dll: Physic pack
    • Virtools Dev\Redist\BuildingBlocks\VRDistrib.dll: VR Pack distribution
    • Virtools Dev\Redist\BuildingBlocks\VRimmersive.dll: VR Pack immersion
    • Virtools Dev\Redist\BuildingBlocks\vs2_embedded.dll: VBS embedded multiuser module
    • Virtools Dev\Redist\BuildingBlocks\vsmanager2.dll: VBS


Keyboard Shortcuts

  • 3D Layout Keyboard Shortcuts
  • Level Manager Keyboard Shortcuts
  • Schematic Keyboard Shortcuts


Glossary

2 . 3. A . B . C . D . E . F . G . H . I . J . K . L . M . N . O . P . Q . R . S . T . U . V . W . X . Y . Z

This page contains definitions for and contextual information about words, phrases, and relationships that are used in a manner (perhaps) unique to Virtools.
Many of the definitions refer to one of the following fundamental terms, reproduced here for your convenience. Words that are capitalized have their own entries in the Glossary. Before you start reading the Glossary, we advise you to review the following entries:

How to Use the Glossary

Behavior

A description of how an element responds to the environment. Applying a Behavior makes an element interactive, either with the User or with other elements of the composition. The term Behavior is a general description and can be used in place of Building
Block (BB), Behavior Graph (BG) or Script.

Behavior Building Block, BB

The fundamental interactive elements within Virtools Dev, BBs encapsulate a specific task. BBs are a visual representation of a software element known as a function.

Behavioral Object, BeObject

 A CKClass. Any element, within a composition, to which a Behavior can be applied.

CKClass

A generic label for any class or class definition used by Virtools Dev.

Element

A generic label for any non-behavioral (non-BB, non BG, non-Script) "thing" within a composition.

NOTE: All BeObjects are Elements but not all Elements are BeObjects: neither a Parameter nor an ObjectAnimation are BeObjects yet both are Elements.

pName, Parameter Name

The name associated with a given Parameter Input (pIn), Parameter Output (pOut), Local Parameter, or Setup Parameter.

pType, Parameter Type

The type associated with a given Parameter Input (pIn), Parameter Output (pOut), Local Parameter or Setup Parameter.

pValue, Parameter Value

The value associated with a given Parameter Input (pIn), Parameter Output (pOut), Local Parameter or Setup Parameter.

Type, Data Type

A representation of a specific genre of information and the rules for determining the validity of the information. A type can be a CKClass.

For example, one of the most basic data types in Virtools Dev is integer. An integer is any whole number in the range -(2³¹) through +(2³¹ - 1). Therefore, the integer data type defines a genre of information: whole numbers and the rules for the range of legal values.

A 3D Entity is a much more complex data type and represents an object instantiated from the class CK3dEntity.

2

Definitions and CKClasses

A number of the entries in this glossary are for the classes within the Virtools Dev SDK. The headings for these entries are of the form:

2D Entity, CK2dEntity

The first term in the entry, 2D Entity, is the form used as a pType. The second term in the entry, CK2dEntity, is the formal name of the corresponding class within the Virtools Dev SDK. The formal name always starts with the letters "CK".

Terms and definitions

2D Curve, CK2dCurve

A CKClass. A graphical description of the relationship between two values. For example, in a Bezier Progression (Logics/Loops) you could use a pIn in the form of a 2D Curve to show acceleration.

2D Entity, CK2dEntity

A CKClass. An element with a position and scale in the screen's 2D coordinate system.

NOTE: The CKClasses 2D Sprite (CKSprite) and Sprite Text (CKSpriteText) descend from this Class.

2D Frame

An instance of CK2dEntity. A 2D Frame may have a Material and a Texture. A 2D Frame is typically used as a place holder when creating a user interface.

2D Sprite, CKSprite

 A CKClass. A 2D image rendered in the background (behind all 3D elements) or in the foreground (in front of all 3D elements), a 2D Sprite can be of arbitrary size.

2D Sprites are often used to create interface elements. However, whenever possible, use a 2D Frame (with a material and texture) for 2D Frames require a less processing power than 2D Sprites.

3

3D Entity, CK3DEntity

A CKClass. An element in Virtools Dev that has a position, orientation and scale in 3D space.

3D Frame

An instance of the class CK3dEntity. A 3D Frame has a position, orientation, and scale. A 3D Frame does not have an Author controlled Mesh. When visible, a 3D Frame is represented as a 3D cross.

A 3D Frame is often used as a reference point. For example, placing a camera according to the 3D Frame's position or orientation.

3D Object, CK3dObject

A CKClass. An element in Virtools Dev that has the characteristics of a 3D Entity and a Mesh.

3D Sprite, CKSprite3D

 A CKClass. An element composed of a 2D image that is rendered in 3D space. A 3D Sprite can have a position, orientation, and scale.

A

Absolute Coordinates

In 2D, a screen position expressed in pixels.

In 3D, a position expressed in the world coordinate system.

Ambient Color

 See Material Color.

Ambient Light

 A pName. The non-directional, background light in a composition.

Ancestor, Parent

 Any element, within a hierarchical relationship, that has one or more Child elements (children) or Descendents. Strictly, a Parent refers to the immediate Ancestor only.

Angle

A pType. A value expressed in the form Turns:Angle where Turns is the number of complete rotations and Angle is expressed in degrees.

NOTE: CK2 performs <Angle> calculations using radians and not degrees. There are 2*PI radians in 360 degrees. An Angle of 0:180, expressed as a Float, has a value of PI (approximately 3.14159)

NOTE: CK2 considers the pTypes <Percentage>, <Float> and <Angle> as being the same type.

Animation

A pName. A process by which an element is modified in 3D space, making the element appear dynamic (rather than static). An Animation is composed of Keyframes, where each Keyframe has a position, scale and orientation.

Animation Frame, Keyframe

 A pName. A Keyframe is a reference frame in an animation.

For example, a Keyframe in a Character Animation is typically a pose that captures the state of the character at a critical instant in an Animation. Keyframes are used to reduce the data storage requirement for an Animation. Intermediate Animation Frames (those frames required to maintain a smooth Animation between Keyframes) are constructed by a process of Interpolation.

Animation Step

 A pName. The current position within an Animation, expressed as a Percentage.

Applying a Building Block to an Element

Once attached, BBs are applied to a an element either

1. explicitly - if the BB is targetable and the Author has defined the target, or

2. implicitly - applied to the owner element, the element to which the Script containing the BB is attached.

Array, CKDataArray

A CKClass. A rectangular arrangement of cells, created as rows and columns, where the columns define the types of data stored in the array and where the rows contain values. Each cell contains a distinct data element. The data types supported by Arrays include:

  • Integer
  • Float
  • String
  • CKObject
  • Parameters

Attaching a Building Block to an Element

 BBs are attached to an element at the moment of mouse button release in a drag and drop operation.

Attribute

 A Parameter associated with a BeObject. An Attribute has a Name and may also have a Category. An Attribute typically consists of one or more Author-editable Parameters. However, some Attributes, such as ZBuffer Only, can not be edited by the Author.

For example, an element with the Floor attribute is identified to the Behavioral Engine as an element that should be treated as a floor so that Characters walk on the element and not through the element.

Virtools Dev includes numerous predefined Attributes. Authors can also define their own Attributes.

Author

 A person using Virtools Dev to create interactive content or an application.

Author Mode

 A state within Virtools Dev; Author Mode occurs when a composition is not playing, and the Behavioral Engine is not active.

Axis

 A pName. A vector used to define a coordinate system.

B

Behavior

 A description of how an element responds to the environment. Applying a Behavior makes an element interactive, either with the User or with other elements of the composition.

The term Behavior is a general description and can be used in place of Building Block (BB), Behavior Graph (BG) or Script.

Behavior Building Block, BB

 The fundamental interactive elements within Virtools Dev, BBs encapsulate a specific task.
BBs are a visual representation of a software element known as a function.

BBs can be categorized as:

1. Single Action: the BB completes processing within the current Frame. A Single Action BB can stand alone or be part of a Behavior Loop. Example: Set Fog (World Environments/Global).

2. Internally Looped: the BB is turned On and the BB is activated every Frame until the BB is turned Off. Example: Keyboard Controller (Controllers/Keyboard).

3. Externally Looped: the BB completes one step in the BB's process loop within the current Frame. If the Author wants the BB to operate in the typical manner, an external activation feedback loop is required. Example: Bezier Progression (Logics/Loops).

NOTE: An externally looped BB does not require that an external activation feedback loop be present. It is possible to construct a Script in a manner such that the external activation feedback loop is not required.

BBs can have one or more of

1. a Custom dialog box, denoted by a C in the lower left hand corner of the icon

2. internal Settings, denoted by an S in the lower left hand corner of the icon, or

3. a Variable configuration, denoted by a V in the lower left hand corner of the icon, that may include

3.1. a variable number of number of bIns

3.2. a variable number of number of bOuts

3.3. a variable number of number of pIns

3.4. a variable number of number of pOuts

3.5. the ability to change the type of one or more of the pIns and pOuts

4. The ability to send a message, denoted by a Sender icon in the lower left corner of the BB

5. The ability to receive a message, denoted by a Receiver icon in the lower left corner of the BB

The following terms are used when describing how BBs are processed.

1. Activate denotes the first time a BB is executed in a Frame.

2. Deactivate denotes that an internally looped BB is no longer active.

3. Trigger denotes that a BB is activated by the external loop feedback path.

4. Receive denotes that some BBs can be activated on more than one bIn per Frame; we say that the BB receives activations on the relevant pIns. Example: LIFO and FIFO (both in Logics/Streaming).

5. Store denotes that some BBs keep a record of received activations; we say that the BB stores activations. The BB then processes the record of received activations and generates new activations according to the rules of that BB. Example: LIFO and FIFO.

6. Generate denotes that some BBs generate more activations than the BB receives. Example: All But One (Logics/Streaming).

Behavior Graph, BG

 A graph composed of one or more of the following elements: BBs, Parameter Operations, Parameters, Behavior Links, Parameter Links, Comments, Shortcuts, other BGs, etc.. In other words, a BG is a visual representation of a Behavior.

At first glance, a BG can look almost exactly like a Script. However, a BG is distinct from a Script because the Author of the BG deliberately encapsulated the Behavior. The Author encapsulated and named the BG so that the BG can be saved and reused.

Virtools Dev treats a BG exactly the same as a BB. A BG can be attached to an element and applied to an element in the same manner as a BB.

A BG can be considered an Author defined BB that, to an Author, works in exactly the same way as a BB - a BG can have pIns, pOuts, bIns and bOuts.

NOTE: Any time the documentation for Virtools Dev refers to using a "(Behavior) Building Block" or a "BB" within a composition, the reader can substitute "Behavior Graph" or "BG".

A BG can be constructed by encapsulating a portion of a Script or all of a Script. A BG can also be constructed as an empty BG and elements added until the desired functionality is achieved.

A BG can be expanded to show the elements that make up the BG or collapsed to hide the elements that make up the BG.

An expanded BG is recognized by the surrounding bounding box and the three diagonal lines in the bottom right corner of the bounding box.

A collapsed BG looks like a BB with the following exceptions: the BG label is in Bold face and the type is Dark Gray in color.

Behavior Input, bIn

 Located on the left side of a BB/BG. Some part of the code within a BB is executed when a bIn is activated, deactivated, or triggered. Some BBs (particularly Logics/Streaming) can also receive and store activations. For example, the FIFO BB and the LIFO BB can receive N activations per Frame but both can only generate one activation per Frame.

Behavior Output, bOut

 Located on the right side of a BB/BG. Generally, a bOut activates when the processing to be performed by a BB in the current Frame (process loop) is complete. Some BBs (particularly Logics/Streaming) can also generate activations at their behavior outputs.

For example, the Keep Activated BB and the All But One BB both generate activations (activate more bOuts than bIns).

See Behavior Loop for further description of the processing done by a BB in a given Frame.

Behavior Link, bLink

 A link within a Script that propagates activations from bOuts to bIns. A behavior link can have a Behavior Link Delay.

(Behavior) Link Delay

 A bLink can have an associated delay, where the Link Delay is measured in Frames (process loops). The Link Delay can be:

1. 0 - propagate the activation within the current Frame

2. 1 - propagate the activation in the next Frame

3. n - propagate the activation in the nth Frame after the current Frame

Behavior Loop

 A series of BBs (and/or BGs) connected by bLinks. BBs are connected together in a manner that causes the BBs to be activated or triggered in a repetitive fashion.

In other words, a Behavior Loop is the visual representation of a repetitive operation. A repetitive operation is also known as an Iteration and the process of repeating an operation is also known as Iterating.

In any implementation of a repetitive operation, a significant concern is to ensure that there is an acceptable upper limit to the number of times that the operation repeats. In other words, there needs to be a mechanism to ensure that an operation is not repeated indefinitely.

Virtools Dev allows the Author to define the maximum number of operations that may be performed in a single Frame via the Max Behavioral Iterations setting in the Schematic.

NOTE: The default value for Max Behavioral Iterations is 8000. The value of Max Behavioral Iterations is saved with the composition.

Any Behavior Loop may have a cumulative delay of zero, as long as the loop is not constantly active and as long as the number of iterations in a Frame does not exceed the value of Max Behavioral Iterations. For example, Array and Group iterators (Logics/Arrays and Logics/Groups) often have a loop delay of 0 so that all elements within the Array or Group are operated on within a single Frame. However, the loop delay can be any positive value in the range of 0 to 32767.

NOTE: Looping BBs (such as Timer (Logics/Loops)) that are time-based require a cumulative loop delay of 1 Frame or the BB automatically changes to Frame-based processing.

Behavioral Object, BeObject

 A CKClass. Any element, within a composition, to which a Behavior can be applied.

Bezier (Curve)

 A pType. A Bezier Curve is a type of a 2D Curve (see Bezier Progression) as compared to Linear (see Linear Progression). A Bezier Curve is characterized by smooth transitions between curve segments.

Billboard

 A pValue. An orientation constraint applied to an element. An element with a Billboard constraint always faces the current viewpoint.
BodyPart, CKBodyPart

BodyPart, CKBodyPart

A CKClass. One or more 3D Entities combined to form a Character.

Boolean

 A pType. A data type with only two permitted values, represented as a check box. The check box is either selected (TRUE) or not selected (FALSE).

Bounding Box

 The smallest box or rectangular volume that encloses an element or set of elements. A bounding box is typically used in performing collision detection.

C

Camera, CKCamera

 A CKClass. An element that provides a viewpoint from which a composition is rendered.

NOTE: A Target Camera (CKTargetCamera) descends from this Class. A Target Camera is a Camera that always points towards its Target.

Cell

 A data point within an Array. For example, an Array with two rows and three columns contains six cells.

Character, CKCharacter

 A CKClass. A 3D Entity composed of one or more BodyParts, arranged as a Hierarchy. A Character typically has Animations.

Channel

 A pName. A Material added to a Mesh that blends with other Materials to create a visual effect. Virtools Dev supports a maximum of 10 Channels per Mesh.

Child, Descendent

 Any element, within a hierarchical relationship, that has a Parent (Ancestor) element. Strictly, a Child refers to the immediate Descendent only.

CKClass

 A generic label for any class or class definition used by Virtools Dev.

Class, Class Definition

 A template for a classification system; a description of a type of element. From object oriented design, a design technique used to group elements based on common characteristics and common behaviors.

Class Hierarchy

 A classification system whereby classes are related via parent - child relationships. A parent class is more general than a child class. A child class is a specialization of a parent class and inherits the characteristics and behaviors of the parent class unless specifically redefined in the child class.

CK2

 The Virtools Dev Behavioral Engine, responsible for the execution of all behaviors within a composition.

CK_ID

 A unique identifier assigned to every element in a composition. The CK_ID is assigned as the element is added to a composition. The CK_ID for a given element is regenerated every time a composition is loaded and is not guaranteed to remain constant between reloads.

CMO - Virtools Composition File

 An arrangement of one or more elements and associated behaviors, assembled within Virtools Dev. A composition contains a Level and, if defined by the Author, may contain Scenes and Places.

Curve, CKCurve

 A CKClass. An element formed by a set of Curve Points that define a series of line segments connected to create a single line.

Curves are open (the Curve forms a line) or closed (the Curve forms a loop). Curves and curve sections are linear (composed of straight line segments) or spline (composed of smoothly varying curves).

The Curve Points of the curve lie on the curve. The shape of the curve is changed by moving or editing the Curve Points.

Curves are 3D elements and can be made visible or invisible in Author Mode and Player Mode.

Curve Point, CKCurvePoint

 A CKClass. A 3D Entity used to define a Curve.

Custom Dialog Box

 A C in the bottom left corner of a BB indicates that a special dialog box is used to control how the BB functions. Example: Unlimited Controller (Characters/Movement), Keyboard Mapper (Controllers/Keyboard).

D

Default Orientation

The default relationship between an element and the world coordinate system. The Default orientation assumes that the element faces in the direction of the positive Z-Axis (Dir), that the top of the element is in the direction of the positive Y-Axis (Up) and that the right side of the element is in the direction of the positive X-Axis (Right).

Dependency (Options)

 A pName. How a copy or delete operation affects the CKObjects used by (aggregated with) that element.

For example, when deleting an element, the Author can choose to

1. delete the element only (No Dependencies)

2. delete the element, and all elements used by that element (Full Dependencies)

3. delete the element, and only selected elements used by that element (Custom Dependencies)

Descendent, Child

 Any element, within a hierarchical relationship, that has a Parent (Ancestor) element. Strictly, a Child refers to the immediate Descendent only.

Dest, Destination

 A pName. From Material, sets a surface's destination blending coefficient.

From Transformation, the end point of a translation. The Destination can be a coordinate (expressed as a Vector) or an element within the composition.

Diffuse (Color)

 See Material Color.

Dir

 A pName. The facing direction of an element, generally the positive Z-axis.

E

Element

 A generic label for any non-behavioral (non-BB, non BG, non-Script) "thing" within a composition.

NOTE: All BeObjects are Elements but not all Elements are BeObjects: neither a Parameter nor an ObjectAnimation are BeObjects yet both are Elements.

Emissive (Color)

See Material Color.

Extents

 A pName. The bounds or limits of an element, typically as projected onto another element or onto the planes defined by the world coordinate system.

F

Face

 A triangular geometric element formed by three Vertices, a part of a Mesh.

Flow (Activation)

 The order in which the BBs within a Script are processed. The activation flow follows a path through the graph formed by BBs and bLinks.

Frame, Process Loop

 A single pass through the processing of all elements of the composition.

Simplistically, Virtools Dev processes all behaviors then renders the scene for each pass through the process loop (Frame). Each pass through the process loop creates and displays a new image.

NOTE: Advanced Authors often refer to the process loop as a Frame or a rendering Frame. Do not confuse a Frame or a rendering Frame with a 2D Frame, a 3D Frame, or an Animation Frame.

G

Grid, CKGrid

 A CKClass. An element that divides the volume enclosed by the Grid into a 2D array of rectangular volumes known as squares. A Grid provides a mechanism for projecting an element's position in 3D coordinates to a 2D coordinate system.

Group, CKGroup

 A CKClass. A collection of references to elements, used to create a logical relationship between the members of the Group.

Guide

 In Author mode, a rectangular grid used to guide placement of elements.

Global State

 A global state is equivalent to a global parameter of boolean type, it is accessible from any script within the composition. It can be activated and desactivated, i.e. equivalent to TRUE or FALSE.

H

Hierarchy

 From object oriented design, a logical organization that enforces a parent-child organization on arbitrary elements.

For example, the file system on a computer is a hierarchical organization where each drive is organized as a hierarchy with the drive letter as the root of a given hierarchy. Organization proceeds in a tree-like structure where a drive can contain folders and files and where folders can contain further folders or files but files can not contain other files. Any folder is the parent to all folders and files within the folder. A folder within another folder is a child of the encompassing folder. Therefore, a folder can be both a parent to other folders and files and a child of another folder. A folder can have many children but a folder can only have one parent.

NOTE: That root is a relative term; any parent is also the root for all of that parent's child elements within a hierarchy.

Within Virtools Dev, a character is the most common form of a hierarchical element. The various elements that form the body (such as torso, legs, arms, etc.) are arranged in a hierarchical manner.

Hierarchies can be explored, created and altered using the Hierarchy Manager or BBs.

Hierarchy (pIn)

 A pName. A Boolean pIn in the form of a check box - if the check box is selected, then the BB affects the elements' children.

Homogeneous Coordinates

In 2D, a screen position expressed relative to the current screen resolution along each axis. Homogeneous Coordinates are used to ensure that, no matter the screen resolution, 2D elements can maintain a constant relative size and position.

Homogeneous Coordinates are limited to the range 0.0 to 1.0.

I

Initial Conditions

 A snapshot of the current state of an element; a record of the data internal to an element at the instant that the Initial Conditions are set.

On a Script, a record of the current values of the local Parameters and the current values of the input Parameters at the instant that the Initial Conditions are set.

Instance, Instantiation

 An Object is an instance of a Class; an Element that complies with or was created from a Class Definition. An Object is Instantiated from a Class Definition.

Interpolator, Interpolation

A BB that interpolates between two values, that calculates a value between the two values.
Interpolation determines the value at a given Percentage of the way between the first value and the second value.

Iterator, Iterate

 A BB that Iterates from a first value to a second value; for example: Counter (Logics/Loops). Iteration counts from a first value to a second value using a given increment per iteration.

A BB that Iterates over all members of a Collection; for example: Collection Iterator (Logics/Loops).

K

Keyframe, Animation Frame

See Animation Frame

L

Layer, CKLayer

 A CKClass. On a Grid, a set of values associated with each square of the Grid. Multiple Layers can be associated with a single Grid.

Light

 A CKClass. An element used to provide real-time lighting as opposed to using pre-lit lighting.

NOTE: A Target Light (CKTargetLight) is a Light that always points toward its Target.

Level, CKLevel

 A CKClass. The root element for a composition; the ancestor for all elements in a composition.

Local Parameter

 A Parameter contained within a Script, represented by a small rectangle. Local Parameters are either above Parameter Inputs (the small triangles on top of a BB/BG/paramOp) or situated by themselves within a Script. Local Parameters are connected to pIns by Parameter Links.

NOTE: Two unique Local Parameters are allowed to have the same name. However, this practice is not recommended due to the potential for confusion. For instance, when you copy and paste a Local Parameter, you copy the Parameter's name, the Parameter's type and the Parameter's value to a new local Parameter: these two Parameters are different, even though they have the same name (due to the copy and paste operation). The Author is encouraged to use unique names for each Parameter that they create.

Virtools Dev maintains a unique identifier for each local Parameter. To view a local Parameter's identifier (called the CK_ID), select "CK Properties" in the local Parameter's context menu.

M

Manager

 A Plugin that performs system wide tasks such as collision management.

Material, CKMaterial

 A CKClass. The surface characteristics of an element, how light affects the element. A Material often has a Texture.

Material Color

The perceived color of an element, defined by the way the element's Material interacts with the scene lighting. The Material Color has four components:

  1. Ambient Color describes how a Material reflects the ambient light in a scene. Ambient light and ambient reflection are nondirectional.

    Typically, the ambient light level in a scene is much lower than the diffuse light level. Therefore, ambient reflection typically has a lesser impact on the perceived color of a Material than diffuse reflection and is most noticeable when little or no diffuse light reflects off the Material.

  2. Diffuse Color describes how a Material reflects the diffuse light in a scene. Diffuse reflection is directional - the angle of incidence of the diffuse light affects the overall intensity of the reflection.

    Typically, the diffuse light is the dominant light source in a scene. Therefore, diffuse reflection typically plays the largest part in determining the perceived color of a Material.

    NOTE: The alpha value of the diffuse color is used for alpha transparency calculations.

  3. Specular Color describes how a Material reflects the specular light in a scene. Specular lighting is responsible for the creation of specular highlights on a Material.

    The appearance of a highlight is dependent on the viewing angle and the specular power. The greater the value of the specular power, the thinner the specular highlight.

  4. Emissive Color describes how a Material can be used to make a rendered object appear to be self-luminous. A Material's emissive color creates the illusion that a Material is illuminated (from within), without incurring the computational overhead of adding a light to the scene.

    NOTE: A self-illuminated Material does not act as a source of illumination for other elements.

Matrix

 An ordered collection of data. The local matrix and the world matrix associated with each 3D Entity are used to store the position, orientation, and scale of that element.

Mesh, CKMesh

 A CKClass. A collection of faces that define the geometric surface of an element. A Mesh is usually covered by a Material.

Message, CKMessage

A CKClass. A means of transfering information between elements or between Scripts. Typically, messages are used to signal a change in state, to request that some task be performed, and to signal that some task has completed.

NOTE: Messages always have a delay of one pass through the process loop. That is, a message is sent in the current Frame but the message is not received until the next Frame (process loop). In other words, messages experience a one Frame delay before they are delivered.

N

NMS - Virtools Script File

 A file containing a Script or a BG.

NMO - Virtools Object File

 A file containing one or more elements, with or without their applied Scripts.

Nodal Link

 A link between Nodes in a Nodal Path. A Nodal Link may allow movement in one direction only or in both directions. A Nodal Link also has a difficulty value used to determine the cost of following that Nodal Link.

Nodal Path, Path

 A map, composed of Nodes and Nodal Links between Nodes, used to predetermine the set of possible paths for an element between a source and a destination. Often used to determine the shortest allowed path between two points.

Node

 An endpoint for a Nodal Link, a junction between links in a Nodal Path.

Normalization, Normalized Value

A value constrained to the range 0.0 through 1.0 by scaling relative to a maximum value. A value is normalized by dividing that value by the value's maximum value.

O

Object

 From object oriented design, an instance of a class; an element rather than a description of an element (a class).

Obstacle

 An element tested by collision detection mechanisms.

Orientation

 The correlation between an element's Right, Dir, and Up vectors, an element's local coordinate system, and the world coordinate system.

Origin

 The point at which the vectors that define a coordinate system intersect.

P

Parameter

 Used to transfer data values between behaviors and to add information to BeObjects (through Attributes). Many behaviors use the values of their pIns to control their processing.

A Parameter has a name (pName) and contains a value (pValue) expressed in a given type (pType) such as integer, string, vector, etc.. A Parameter can be static (the value is fixed, such as a value entered by the Author) or dynamic (the value can change, based upon other factors). The value of a Parameter is provided to a Behavior or to a paramOp via a pLink or via a shortcut.

Parameter Input, pIn

 Data values received by a paramOp or by a BB. pIns have a source. pIns are represented by the small triangles on top of a BB/BG/paramOp.

In traditional programming terms, Parameter Inputs are the arguments to the function encapsulated by a BB, BG or paramOp.

Parameter Link, pLink

 A link that propagates a Parameter value either from a pOut or from a Local Parameter to a pIn.

NOTE: When a BB is added to a Script (in the Schematic) or to an element (in the 3D Layout), the links between the default Local Parameters and the corresponding pIns are not visible due to the scale of the image. However, the link is immediately visible if the Local Parameter is moved from the default location.

Parameter Operation, paramOp

 A simple operation performed on a single Parameter or performed between a pair of Parameters. A paramOp is only evaluated when the result is requested by another paramOp or a BB.

Many calculations and data retrieval operations (Get Value) are implemented as paramOps.

Parameter Operation Link

 A simple operation, automatically performed, on a single Parameter when a pOut is connected to a pIn of incompatible type and at least one paramOp exists to convert the pOut type to the pIn type. A Parameter Operation Link is a pLink that performs a type conversion.

The type conversion occurs automatically and the default paramOp icon is not displayed. Instead, a Parameter Operation Link is identified by the name of the paramOp displayed along the link. By default, a Parameter Operation Link is displayed in a different color than a pLink.

Parameter Output, pOut

 Data values generated by a paramOp or by a BB. pOuts have a destination. pOuts are represented by the little triangles on the bottom of a BB/BG/paramOp.

In traditional programming terms, pOuts are the values returned by the function encapsulated by a BB, BG or paramOp.

Parent, Ancestor

 Any element, within a hierarchical relationship, that has one or more child elements (children) or Descendents. Strictly, a Parent refers to the immediate Ancestor only.

Path, Nodal Path

 A graph composed of Nodes and Nodal Links between Nodes, used to predetermine the set of possible paths for an element between a source and a destination. Often used to determine the shortest allowed path between two points.

Percentage

 A pType. A value bound to the range 0.0 to 1.0, a value expressed as a percent in the range of 0% to 100%.

NOTE: CK2 considers the pTypes Percentage, Float and Angle as being the same type.

Place, CKPlace

 A CKClass. An abstract element used to define the elements found within a physical locale in a composition. A Place is a geometric construct used to define an area of related geometry.

For example, within a building, each room can be defined as a separate Place.

Places contain the elements within the Place. An element in a Place does not appear in the Global list of elements.

Places are very useful when using portal optimization to reduce the processing requirements of a composition.

Player

 An application, such as the Virtools Web Player, that can process and render a Composition.

Player Mode

 A state within Virtools Dev; Virtools Dev enters Player Mode when a composition is playing and rendered in 3D Layout.

Plugin

 A Dynamic Link Library (DLL) that extends the capabilities of the base CK2 engine.

pName, Parameter Name

 The name associated with a given Parameter Input, Parameter Output, Local Parameter or Setup Parameter.

Portal

 A connector between two Places, used by the Portal Manager to reduce the render processing requirements of a composition. A Portal is a special 3D Entity (a 3D Frame with a Portal flag) that is used to determine which Places are potentially visible from the current viewpoint and, therefore, rendered.

Priority

 Allows the Author to control the activation order of elements and behaviors in the current Frame.

By default, Virtools Dev implements a pure message passing model where each object acts independently and asynchronously. In a pure message passing model, there is no priority - each object exhibits the appropriate behavioral response to the received messages. However, there may be times when an Author must be able to guarantee the order in which behaviors are activated. Virtools Dev allows the Author to specify the activation order by controlling the priority of objects, scripts, BGs and BBs. The priority for an object or behavior can be set to a value in the range +32767 to -32768, where +32767 is the highest priority.

Behavior processing is performed in order of priority. The objects within a composition that have scripts attached are sorted from highest priority to lowest priority. The object with the highest priority is processed first.

If there are multiple Scripts attached to that object, the Script with the highest priority is processed first. All of an object's scripts are processed before proceeding to the next highest priority element.

Within a Script, if several BBs are attached to the Start (not recommended) and all BBs have the same link delay, then the BB with the highest priority is processed first.

If several elements have the same priority - then it is impossible to predict which element will be processed first - the Behavioral Engine will simply choose one at random. Controlling priority can be useful for resolving conflict when BBs, BGs, or scripts seem to be interfering with each other.

Process Loop, Frame

 A single pass through the processing of all elements of the composition. In the simplest model of the process loop, Virtools Dev executes all behaviors then renders the scene. More detailed models are available in the Virtools Dev SDK documentation.

NOTE: Advanced Authors often refer to the process loop as a Frame or a rendering Frame. Do not confuse a Frame or a rendering Frame with a 2D Frame, a 3D Frame, or an Animation Frame.

Progression

 A BB that iterates from a first value to a second value.

A Progression counts from a first value to a second value using a given increment per iteration. The increment can be fixed (Linear Progression (Logics/Loops)) or variable (Bezier Progression (Logics/Loops)).

Progression Curve

 A pName. A mechanism for visually describing the increment used at each step of a Progression.

pType, Parameter Type

 The type associated with a given Parameter Input, Parameter Output, or Local Parameter. A pType is expressed as <ptype>.

pValue, Parameter Value

 The value associated with a given Parameter Input, Parameter Output, or Local Parameter.

R

Referential

 A pName. The element used as the point of reference for an operation. Typically, the element used as the point of reference for calculating a Transformation (for example, a translation).

Render Object, CKRenderObject

 A CKClass. An element that is rendered, that is shown on-screen in the render window.

Resource

 Any element, BB, or BG, that can be directly imported into a composition (via drag and drop or file selection); any element in a Virtools Dev compatible file format.

Right

 If an element is assumed to be a Character, the direction of the element's right hand with respect to the origin of the Local Coordinate System.

Root

 The topmost element within a hierarchy. Root is also a relative term; any parent is also the root for all descendent elements within a hierarchy.

The Level is the root of a composition.

S

Scale

 A pName. A factor that describes the element's current size compared to it's original size.

Scene, CKScene

 A CKClass. An abstract element used to define the elements within a narrative unit of a composition. A Scene is a logical construct used to define a group of related elements and is not restricted to a geometric locale within a composition.

For example, scenes can be used to control which elements are active at what time: in this part of the story, only these elements are active whereas in that part of the story only those elements are active. Remember, only active elements are processed.

Scenes contain references to elements and not copies of elements or the elements themselves.

Scenes are very useful when attempting to reduce the processing requirements of a composition.

Script

 The visual representation of a behavior, applied to an element, as represented in the Schematic.

A Script is composed of two parts - a header and a body.

The header displays the name and owner of the Script, and optionally a small snapshot.

The Script body is composed of the Start and one or more BBs, BGs, paramOps, Parameters, bLinks, pLinks, comments, etc.

Mathematically, a Script is a graph whose nodes represent operations (BBs or paramOps) and whose edges represent possible paths of data flow (pLinks) and program flow (bLinks).

A Script is processed by following the bLinks as directed by the BBs contained within the Script.

Setting

 An S in the bottom left corner of a BB indicates that the BB has internal settings that can be edited through its' context menu.

Settings can take many forms. For example, Settings can control whether a BB is time-based or Frame-based (Linear Progression (Logics/Loops)), or what aspects of a BB are actually calculated at each activation (the Settings for Mouse Waiter (Controllers/Mouse) control what bOuts are available and, therefore, calculated each Frame).

Setup Parameter

A parameter available in the Setup for an element.

Sibling (Classes)

 Classes that share a common parent class.

Sound, CKSound

 A CKClass. A data set containing a digital representation of a sound.

NOTE: Midi Sound (CKMidiSound) and Wave Sound (CKWaveSound) descend from this Class.

(Parameter) Shortcut

 A Parameter Shortcut is similar to the desktop shortcuts used in Windows. A Parameter Shortcut is composed of a destination and a source, each identified by arrow icons.

A Parameter Shortcut is the only type of shortcut available in Virtools Dev and is usually referred to as a Shortcut.

A Shortcut is actually another instance of a particular Parameter. Therefore, the CK_ID of the destination has the same CK_ID as the source.

A Shortcut is dynamically updated and is often used to make a Parameter available across Script boundaries (the source is in one Script and the destination is in another Script) or used to make a Parameter available within a Script without using a pLink.

A Shortcut can also be used to make a Parameter available to multiple locations without requiring a pLink between the source and each destination.

NOTE: An Attribute is a Parameter attached to a BeObject. Therefore, a shortcut to an Attribute can also be created.

Specular

 See Material Color.

Specular (Light)

A pName. A directional light with the specular flag set, a light responsible for highlights on a Material.

 Sprite Text, CKSpriteText

A CKClass. A Sprite used to draw text on the screen.

Src, Source

 A pName. From Material, sets a surface's source blending coefficient.

From Transformation, the start point of a translation. The Source can be a coordinate (expressed as a <Vector>) or the identity of an element within the composition.

Start

 The leftmost icon within the body of a Script, the point at which a Script begins.

T

Target Parameter

 A special type of pIn used to explicitly identify the element affected by the Behavior.

When a Behavior is attached to an element, that element becomes the owner of the Behavior. Typically, a Behavior attached to an element is implicitly targeted at the Script owner.

For example, Translate (3D Transformations/Basic) normally modifies the position of its owner.

However, an Author may want a Behavior to affect a different element than the owner. In this case, the Behavior must be explicitly targeted by the Author at a different element.

Alternatively, an Author may attach a Behavior to an element of a different type than the type supported by the Behavior (for example, an Author can attach a Rotate behavior to a texture). A Target Parameter is automatically generated by Virtools Dev in the case of an incompatible class.

A BB is targetable only if there is a "T" in the targetable column (between the "Apply to" and "Description" columns) within the Building Blocks window.

If a Target Parameter does not already exist on a targetable behavior, a Target Parameter can be added by selecting "Add Target Parameter" from the context menu. A new pIn is created as the leftmost pIn. A Target Parameter input is identified by a pair of small squares (rather than the usual single small triangle for a regular pIn).

See also Applying Building Blocks to Elements.

Texture, CKTexture

 A CKClass. An image used by a Material to give an element a certain appearance. A Texture should have dimensions that are an integer power of 2 (e.g. 32 * 64, 128 * 128).

Transformation

 An operation that affects one or more of the position, orientation, and scale of an element.

Type, Data Type

 A representation of a specific genre of information and the rules for determining the validity of the information. A type can be a CKClass.

For example, one of the most basic data types in Virtools Dev is integer. An integer is any whole number in the range -(2³¹) through +(2³¹ - 1). Therefore, the integer data type defines a genre of information: whole numbers and the rules for the range of legal values.

A 3D Entity is a much more complex data type and represents an object instantiated from the class CK3dEntity.

U

Up

 The Y-Axis in the default orientation.

User

 A person interacting with a CMO or with an application created using Virtools Dev; the end user.

UV (Texture Coordinates)

 The coordinate system used to define texture coordinates on a 3D surface.

U and V coordinates are normalized to the size of the texture.

A UV coordinate of (0,0) indicates the top left corner of the texture.

A UV coordinate of (1,1) indicates the bottom right corner of the texture.

V

Variable

A V in the bottom left corner of a BB indicates that the Behavior is variable. That is, the Author can do one or more of the following:

1. add bIns,

2. add bOuts,

3. add pIns,

4. add pOuts,

5. change some or all of the types of the pIns and/or pOuts.

For example, Sequencer (Logics/Streaming) supports the construction of additional bOuts via the context menu. Parameter Selector (Logics/Streaming) supports the construction of additional pIns via the context menu.

NOTE: when changing pTypes, not all pTypes are available for all BBs.

For example, Calculator (Logics/Calculator) can accept pIns of pType <Float> or pType <Vector> only, whereas Identity (Logics/Calculator) can accept any pType.

The Author must check each behavior's documentation to determine the supported data types.

Vector

A pType. A directed quantity, a magnitude and a direction. A Vector is always defined relative to a Referential.

Virtools Dev uses two types of vectors: a Vector2D for 2D coordinate systems (for example, screen coordinates expressed as [X,Y]) and a Vector for 3D coordinate systems (for example, world coordinates expressed as [X,Y,Z]).

The magnitude of a vector (also known as the length of a vector) is defined as:

Vector2D Magnitude = SquareRoot(X² + Y²)
Vector Magnitude = SquareRoot(X² + Y² + Z²)
The magnitude of a vector can be calculated using the paramOp Get Magnitude:
Vector2D <Float> Get Magnitude <Vector2D>
Vector <Float> Get Magnitude <Vector>
The direction of a Vector is defined as a ray (a directed line) with the origin of the ray at the origin of the Referential and extending through the point (relative to the origin of the Referential) defined by the value of the Vector.

Vertex

 A point in 3D space, used to define a Face in a Mesh. A Face is defined with three vertices.

VMO - Virtools Player File

A composition that has been exported from Virtools Dev using the Export to Player command from the File menu. The contents of a VMO file are hidden and can not be opened or edited by Virtools Dev.

W

Workset

 An arbitrary collection of elements and scripts constructed in the Level Manager. A Workset is used to organize a composition (without regard to the type of an element) and to control the visibility (within the Schematic) of the Scripts attached to members of the Workset.


Send Comments to Virtools - Help Improve Virtools Documentation!

Use this form to send comments to Virtools about the Online Reference. Note that you must be connected to the Internet to use this form. If you are not connected to the Internet, you can alternatively send comments by e-mail.

Topic:
Name:
 Email Address (optional):
Comments:

Note: This form is not intended as a way for you to receive feedback or technical support. The information you provide will be used to enhance future updates to the documentation. Thanks!


Nodal Paths

Functions of a Nodal Path:

Nodal Paths are useful to easily create terrain information, and in the process, furnish a quick and simple way to determine the path that an object or character follow to get from one point to another, avoiding obstacles and utilizing the shortest path (or one of least resistance.)

Steps to creating a Nodal Paths:

- First, load the entities representing the background of your content. In our example, we'll work with these simple objects: a cube, a sphere, a plane and the letters of Virtools.

- You need then to create an empty group in the level view and apply it the Create Nodal Path behavior. Then you can go to the Schematic view and edit this behavior. A dialog box like the following one should appear.

The main tools to create your nodal path are in the toolbar at the right of the 3D View. They allow you to zoom and pan in your current view, create new nodes, move them, create one and two way links, delete nodes and links, and create nodes around obstacles.

Here is a full explanation of these buttons:

- Zoom: choose this tool and then click and drag the mouse cursor in the 3D view to move the camera toward and backward. Vertical movement of the mouse makes the camera zoom fast, when moving it horizontally makes the camera zoom slowly.

- Pan: select this tool and then click and drag the mouse cursor in the 3D view to move the camera in the two dimensions of the current view.

- Move Node: select this tool and then point and click a node in the 3D view, then drag it where you want it to be. The node will only move in the two dimensions of the current view.

- Create Node: This tool works in conjunction with some check boxes and some edit boxes at the left of the 3D View: Basically, when this tool is selected, it creates a node each time you click in the 3D View. If you check the automatically link check box, each newly created node will also create the edges linking it with the other nodes of the nodal path. If you validate "check for obstacles", when creating nodes, the system will check if the node can be created at this place, by checking collisions of a box centered on the node and with X and Z extents of [-Width,Width] and Y extents of [-Height,Height] with all the objects declared as obstacles (see Declare Obstacle behavior) and it will test also test the links to be automatically created with them. The last check box allow the user to check that the nodes and links will be on floors.

Nodes should be placed in strategic locations so as to thoroughly canvas your 3D environment. IE, for a character to avoid an obstacle regardless of the direction which he arrives at the obstacle, four frames will need to be placed at the four principal points around the obstacle (the Add Obstacle function do this automatically for you)

- Create Two/One Way Link: When selecting this tool, you can rapidly links all the nodes of your nodal path by selecting a first node ( which is then drawed in a different color and a different size ) and then selecting a second node. One Way links allow passage from the starting node to the ending node and Two Way link that permit passage in both directions. A one way link is useful for a passage on a slippery incline, allowing a character to slide down but not to climb up.

- Delete Node: Select this tool and then click a node to delete it and all the edges linked to it.

- Delete Link: Select this tool and then click two nodes to delete the link, if any, between them two.

- Add Obstacle: This tool is he little brother of the Add All Obstacles button. It creates 4 nodes at each corner of the picked object (if it is declared as an obstacle) the same way you create nodes manually. That means it will check for floors, obstacles and create automatically links if asked. The Add All Obstacles button do this fo all the objects declared as obstacle in the current scene.

Using these tools, we created a graph looking like this:

- Once the graph is in place, you can dynamically activate or deactivate the links with the Graph Window. The Graph Window contains all the nodes of the graph, and when you expand a node (it it has a little triangle on the left), you can see all the edges that leave it to go to listed destination nodes. By clicking on the little A next to the destination of each edge, if for example, you want a door that closes or a bridge that crumbles. If you want a two way link riding from A to B to be inaccessible from the two directions, don't forget to deactivate the edge B of node A AND the edge A of node B. Deactivated links will be represented in red in the graph.

These activations are static and saved with your graph but you can also dynamically (de)activate links and nodes (meaning (de)activating all the link going to/from this node) by using the Activate Link and Activate Node behaviors.

- Still in the Graph Window, you can see that there is a difficulty value next to each edges. It's a value that is used when finding the shortest path to go from one point to another (with behaviors such as Find Curved Path or Go To Node ). The less the difficulty is, the more likely the edge will be taken. A value of 1.0 is a standard difficulty.

- Once you've finshed the construction of your nodal path, you can test it with the Find Path button. Click the Find Path button, then click the starting node and the ending node and it will show you the shortest path to go, if any. You'll even have the time (in ms) of the shortest path algorithm on your graph in Graph Status, below the nodes number and the edges number. Try to keep your edges number low to lower the algorithm complexity.

Using the Nodal Path:

- When you finished creating your nodal path, you can use it with behaviors such as Find Curved Path or Go To Node. The first one create the shortest curve leading from the starting node to the ending node. The second behavior makes the owner character go to the selected node by taking the shortest path possible.

- If you move nodes at run time, you'll have to call the Update Nodal Path behavior because the distances between nodes are precalculated for speed and if you move nodes you'll have to recalculate edge distances.


////////////////////////////////
Virtools Exporter for 3DS Max///
////////////////////////////////

Versions

3DS Max			: 3, 3.1 or 4.0
Virtools Dev		: 2.0 (build 2.0.0.14 - release)
Virtools Exporter 	: 3.0 (build 2.0.0.14 - release)
This Document		: May 2001

For the latest versions of 3DS Max and other exporter plugins, please visit the Virtools website: <http://www.virtools.com/>

I) Description
--------------
This document describes how to use the Virtools Exporter for 3DS Max.

Before going any further, you should be aware of how an exporter plugin works: it takes information from a source format, in this case the 3DS Max format and converts it to a destination format, in this case the Virtools NMO format.

When converting this information, one of three things will happen:

- There is a direct equivalent in Virtools, so the result will be the same as what you have in 3DS Max
- There is no direct equivalent, so the element is translated into the nearest Virtools equivalent
- The feature is not recognized by the exporter, so it will not be translated at all.

The plugin converts the following elements:

- Geometry: Patch meshes and standard meshes.
- Materials: Standard type or multi/sub-object
- Lights: All standard lights from 3DS Max (FreeSpot, Target Spot, Omni, Target Direct, Free Direct).
- Cameras: All standard cameras from 3DS Max (Target, Free).
- Dummies: Dummy (in the sub-menu HELPERS)
- Animations: All types, however you are strongly advised to stick to Bezier, Linear or TCB types.
- Splines: only a "Shape" (created in 3DS Max under the submenu Shapes/Splines) containing ONE unique spline will be converted (to a 'Curve' in Virtools Dev).
- Groups: Groups as defined in 3DS Max.

II) Installation
----------------
The Max2Virtools plugin is installed by running setup.exe from the Virtools Dev CD:
1. select the 3DS Max plugin only
2. follow the on-screen instructions.

N.B. Ensure you select the correct version - i.e. the explorter plugin for 3DS Max 4 will only work with release 4, it will not work with release 3.1 for example!

III) Export Modes
-----------------
There are 3 export modes:

- "Export as Objects" - exports 3D objects (and simple object animations).
- "Export as a Character" - exports a single character and optionally one animation.
- "Export Animation Only" - exports a single character animation only.

a) Export as Objects
Export as Objects is used to export a scene. This mode produces a single NMO file and exports
- Geometry
- Lights
- Cameras
- Splines
- Dummies
- Groups (as Groups or Places)
- Object animations
Hierarchies are maintained. The animation of geometry, dummies and splines is also exported.

b) Export as a Character
Export as a Character is used to export a character only and produces one NMO file.
*** In this case you must only have a single root in your scene (the root of the character).***
You can also export one animation with the character at the same time. When using Physique for modeling characters, you are recommended to export in Skin for reduced file size. See "Exporting Characters and Animations from 3DS Max" and "Modeling with Character Studio" in the Online Reference for further information.

c) Export Animation Only
Export Animation Only is used to export additional animations only. A single NMO file is produced.

When exporting additional animations for characters you can only export one animation at a time. The character itself is not exported. As with exporting characters, your character must have a single root.

You can also export additional animations for objects using this mode.

IV) Exported Parameters and Important Notes
-------------------------------------------

a) Geometry parameters that are exported:
- Mesh
- Mapping Coordinates
- Smoothing Groups
- Normals
- Materials
- Vertex Color (including alpha value)

b) Mesh Sharing notes:
- If you use one or more instances of the same object (i.e. you create an object, decide to copy it and select the "create instance" radio button in "Clone Options") a single mesh is shared. Mesh sharing is exported to Virtools - all instances of the object are exported, however a single mesh is exported. You are highly recommended to use mesh sharing wherever possible as this greatly reduced file size!

c) Material parameters that are exported:
- Diffuse Map: Although not necessarily a restriction, you are highly recommended to use textures with dimensions to the power of 2 (e.g. 2, 4, 8, 16, 32, 64, 128 etc.).
- Diffuse: This color influences a lit material's appearance in Virtools unless its value is (255,255,255).
- Ambient Color
- Specular Color
- 2-Sided Flag
- Opacity
- Texture Cropping: Note that you cannot crop and tile a texture at the same time.
- Texture U/V Offset
- Face Map: the face map feature of the Material editor is exported.

d) Texture notes:
- These formats are supported: jpg, bmp, pcx, tga, png, tif. For further information, see the Supported Formats section of Images (Importing Media) in the Online Reference.
- Opacity Map: this parameter, used for alpha texture transparency, is exported. However, the Opacity Map must have the same size as the diffuse map.

e) Light parameters that are exported:
- On/off flag
- Color
- Range (only "Attenuation/Far/End" that limit the distance of the light).
- "Affect specular" flag
- Spot Lights only: HotSpot and Fall Off
- Direct Lights only: 3DS MAX allows the limitation of directional light inside a cylinder of influence. This cylinder does not exist in Virtools; therefore, the influence of the light will be felt on the whole scene.

f) Camera parameters that are exported:
- FOV
- Front and Back Clipping Planes
- Camera animations are currently NOT exported. You can work around this however, by creating a Dummy in Max and parenting the dummy to the the Camera in Max. The Dummy is therefore animated, and the animation exported.

g) Spline parameters that are exported:
- Only spline vertices are exported and are interpolated into a 'Curve' in Virtools.

h) Group parameters that are exported:
- The creation of a group results in the creation of a Dummy that is the parent object of the group. This element will be exported along with the hierarchy as a Virtools 3D Frame.
- To convert a Group to a Place, select the 'Convert groups to "places"' check box. Places can be used in Virtools Dev for Portal Management.

i) Animation (Characters and Objects) parameter notes:
- Do not relocate the pivot point relative to its object during an animation.
- You are advised to use Bezier, Linear or TCB animation controllers (Position, Rotation and Scale controllers). Prefer Linear wherever possible as this controller is fastest. The exporter can convert any unknown animation controllers (such as an IKController, PathController or procedural controller, etc..) to a standard animation by sampling the object animation. The "Frames per Sample" parameter of the "Controllers Output" section of the exporter dialog box defines the animation's sampling rate. For example a 100 frame long animation sampled at 3 Frames per sample will generate an animation with 33 keys. The lower the sampling rate, the higher the quality of the animation (as it will contain more keys), but consequently the larger the file size.
- 3DS Max also enables you to animate meshes with morph animations or modifiers such as bend, taper, etc... Virtools does not support such modifiers but the exporter can again convert them to a morph animation using the "Animated Object" sampling rate in the same manner as above. However file sizes will be larger as at each keyframe the mesh's topology is stored in the file.
- Warning: Modifiers that add or remove faces to an object during an animation will NOT be converted.
- In order for the animation to play correctly in Virtools, a Position/Rotation/Scale Key needs to be placed on the first and last animation frame on the root object of the hierarchy.
- 3DS Max allows rotation of angles of any value. Virtools' Rotation Key does not support absolute values greater than 360°. Exporting a Rotation Key with a value greater than 360° will result in an incorrect animation, so these rotations need to be subdivided in order to keep the values valid.
- Ensure a character only has a single root - animations for characters with more than one root will not play correctly
- If you choose "Convert to Skin" in the "Physique conversion" section for Characters created with Biped (Physique modifier of Character Studio), a sampling rate is used for calculating animations. Set this sampling rate in "Controllers" under "Frames per Sample" in the "Controllers Output" section.

j) Secondary Animation (Characters only) notes:
- To export just the secondary animation, delete all animation keys for the character except those animations keys used for the secondary animation. For example, a character's primary animation is a walk, the secondary animation is the character moving its head. The character walks, and at the same time, moves its head when the secondary animation is triggered.
- If you use Character Studio, you must select the Biped objects (the Biped "bodyparts") used for the secondary animation, then choose "Export Selected" from the File menu to export the secondary animation.
- Choose the export mode "Export Animation Only" in the Virtools Export dialog box.

k) Hierarchy note:
- When an object is selected for exportation, all the parent objects are also exported to preserves the coherence of the hierarchy and animations. This convention is used by 3D Studio MAX when saving a selection.

V) Referencing Textures
-----------------------
- You can choose to reference textures and not include them in the NMO file created when exporting. To reference textures, select the "Store only texture filenames" check box under the "General Options" section of the Exporter dialog box. To access these textures from within Virtools Dev, place the textures into the textures folder of a data resource.

VI) Troubleshooting
-------------------

a) Objects do not export correctly.
=> Ensure you use Reset XForm on them BEFORE constructing hierarchies or animations. Use the following procedure:
  1) Create the objects.
  2) Reset XForm on them:
    a) Select all objects.
    b) Select "ResetXForm" in the "Utility" panel.
    c) Select "Reset Selected" in the Utility's submenu.
    d) Verify that the Normals on the face of each object haven't been inversed during Reset XForm. Flip the Normals over if that is the case.
    e) Save to 3dStudio MAX format in order to conserve the file for reference purposes.
  3) Proceed to implement hierarchies and/or animations.
=> Do not use operations that modify the axis system (such as Mirror Selected Objects from the toolbar - use the modifier instead) as this impacts geometry conversion during export.

b) An animation does not export correctly (including Characters that "moon-walk").
=> Verify that the character has a unique root.
=> Verify that the root object's animation track has a Position key on the first and last frame of the animation.
=> Verify that the Rotation Keys do not contain values greater than 360° or less than -360°.
=> Verify that the character *really* translates and does not just perform its animation "in place" or "on the spot".

c) A secondary animation does not export correctly.
=> Check that animations keys are only set for the object being animated.

d) Wrapping settings are not correctly converted.
=> You can change the Wrap Mode in Virtools using the BB Set Wrap Mode (Materials-Textures/Basic).

e) Splines are not correctly exported.
=> Splines may be converted into "Editable Mesh" during the course of certain operations in 3DS Max. In such cases, they are exported as Geometry.


/****************************************/
/*   Virtools Exporter for LightWave
/****************************************/

Versions

LightWave		: 6.5 , 7.0 and 7.5
Virtools Dev		: 2.0, 2.1 and 2.5
Virtools Exporter	: 1.6, February 2003
This Document		: 1.6, February 2003

For the latest versions of the LightWave and other exporter plugins, please visit the Support section of the Virtools website: <http://www.virtools.com/>

--------
CONTENTS
--------
1 - Description
2 - Installation & Activation
3 - Exporting from the Modeler
4 - Exporting from the Layout
    4.0 Summary
    4.1 Scenes
    4.2 Characters
    4.3 Virtools Exporter Dialog Box
5 - Exported Parameters and Important Notes
    5.1 Notes about IK
    5.2 Notes about texture and color managment
6 - Known Bugs/Troubleshooting
7 - Versions
    7.0 Changes Since v1.5
    7.1 Changes Since v1.4
    7.2 Changes Since v1.3
    7.3 Changes Since v1.2
    7.4 Changes Since v1.1
    7.5 Changes Since v1.0
    7.6 Changes Since beta 2.0

---------------
1 - Description
---------------
This document describes how to install, activate and use the Virtools Exporter for LightWave.

Before going any further, you should be aware of how an exporter plugin works: it takes information from a source format, in this case the LightWave format and converts it to a destination format, in this case the Virtools NMO format.

When converting this information, one of three things happen:

- There is a direct equivalent in Virtools, so the result will be the same as what you have in LightWave
- There is no direct equivalent, so the element is translated into the nearest Virtools equivalent
- The feature is not recognized by the exporter, so it will not be translated at all.

The Virtools Exporter for LightWave can export from either the Modeler or Layout.

-----------------------------
2 - Installation & Activation
-----------------------------
The installation program copies all needed files to the correct folders.  You still need to activate the plugin as any other LightWave plugin, in *both* the Modeler and Layout.  Next you add Exporter commands to the interface: this is optional (but recommended) for Modeler, and mandatory for Layout.

- To Activate the plugin
1. Open the Add Plug-ins menu:
    * From the Modeler menu, choose Plug-ins then Add Plug-ins.
    * From the Layout menu, choose Plug-ins then Add Plug-ins.
2. In the dialog box that appears, browse to the LightWave Plugins folder (LightWave\Programs\Plugins) and select VirtoolsLW.dll
3. Click Open.

- To Add the Exporter command in Modeler
The first time you want to export from Modeler, you are advised to add a command to the Modeler interface.
1. From the Modeler menu, choose Interface then Edit Menu Layout.
2. In the left panel, choose Virtools_Export_Layout in the Additional folder.
3. In the right panel, select the Menu to which you want to add the Virtools Exporter command, and press the Add button
4. Close the panel.

- To Add the Exporter command in Layout
The first time you want to export from Layout, you *must* add a command to the Layout interface.
1. From the Layout menu, choose Interface then Edit Menu Layout.
2. In the left panel, choose Virtools_Export_Layout in the Plugins folder.
3. In the right panel, select the Menu to which you want to add the Virtools Exporter command, and press the Add button
4. Close the panel.

------------------------------
3 - Exporting from the Modeler
------------------------------
NOTE: The exporter does not show a Virtools Exporter dialog box when exporting from Modeler, it simply exports all elements in foreground layers only.

- To Export from Modeler
1. Choose the Exporter command.  Either
    * From the Construct tab, choose Additional then Virtools_Export_Modeler, or
    * Choose the Virtools_Export_Layout command you added to the interface above in section "2 - Installation & Activation".
2. Choose a folder and filename to save to in the dialog box that appears and click OK.
3. Export is successful unless LightWave displays an error message.

-----------------------------
4 - Exporting from the Layout
-----------------------------

4.0 - Summary
-------------
- To Export from Layout
1. Choose the Virtools_Export_Layout command you added to the interface above in section "2 - Installation & Activation".
2. Choose a folder and filename to save to in the dialog box that appears.
3. Choose the elements you want to export, set any parameters (see next section) in the Virtools Exporter dialog box, and click OK.
4. Export is successful unless LightWave displays an error message.
NOTE: Read section "5 - Exported Parameters and Important Notes" carefully to be sure of which elements the exporter can export, and how certain parameters are handled.

4.1 - Scenes
------------
You can export scenes with or without animation.  All items in the scene are taken into account by the Exporter.

- To Export a Scene
1. Choose the Virtools_Export_Layout command you added to the interface above in section "2 - Installation & Activation".
2. Choose a folder and filename to save to in the dialog box that appears.
3. Select the check boxes for the items you wish to export, and click OK.
NOTE: to export a scene without any animations, make sure you clear all check boxes in the Animations section of the Virtools Exporter dialog box.

4.2 - Characters
----------------
You are advised to export your Character and animations in separate NMO files.

See the Virtools Dev User Guide or Online Reference (from the Virtools Dev Help menu) for information on how to import Character and animation files to your scene in Virtools Dev, and how to attribute and configure animations.

- To Export a Character only
1. Choose the Virtools_Export_Layout command you added to the interface above in section "2 - Installation & Activation".
2. Choose a folder and filename to save to in the dialog box that appears.
3. Ensure the following check boxes are selected: Export Objects, Export As Character.
4. Ensure the following check boxes are not selected: Export Lights, Export Cameras, Export Animations.
5. Select the Export Bones check box only if your Character uses Bones.
NOTE: If you are using LightWave 6.5 you must check the Bones Falloff Type in the LightWave interface, and select this value from the Bones Falloff Type menu in the Virtools Exporter dialog box.  LightWave 7 users do not need to do any of this.
6. You can select the remaining check boxes if you wish:  Prelit, External Textures, Build Normals.
7. Select the Character Root Object from the drop-down list, and enter a name for Character Name.
8. Ensure no check boxes in the Animation section are selected, and click OK.

- To Export a single Character Animation only
1. Choose the Virtools_Export_Layout command you added to the interface above in section "2 - Installation & Activation".
2. Choose a folder and filename to save to in the dialog box that appears.
3. Select the Export Animation Only check box (this automatically clears all check boxes that have nothing to do with exporting only animations).
4. Set the Starting Frame and Ending Frame parameters for your animation.
NOTE: A single LWS file can contain several animations, with each animation in a separate frame range. In this case you must enter Starting and Ending Frames to export the animation correctly.
5. Select any of the remaining check boxes if you want the exporter to take these parameters into account: Sample Animations, Export IKAnimations, IK : Dont export Frame 0, Export Morph, Animations Saved in Linear.

4.3 - Virtools Exporter Dialog Box
----------------------------------
The Virtools Exporter dialog box only appears when you export from Layout.  Select the check boxes of elements you want to export.

* Export Objects
* Export Lights
* Export Cameras
* Prelit - export vertex color for all elements.
* External Textures - a reference to Textures is saved in the NMO file. The reference consists of the filename only; to *see* the Textures in Virtools Dev you must place them in a Data REsource or add a data path using the Path Manager in Dev.  For more information, consult the Virtools Dev Online Reference (Online Reference from the Help menu).
* Export Bones
* Bones Falloff Type (required for LightWave 6.5 only) - select bones falloff mode.
* Build Normals - If selected, Normals are built according to the LightWave parameters "Smoothing" and "Smoothing Threshold" (in "Surface Properties").  This results in exported meshes having more vertices, meaning that rendering in Virtools will be closer to the rendering in LightWave, but rendering (in Virtools) takes more time/resources. If left unselected (default), Normals are calculated so that the mesh is automatically smooth, but non-smooth surfaces export as flat materials.
NOTE: If your usual "Smoothing Threshold" is about 90 for all surfaces in the scene, it would be better to leave the "Build Normals" check box unselected.
NOTE :
a vertex can have different uvs : if 2 polygons share the same vertex, this vertex can have (uv1) on polygon1 and (uv2) on polygon2, with (uv1) not equal to (uv2). If a scene contains vertices of this kind, the "Build Normal" option should be checked.

* Export As Character - export a single character.  When exporting a Character, you are recommended to export that Character only without any other elements.
* Character Root Object - you *must* specify the root (main parent) object of the character when exporting a character.
* Character Name - the name of the character if you want to export a character.

* Export Animations Only - export only object and bone animations.
NOTE: Selecting the "Export Animations Only" check box automatically clears any check boxes incompatible with this option.
* Export Animations - export the animations of any animated elements in your scene.  Selecting just this check box and no other element will export animations only.  Note you can only export a single character animation at a time.
* Sample Animations - select if you want to sample keyframe animations with a constant step (in frames) instead of using the keys created in LightWave.
* Export IK Animations
* IK : Dont export Frame 0 - in some cases, IK export does not work if this check box is not selected (e.g. BBotDrop.lws among LightWave samples).
* Sampling Rate (frame) - sampling rate for animations. For example, a 100 frame long animation sampled at 3 Frames per sample will generate an animation with 33 keys. The lower the sampling rate, the higher the quality of the animation (as it will contain more keys), but consequently the larger the file size.
NOTE: Morph/IK Animation are always sampled; keyframe animations are only sampled if you select Sample Animations above.
* Export Morph - select if you want the animation to be exported as a morph-type animation and not keyframe type. Morph animations result in larger file sizes than keyframe animations, as at each sampled keyframe the mesh's topology is stored in the file. Morph animations and bone animations are not compatible, you can choose both theses options at the same time, but only Morph animations will be taken into account for the mesh deformation.
* Animations Saved in Linear - Animations are automatically saved in linear. Otherwise, the only other type supported is TCB, all other types of animation are exported as linear.
* Starting Frame - animation will be exported from that frame
* Ending Frame - animation will be exported to that frame

-------------------------------------------
5 - Exported Parameters and Important Notes
-------------------------------------------
Objects
* Faces with more than 3 vertices *are* supported.
* Patch meshes are supported with the precision defined in Layout ("Display Subpatch Level" in Object Properties)
* Object hierarchies are exported.
* Objects without meshes are converted to 3D Frames.
* A single mesh must not have more than 65535 vertices (this is a limit of DirectX/OpenGL, not Virtools).
NOTE: Leaving the "Build Normals" check box unselected results in exported meshes that have less vertices.

Material Parameters
* Base colors are used for Diffuse, Emissive and Specular, Ambient is set to black.  Note the following translations (LightWave to Virtools):
  Diffuse      -> Diffuse
  Luminosity   -> Emissive
  Specular     -> Specular
  Glossiness   -> Specular Power
  Transparency -> is Color.Alpha
* Both-sided Materials are taken into account.

Textures
* Only is exported the first Texture slot whose first layer is an image texture, from Color, Luminosity and Diffuse texture slots.
* Only image Textures are supported, other kind are ignored.
* All types of Projection are supported for Texture coordinates (including Atlas).
* UV Mapping Coordinates are supported.
* UV Wrapping is supported (but the wrapping mode must be the same for both U & V).

Lights
* Note the following translations (LightWave to Virtools):
  Distant	=> Parallel
  Point 	=> Point
  Spotlight 	=> Spot (approximate)
  Linear 	=> Point
  Area 		=> Point
* Attenuation mode is not exported for LightWave 6.5. For LightWave 7, only "Off" and "Linear" attenuation are exported.

Cameras
* FOV is exported (approximate).
* Camera animations are exported.
* Clipping Planes are not exported but can be set in Virtools Dev.

Animations
* Position, orientation & scale keys are taken into account.  If a key is missing, the exporter still creates a full key (e.g. at frame 10, if there is a position key for X & Y only, but not Z, the exporter estimates Z at frame 10).
* Keyframe animations supported.
* TCB animations supported.  Note the exporter stores a keyframe as an X, Y, Z key.
* For animations of 180 degrees or more, you must place at least one keyframe at 179 degrees or less or the animation will not export correctly.
* For all types of character animations, pay attention to what you are doing with the FloorRef When walking or running, the character should stay at a constant height from the FloorRef object. When jumping, the Character should increase it's distance from the FloorRef object to give the appearance of translation away from the floor. Characters should ALSO have a "stationary root" that only moves relative to the floor reference (e.g. for walking, jumping etc.) but that does not move constantly (i.e. in an idle animation the root should not move). This is very important if you wish to use your Characters with the Virtools Mulituser Pack, or the dead reckoning algorithm used for predicting distributed objects will not work correctly. In short:
   - Make sure the (stationary) root element does not move at all when the character is in its default ('wait' or 'idle') animation.
   - For other animations make sure the root moves a minimum; in a walk animation along the Z axis for example, make sure that the root moves along the Z axis only - there should be no movement on the X or Y axes.
* Ensure any character animations you create are 'real' in the sense that the Character actually performs them and does not 'pretend' to perform them - e.g. for a walk animation you should ensure that your character actually moves (translates) in your modeling application,   and does not perform the animation in situ ("on the spot" or "in place")

Characters
* Characters must be organised in a hierarchy from a single root.
* Character keyframe animations are supported.
* Characters animated by bones are supported.
* Character animations can be exported uniquely, without the Character or any other elements.

Bones
* Note when some bones use a weight map, and some others don't use any, and share the same vertex that is in the weight map, only bones using weight map will affect that vertex.
* Bones Strength is not exported.  Note you must give the bone attenuation value in the Virtools Exporter dialog.

IK
* IK is supported, but you must not save your file after using the Virtools Exporter as some keyframes may have been added.

Morph
* Morph is supported, however combining bone & skin and morph animations on the same object/character will result in only the morph animation.
In LightWave 6.5, please set the Bounding Box Threshold so that it includes the whole scene (so when you press the play animation button, you should not see bounding boxes instead of meshes). This settings is in Display Option Panel.

Color Map & Prelit
* Supported - when an object is linked to a colormap, it will be automatically export as prelit. However, if the "Prelit" button is checked, all objects will be exported as prelit.

Lightmap
* Textures with several layers are supported.  However as the blending mode is not supported, the export is approximate. You can set the blending mode in Virtools.
* Layer Opacity is supported - note that if layer opacity is 100%, diffuse color is set to white. Otherwise diffuse is set between LightWave color and white according to opacity.

Motion Options - Match Goal Orientation function (exporter for LightWave 7 only - available in "Motion Options")
* If used, the animation of the object using Motion Options is sampled using the "Sampling Rate" parameter value, since orientation may be different from what is stored in LightWave for all frames (so even if there is 1 animation key for concerned object, if frame total = 60 and sampling rate = 2, there will be 31 rotation key exported).

Motion Options - Target Item
* If used, the animation of the object using Motion Options Target Item is sampled using the "Sampling Rate" parameter value, since orientation may be different from what is stored in LightWave for all frames

5.1 - Notes about IK
--------------------
* There is another plugin in lightwave exporter, named "VirtoolsIKExporter" Motion plugin.
This is a motion plugin. It can be compared to "Motion Baker" plugin provided with Lightwave: it compares animation key for a given time before and after IK, and creates a new key if there are some differences.  That motion plugin is executed each time the current frame is modified.  You can try to use that plugin separately.

* Functioning of IK export - the exporter adds "VirtoolsIKExporter" motion plugin to all items ("VirtoolsIKExporter"). The exporter then change the lightwave current frame from "Starting Frame" to "Ending Frame" with "Sampling Rate" frame step. A lot of new keys will be created, so it is not advised to save the scene after exporting IK. Disabling IK and playing animation should render almost the same now, if not IK had not been exported properly.

* About "Dont export Frame 0" check button - when frame 0 is baked (that is, keyframes at time 0 has been modified to be as they look after IK), some samples like (BBotDrop.lws from lightwave samples) do not export properly, but other are exported properly (TindalosJump.lws from lightwave samples). So if IK has not been exported properly, clear the scene, reload it and try with this button in its opposite state.

5.2 - Notes about texture and color managment
---------------------------------------------
->default blend mode : MODULATE ALPHA

->alpha = transparency, set in diffuse

->material ambient set to color

->managment of diffuse & specular color according to used texture slot
(only 1st used of the 3 first texture slot is taken into account)
*no texture slot used
  diffuse  = color * diffuse
  emissive = color * luminosity

*color texture slot used
  diffuse  = diffuse
  emissive = luminosity
  blend mode = DECAL ALPHA

*luminosity texture slot used
  diffuse = color * diffuse
  emissive = color

*diffuse texture slot used
  diffuse = color
  emissive = color * luminosity

->specular = specular (color is not taken into account)

->texture layer opacity : diffuse = opacity * diffuse + (1-opacity) * color
note that virtools dev does not support factor*texture + (1-factor)*color when rendering

------------------------------
6 - Known Bugs/Troubleshooting
------------------------------
Please send any comments about the plugin or this document to
* mortal@virtools.com
* doc@virtools.com
Thank-you!

The following known bugs exist at the time of writing:
* Global animations may not play correctly in Virtools

The following troubleshooting advice may be useful:
* Tesselated boxes do not render correctly in Dev.
  To correct this, ensure the "Build Normals" check box is selected in the Virtools Exporter dialog box.

* Texture coordinates for cyliner bases and spherical poles are incorrectly translated.
  Incorrect Texture coordinates may be due to using cylindrical and spherical projection for Textures.  Use a Texture Map instead of these projection methods to correct the problem.

* Bone Animations play incorrectly.
  High bone falloff values (>16) may introduce errors in exported animations.  It is due to vertices very near to bones (distance<1).  For now you are advised not to use high bone falloff values.

* Virtools Dev is unable to load certain Scenes.
  This may be due to an invalid reference for the vertices of a face.  Try converting your Mesh to triangular polygons, clear the "Build Normals" check box, and export again.

* Virtools Dev is unable to load Patch Meshes.
  This may be due to too many vertices. Note that Patch Meshes are exported using the "Display Subpatch Level" value in object properties in LightWave as patch precision; try changing these values and try again. (max vertices for a mesh in Virtools Dev : 65535)

* The Exporter functions correctly in Layout but not in Modeler.
  Check you have added the plugin to Modeler (Modeler->Add Plugins command, see "Installation & Activation above).

* The Exporter no longer functions, either in Modeler and Layout.
  This may be due to LightWave may have become corrupted.  A potential (and radical solution) is to uninstall LightWave then reinstall LightWave.

------------
7 - Versions
------------

7.0 Changes Since v1.5
----------------------
*Bug Fix: export keyframed and morph animation bug when the starting frame is greater than 0.

7.1 Changes Since v1.4
----------------------
*Bug Fix: Build Normals option, when checked, was producing too much vertices.
Note :
a vertex can have different uvs : if 2 polygons share the same vertex, this vertex can have (uv1) on polygon1 and (uv2) on polygon2, with (uv1) not equal to (uv2). If a scene contains vertices of this kind, the "Build Normal" option should be checked.
*Change: Ambient is always set to black

7.2 Changes Since v1.3
----------------------
*Bug Fix: cycling animation were badly exported (animations paused for 1 frame before cycling)

7.3 Changes Since v1.2
----------------------
* Bug Fix: setting "Sampling Rate" to 1 while exporting IK or Morph animation made the exporter crash or freeze.
* Bug Fix: when using diffuse texture slot, diffuse color was set to 1,1,1 instead of material color

7.4 Changes Since v1.1
----------------------
* Improvement: better handling of surface colors.
* Improvement: take color or luminosity or diffuse texture slots into account (that is, only the first slot occupied by an image texture in its first layer)
* Improvement: handle "Target Item" parameter of objects, in "Motion Options" dialog
* Improvement: support scene that uses bones animation and morph animation. Note that while exporting a scene with "Export Bones" and "Export Morph" settings, if a specific object uses bones animation and morph animation at the same time, only morph animation will be taken into account for the mesh deformation in Virtools Dev.
* Bug Fix: emissive material was not exported
* Bug fix: exporting morph animations could cause LightWave to crash
* Bug fix: exporting morph and bones animations together could cause LightWave to crash.

7.5 Changes Since v1.0
----------------------
* Bug fix: bones were no longer exported for LightWave7 in the last build
* Improvement: unneeded animations are no longer exported: animations with only 1 position & rotation & scale key for frame 0

7.6 Changes Since Beta 2.0
--------------------------
* Bug fix: in multi texture layer in a surface support corrected
* Improvement: morph animation, now first and last frame of animation are taken into account
* Improvement: texture wrap mode support added for spherical and cylindrical projection