Trace-Button Docs | Window Overview || Last | Next

 
The Trace Button in the right upper corner of the 3DPI window is responsible to give you any scriptlines, except those for one single property on command. All the scripts appear in the message window and can be copied for furthor use.

  • Trace Button functions
  • Trace Button appearance

  • Function "Dump Properties"
  • Example
  • Function "Dump Property List"
  • Example
  • Function "Trace Changes"
  •  

    Trace Button functions top

    The Trace Button offers 3 functions, that can be switched by a PopUp, which opens when clicking on the Button and keeping the mouse button pressed. These functions are:

    1. Dump Properties: getting the scripts for all properties, that are currently visible within the 3DPI, on each buttonclick.

    2. Dump Property List: getting propertyLists of all properties, that are currently visible within the 3DPI, on each buttonclick. (for advanced Lingo users)

    3. Trace Changes (default function): when changing a Property or calling a function with the help of the 3DPI, the script of this act will appear in the message window automatically.

    Trace Button appearance top

    The Trace Button appearance depends on the selected function:

    If "Dump Properties" or "Dump Property List" is selected, the Mode is set to "Button". Click on the Button and the 3DPI puts the requested scripts into the message window immediately.

    inactive
    active

    If "Trace Changes" is selected, the Mode is set to "Toggle", so a click on the Button will only switch the function to active or inactive. Scripts only appear while the Button is active and one changes a property or calls a function with the 3DPI.

    Function "Dump Properties"

    top


    If the function "Dump Properties" of the Trace Button is selected, you can get the scripts for all properties, that are currently visible within the 3DPI, by clicking shortly on the Button.

    E.g. if the Light-Tab of the 3DPI is active, and a directional light is selected, the scripts for all properties of this light appear in the message window.
    E.g. if the Model-Tab is active, but no model is already selected, there are no properties visible within the 3DPI, and so in the message window appears:
    -- "3DPI message: No Properties found to trace."


    Example for "Dump Properties" top


    The following example demonstrates how to get the scripts for all properties of the default plane ModelResource, and explains the scriptlines.

    1. Activate the ModelResource-Tab of the 3DPI.
    2. Select the first ModelResource, which is called "DefaultModel".
    3. Switch the function of the Trace Button to "Dump Properties".
    4. Click shortly on the Trace Button.
    5. Take a look at the message window:

    -- "*********** 3DPI Tracing ***********

      This line is only to help identifying, where the last "3DPI Tracing" did start, in case your message window is already full of scripts.

    theModelResource = member(1, 1).ModelResource("DefaultModel")

      A reference to the ModelResource is created, and is stored in a variable called "theModelResource".

      This scriptline is necessary to make the following lines working properly. It has to be copied together with the other lines, if one pastes them into a scriptmember.
      For playing around with the scriptlines in the message window, it is first necessary to click at the end of this line and to press the RETURN key.
       

    put theModelResource.name
    -- "DefaultModel"

      The name of the selected ModelResource is displayed in the name list on top of the 3DPI window. A name of a 3D object cannot be changed after creating the object, but of course one can ask Director for the name.

      This scriptlines are not necessary to copy into a script member , but they might help to understand which ModelResource was selected, or to improve the scripts afterwards. But if leaving this scriptlines after they have been copied into a script member, it is recommendet to inactivate the first line "put v3DPI_ModelResource.name", otherwise the message window will quickly be full of informations, when using the script frequently. To deactivate it, simply add a comment delimiter add the beginning of this line:
      -- put v3DPI_ModelResource.name
       

    put theModelResource.type
    -- #plane

      There are generally some properties of 3D objects, which cannot be changed, just like the type of a ModelResource. The 3DPI will display all non-editable properties by a dark grey field, and all referring scriptlines that appear in the message window, will start with the word "put" at the beginning.

      All this scriptlines are not necessary to copy, but they might help to understand more about the selected object. If leaving such lines within a script member, it is recommendet to deactivate all lines that start with the word "put".
       

    theModelResource.length = 1.0000
    theModelResource.width = 1.0000
    theModelResource.lengthVertices = 2
    theModelResource.widthVertices = 2

      This 4 scriptlines are corresponding to the properties of a Modelresource of type #plane, and their values are set to the current values of the selected ModelResource.
      Copy this lines if you want to reuse all these values again.

      For optimization it is recommended to cut out or deactivate all lines, which corresponding properties have not been changed and are still set to the default value. So e.g. if only the length and width of this ModelResource has been changed, the lines about lengthVertices and widthVertices are not necessary.


    Function "Dump Property List" top

    If the function "Dump Property List" of the Trace Button is selected, you can get propertyLists, which includes all properties, that are currently visible within the 3DPI, by clicking shortly on the Button.

    NOTE:
    The "Dump Property List" function of the Trace Button is designed for advanced Lingo users.
    The output of the "Dump Property List" function includes the following informations:
    1. the scriptLine to rebuild the reference to the selected Object
      e.g. theShader = member(7, 1).shader("DefaultShader")
    2. "settable properties"
      a property list of all properties, that can be rebuild with a generic handler (example see below) and the "do" function.
    3. "reference properties"
      a property list of all properties, that refer to other shockwave3D-objects, like shader.textureList or model.parent. To rebuild this properties a special handler is needed (example see below).
    4. "read only properties"
      a property list of all properties, that cannot be set.
    5. "rebuilding Help"
      a property list of informations that might help to rebuild the property values. This list can contain the following informations:
      • #object for the reference of the object (only in Sprite-Tab, Member-Tab, Havok-Tab and Renderer-Tab).
      • #member for the reference to the member of the object.
      • #objectType, which is similiar to #ilk, except that it will always provide
        #modelResource for all ModelResources.
      • #name for the object name.

    Two example handlers can rebuild all the "settable properties" and "reference properties": rebuildHandlers.txt. (The scripts are not optimized for speed, but on the other hand work generic for all outputted lists of the complete 3DPI.)


    Example for "Dump Property List" top

    The following output refers to a model, which uses a ModelResource of type #box.


    Function "Trace Changes" top


    If the function "Trace Changes" of the Trace Button is selected, a short click on the Button will switch the 3DPI-Tracing ON or OFF .

    Only if the Button is activated the 3DPI put scriptlines whenever you change a Property or call a function with the help of the 3DPI. The script of this action appears in the message window.

    This function of the Trace Button is especially useful when working with 3D-functions. In the 3DPI these functions are always presented by a Button, e.g.:

    • The "New..." Button for creating new objects (a new member, a new model, a new light, ...),
    • the "loadFile..." Button in the Member-Tab to import external w3d files into the selected member,
    • the "rotate..." Button to rotate a Node,
    • and much more...

    Last: Picking Button Next: Renderer-Tab