Using 3DCrafter Scripting and the 3DCrafter Plugin Interface

Using 3DCrafter Scripting (Available with 3DCrafter Pro)

3DCrafter Pro provides scripting capabilities through the Microsoft Windows Script Host. Programmers and would-be programmers can use this feature to write small programs to do useful things in 3DCrafter such as create shapes, animate lighting, export scene information etc.

For example, a script could be written to animate the brightness of a light to create a strobe effect, or create a pulsating shape or most anything that you would want. It also can be used to write export scripts, import scripts or create new primitive shapes.

Scripts are written in VBScript, which is a variation of Visual Basic. Microsoft provides considerable information on using VBScript on the Microsoft Developer Network web site. 3DCrafter supports scripting version 4.0.

In 3DCrafter there are two types of scripts: General Purpose Scripts and Animation Scripts

General Purpose Scripts

The Scripts menu provides the ability to create, edit, delete and run scripts. To create a new script, select Create Script. A script editing window will open that allows you to type in, or paste in, a script. After you save your script you can run it by selecting Run Script. The Tools menu also provides the ability to edit and delete scripts.

3DCrafter General Purpose Scripts are saved as simple text files and are located in the Scripts folder within the 3DCrafter program folder. These General Purpose scripts can be distributed to other users of 3DCrafter Pro. You can also edit these files with any editor you wish.

A script can be very simple. The following script displays a message box that says "Hello World!":

Sub Main (Scene)

MsgBox "Hello World!"

End Sub

A general purpose 3DCrafter script must include a Sub named Main that has a single parameter. The Main Sub is run by 3DCrafter when you select Run Script from the Tools menu. 3DCrafter will provide a CSScene object as an argument to this script. This object provides functions to modify the scene, general purpose helper functions, and functions that provide information about 3DCrafter's current state. See the CSScene object documentation for more information.

Animation Scripts

3DCrafter scripts can also be used to animate Groups, Shapes, Lights and the Animation Camera.

A script can be attached to a 3DCrafter scene component by clicking on the component and selecting the Component Animation Script tab of the Properties and Information panel, and then clicking anywhere on the default script.

Following is a script for a Group that animates a Group along the Y axis:

Sub AnimateGroup (Time, CSGroup)

CSGroup.SetPosition Nothing, Time, 5, Time, 5

End Sub

A group animation script must include a Sub named AnimateGroup that has two parameters. The AnimateGroup Sub is run by 3DCrafter prior to rendering when an animation is running or being recorded. 3DCrafter provides the animation key-frame being rendered (Time) and a CSGroup object. Any changes that you make to a group's position and orientation overrides what 3DCrafter sets.

Note that the position and orientation you set will not be retained for the next time that AnimateGroup is called.

An animation script can be set for the Scene. This script can be used as the controlling script for all animations. There is no need to attach scripts to individual groups or shapes unless desired.

Following is a script for a shape that scales it over time:

Sub AnimateShape (Time, Shape)

    Dim PointCount
    Dim PointIndex
    Dim PointX
    Dim PointY
    Dim PointZ

    'get the number of points in the shape
    PointCount = Shape.GetPointCount

    'Run through the points scaling them
    For PointIndex = 0 to PointCount - 1

        'get the point
        Shape.GetPoint PointIndex, PointX, PointY, PointZ

        'scale the point
        PointX = PointX * (Time+1)
        PointY = PointY * (Time+1)
        PointZ = PointZ * (Time+1)

        'set the point
        Shape.SetPoint PointIndex, PointX, PointY, PointZ

End Sub

An shape animation script must include a Sub named AnimateShape that has two parameters. The AnimateShape Sub is run by 3DCrafter prior to rendering when in animation mode. 3DCrafter provides the animation key-frame being rendered (Time) and a CSShape object. Note that unlike the AnimateGroup sub, AnimateShape is called before each render in Animation Mode regardless of whether you are running an animation or not.

Note that the changes you make to the shape will not be retained for the next time that AnimateShape is called. 3DCrafter will reset the shape to the state it was in prior to your changes.

Following is a script for a light that makes it brighter over time.

Sub AnimateLight (Time, Light)

    'make sure that we don't set a color intensity > 1
    If Time < 10 Then
        Light.SetColor Time/10, Time/10, Time/10
    Else
        Light.SetColor 1, 1, 1
    End If

End Sub

A light animation script must include a Sub named AnimateLight that has two parameters. The AnimateLight Sub is run by 3DCrafter prior to rendering when in animation mode. 3DCrafter provides the animation key-frame being rendered (Time) and a CSLight object. Note that unlike the AnimateGroup sub, AnimateLight is called before each render in Animation Mode regardless of whether you are running an animation or not.

Note that the changes you make to the light will not be retained for the next time that AnimateLight is called. 3DCrafter will reset the light to the state it was in prior to your changes.

Following is a script for the Animation Camera that increases the Animation Camera's field of view over time:

Sub AnimateCamera (Time, Camera)

Camera.SetFieldOfView (Time+1)*.1

End Sub

A camera animation script must include a Sub named AnimateCamera that has two parameters. The AnimateCamera Sub is run by 3DCrafter prior to rendering when in animation mode. 3DCrafter provides the animation key-frame being rendered (Time) and a CSCamera object. Note that unlike the AnimateGroup sub, AnimateCamera is called before each render in Animation Mode regardless of whether you are running an animation or not.

Note that the changes you make to the light will not be retained for the next time that AnimateCamera is called. 3DCrafter will reset the camera to the state it was in prior to your changes.

Creating 3DCrafter Plug-ins (Available with 3DCrafter Pro)

Like scripting, Plug-ins provide a way that users can extend 3DCrafter's features. 3DCrafter provides a plug-in Applications Programmer's Interface (API) that exactly matches the scripting API. Several examples written in Visual Basic are provided in the Plugins\Samples folder.

Unlike scripting, Plug-ins do not provide any animation functions. They work strictly in modelling mode.

Creating 3DCrafter Operations (Available with 3DCrafter Pro)

Like scripting and plug-ins, operations provide a way that users can extend 3DCrafter's features. 3DCrafter provides an operation Applications Programmer's Interface (API) that is similar to that of the scripting and plug-in interface. The operation interface is undocumented at this time, but examples written in Visual Basic are provided in the Operations\Samples folder.

Like scripting, operations do provide animation capabilities. 3DCrafter handles all animation functions. The operation writer need only apply the operation with the parameters supplied by 3DCrafter.

Creating 3DCrafter Import/Export Plug-ins (Available with 3DCrafter Pro)

Import/Export Plug-ins provide a way that users can extend 3DCrafter's import and export capabilities. Import/Export Plug-ins use the same Application Programmer's Interface (API) as operations. Examples written in Visual Basic are provided in the PluginsImportExport\Samples folder.