This document can be found at http://reality.sgi.com/employees/gavin/vrml/Scripts.html. It was last updated on Dec. 11, 1995.

Script nodes

Behavior files are referenced through a new Script node:

    Script { 
        behavior  ""  # MFString field
        scriptType "" # SFString field
        optimization  # SFBitMask field:
                        (UNKNOWNOUTPUTS | ALWAYSEVAL
Mitra/Sony:             | CULLEVENTS | LODEVENTS | WORLDINOUT )

        # And any number of:
        eventIn eventTypeName eventName
        field fieldTypeName fieldName initialValue
        eventOut eventTypeName eventName
    }

For example:

    Script { 
        behavior  "http://foo.com/bar.class"  ; MFSTRING
        scriptType "JAVA" ; SFSTRING
        eventIn SFString name   
        eventIn PICK selected
        eventOut SFString lookto
        field SFLong currentState 0
        optimization  ALWAYSEVAL
    }

A Script node instance may consist of:

• The behavior field specifies the URL of a script to use, e.g. "http://foo.com/mycode.java",
• The scriptType can be used to specify the Mime type of the script e.g. "application/java". If unspecified it will be inferred by the transport layer.
• The eventIn fields are used to specify field events that the script can handle, they have two uses
  1. They can be used to make the API of the script available to a visual authoring tool so that it can make connections between a field on another node, and a particular function call to the script.
  2. On some systems they will allow optimization to be done, since if this Script's object is not visible (and the ALWAYSEVAL or UNKNOWNOUTPUTS optimization flags are not set) then the source of the eventIn may not need to be evaluated.

  Note that multiple outputs can be fanned into a single eventIn. Also note the example of specifing the type as PICK, which is a hint to the authoring system that it should only attach this eventIn to a ClickSensor.

• The eventOut fields are used to specify outputs from the script, if all the outputs are known then some optimisation can be done. (See Culling rules)
• Any number of fields of any type can be declared. Fields of a Script node define the initial state of the script, are read and written from/to the VRML file, and may be read and changed by the Script (but only by the Script).
• The optimisation flags are used to help smarter browsers decide when to evaluate a script.
  • UNKNOWNOUTPUTS - says that the script may effect other parts of the scene graph than its object and its outputs. See Culling rules.
  • ALWAYSEVAL - says that no matter what any other flags say, evaluate this script whenever its inputs change.
  • Mitra/Sony: CULLEVENTS - says that the script should receive events when the browser would otherwise cull it, for example because it went out of view.
  • Mitra/Sony: LODEVENTS - says that the script should receive events when the browser would change the LOD level of its object. These will only occur when the behavior is attached to a LOD node. Issue, would it be better to allow this to be independant of visual LOD, for example with a LODSensor
  • Mitra/Sony: WORLDEVENTS - says that the script should receive events when the browser wants to load or unload the world. This can be used to save state for example.

Gavin: Defines a VisibilitySensor that takes the place of the CULL/LOD events functionality; script init/destroy calls and ProximitySensors that enclose the entire world take the place of WORLD events.

Sony/Mitra: Script nodes can only appear as children of Frames, and have an implicit object which they are attached to. They should be thought of as implementing the behavior of the real-world object.

SGI/Gavin: Script nodes can appear anywhere a node can appear in the VRML file, but Script nodes are conceptually NOT part of the scene parent/child hierarchy. Instead, Script nodes should be thought of as nodes that live "to the side" of the scene graph structure, orchestrating the flow of events from Sensors, which are part of the scene's structure and which DO have a particular place in the virtual world, or from the real world (if the Script node is a source of real-world events), into changes to the virtual world. Scripts may be combined with geometry using the prototyping mechanism to create real-world-like objects that encapsulate behavior.

Script Capabilities

A Script node is "executed" after it has received one or more events. When it executes, it may process the events received, update its internal and/or persistent state, generate output events, and make API calls to find out information about or change the virtual world.

A Script node may also run asynchronously, in which case it may spontaneously generate events.

The Script API document describes in detail the types of operations a Script node may perform.

Culling Rules

To deal with concerns about optimisation, some rules must be laid down about when a browser can, and when it cannot, optimise away, or cull, a behavior (or a node).

1. If a script has an output that is visible, it must be evaluated when it receives events.
2. If a script has the UNKNOWNOUPUTS flag set, meaning that it might effect other things in the scene graph, then it must be assumed to be connected to a visible object, so rule 1 applies.
3. If a script has the ALWAYSEVAL flag set, then it must be evaluated whenever it receives events. (this might be equivalent to UNKNOWNOUTPUTS, but I'm not sure it will be for all systems).
4. If a script would be evaluated, then any Node that it depends on will need evaluating.