FEATURES

DOCUMENTATION

Each object in a simulation is associated with an identifier and a type. The identifier (a) appears in messages produced by the object in the data log (b) is used to configure the object and (c) is used to interact with the object dynamically. The type describes the nature of the object as well as methods for interacting with the object. For instance, a user interface component commonly found in PhET Simulations is a "reset all" button, which restores the simulation to its initial state. The identifier and type for a reset all button in a simulation may be given like this:

// The Reset All button, which appears in the bottom right of the screen
        resetAllButton: TResetAllButton

The identifier can be used to refer globally to the instance after it has been created, and the type shows what kinds of events and methods are provided by the object. In this case, the TResetAllButton provides an event to the data stream when the button is pressed.

// Names of events emitted by the button
  events: [ 'fired' ]

Here is a larger example of the identifiers and names for PhET's Faraday's Law Simulation:

phetio.api = PhETIOCommon.createAPI( {

// Simulation-specific content
  faradaysLaw: PhETIOCommon.createSim( [ 'faradaysLaw' ], {

    // Content in the screen
    faradaysLawScreen: {

      // Physical values in the model and settings
      model: {
        showSecondCoilProperty: TProperty( TBoolean ),
        showMagnetArrowsProperty: TProperty( TBoolean ),
        magnetModel: {
          positionProperty: TProperty( TVector2 ),
          flippedProperty: TProperty( TBoolean ),
          showFieldLinesProperty: TProperty( TBoolean )
        },
        voltmeterModel: {
          thetaProperty: TProperty( TNumber ) // the angle of the needle, in radians
        }
      },

      // Visible objects
      view: {
        controlPanel: {
          resetAllButton: TResetAllButton,
          flipMagnetButton: TPushButton,
          showFieldCheckBox: TCheckBox,
          singleCoilRadioButton: TRadioButton( TBoolean ),
          doubleCoilRadioButton: TRadioButton( TBoolean )
        },
        magnet: TNode.extend( {
          dragHandler: TTandemDragHandler
        } )
        }
      }
    }
  )
} )

The full identifier for an object is given by the full path to reach the object. For example, the magnet's position is

'faradaysLaw.faradaysLawScreen.magnet.position'

Note that all identifiers are prefixed by the name of the simulation and the name of the screen within the simulation to facilitate cross-simulation studies.

Query Parameters

Several query parameters govern the behavior of an instrumented PhET simulation:

• phet-io.emitStates: Outputs the full state at the end of every frame.
• phet-io.emitDeltas: Outputs state keyframes every 10 seconds and deltas every frame
• phet-io.emitEmptyDeltas: When emitting states using phetio.js, emit deltas that are empty, to simplify playback in some systems.
• phet-io.log: If set to console, will stream phetioEvents to console. This is useful for understanding or debugging the phetioEvent log output in real-time. If using Chrome or Firefox, using phet-io.log=lines provides a colorized single-line output.
• phet-io.docs: Will output type documentation to the console, see github.com/phetsims/phet-io/issues/218
• phet-io.expressions: Evaluate expressions on phetio wrapper objects, like:

  http://localhost/faradays-law/faradays-law_en.html?ea&brand=phet-io&phet-io.log=console&phet-io.expressions=[["beaker.beakerScreen.soluteSelector","setVisible",[true]]]

  Described in more detail below.

Query Parameter API for instrumented instances

Instrumented objects in a simulation can be customized through a query parameter named phet-io.expressions. Here is an example of that query parameter:

?phet-io.expressions=[["beaker.beakerScreen.soluteSelector","setVisible",[true]]]

The list of available methods and types are provided below in the types section. A complete an example of this is provided in customization.html. Please be aware that different browsers have different limits on the length of query strings. If a query string becomes too long, it will simply be truncated, leading to errors during parsing. Internet Explorer has the lowest maximum query string length at approximately 2000 characters. This limit can be reached easily if setting many state variables through the query string. An alternative to configuration with query strings is to configure the simulation after it launches using the iframe API.

Data Stream

Here is (the beginning of) a sample data log from the Color Vision simulation:

{
  "messageIndex": 0,
  "eventType": "model",
  "phetioID": "sim",
  "componentType": "TSim",
  "event": "simStarted",
  "time": 1447285103220,
  "parameters": {
    "sessionID": null,
    "simName": "‪Color Vision‬",
    "simVersion": "1.1.0-phet-io.3",
    "url": "http://www.colorado.edu/physics/phet/dev/html/phet-io/newschools/color-vision_en.html",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko)
    Chrome/46.0.2490.80 Safari/537.36",
    "provider": "PhET Interactive Simulations, University of Colorado Boulder"
  }
}
{
  "messageIndex": 1,
  "eventType": "user",
  "phetioID": "homeScreen.singleBulbScreenLargeButton",
  "componentType": "TPushButton",
  "event": "fired",
  "time": 1447285111392,
  "children": [
    {
      "messageIndex": 2,
      "eventType": "model",
      "phetioID": "sim.showHomeScreen",
      "componentType": "TProperty",
      "event": "changed",
      "time": 1447285111393,
      "parameters": {
        "oldValue": true,
        "newValue": false
      }
    }
  ]
}
{
  "messageIndex": 3,
  "eventType": "user",
  "phetioID": "colorVision.singleBulbScreen.photonRadioButton",
  "componentType": "TRadioButton",
  "event": "fired",
  "time": 1447285114104,
  "parameters": {
    "value": "photon"
  },
  "children": [
    {
      "messageIndex": 4,
      "eventType": "model",
      "phetioID": "colorVision.singleBulbScreen.beamType",
      "componentType": "TProperty",
      "event": "changed",
      "time": 1447285114104,
      "parameters": {
        "oldValue": "beam",
        "newValue": "photon"
      }
    }
  ]
}

Here is a brief description of each of the fields in a message:

The events are delivered as JSON objects, and must be parsed using a JSON parser. JSON and JavaScript do not guarantee the order of the fields, so the data stream cannot be parsed as simple text under the assumption that fields appear in a deterministic ordering.

iframe API

The iframe API can be used to communicate with a running simulation. Methods can be called on any of the simulation instances. Commands can be sent to them, or values retrieved from them. Here's a full example of how to use the sim iframe API to toggle whether a simulation is active (running) or inactive (frozen), which also demonstrates how to send commands to the simulation and receive messages back from the simulation.

var sim = WrapperUtils.getSim( 'concentration' );

// Get a reference to the iframe for the sim
var simFrame = document.getElementById( 'sim' );

// This sim does not need any listeners to be added before the sim launches, so it can be phet-io.standalone
simFrame.src = sim.URL + '&phet-io.standalone';

// Construct the sim iframe client that can be used to send messages to the sim.
var simIFrameClient = new SimIFrameClient( simFrame );

// Keep track of whether the sim is active or not
var lastActiveValue = true;

// When the user presses the "Toggle Active" button, send a command to the iframe
document.getElementById( 'toggleActiveButton' ).addEventListener( 'click', function() {

  // Send a message using the simIFrameClient to invoke a method on an instance
  simIFrameClient.invoke( sim.camelCaseName + '.sim.active', 'setValue', [ !lastActiveValue ] );
} );

// When the sim launches, wire up a listener to the active Property, so we can report its value and
// use the correct value when toggling
simIFrameClient.onSimInitialized( function() {

  // Send a message using the simIFrameClient to link up to the active Property
  simIFrameClient.invoke( sim.camelCaseName + '.sim.active', 'link', [ function( active ) {
    lastActiveValue = active;
    document.getElementById( 'readout' ).innerHTML = 'Active: ' + active;
  } ] );
} );

There are two ways to pass a function across the API, one which runs the function in the parent frame and one which runs the function in the sim frame. For instance, in the above example the args has a function wrapped in an array. This will run in the parent frame. If passing an object literal with {phetioID, method, args}, it will be invoked synchronously in the simulation frame, see the source for state.html for an example.

Startup Sequence

In order to prevent missing any events sent from the simulation to the wrapper (in the case of multi-threaded browser support for multiple frames), PhET-iO provides a startup sequence with a step where the wrapper can register any listeners with phet-io, before the simulation launches. Here is an overview of the startup sequence:

1. the wrapper starts up and initializes its state
2. the wrapper creates a listener with `window.addEventListener( 'message',...)`
3. the wrapper sets the source of the simulation iframe
4. the simulation preload files initialize (including phetio.js and related files)
5. the simulation creates a listener with `window.addEventListener( 'message',...)`
6. the simulation does postMessage indicating that it is ready for phet-io messages
7. the wrapper receives the postMessage and sends a composite command to the simulation frame, containing adding any desired listeners, setting any desired startup configuration, etc and ending with the directive to start launching the requirejs portion of the simulation. Alternatively, this could be a sequence of individual messages, but the wrapper would have to wait for the response message for each before sending the final go-ahead to launch the requirejs portion of the simulation.
8. the simulation receives the message to launch the requirejs portion and finishes launching normally.

      // Wait for the phase where we can add listeners
      simIFrameClient.onPhETiOInitialized( function() {

      // Add any desired listeners to phet-io (cannot communicate with sim instances at this
      // point since they have not been created yet
      simIFrameClient.invoke( 'phetio', 'addPhETIOEventsListener', [ function( message ) {
      textarea.innerHTML += '\n' + message;
      textarea.scrollTop = textarea.scrollHeight;
      } ], function() {

      // after that is complete, launch the simulation
      simIFrameClient.invoke( 'phetio', 'launchSimulation', [] );
      }
      );
      } );
      

Types

Each instrumented instance in a PhET-iO simulation has a type which provides a set of methods which can be called from query parameters or across the iframe api. The events field declares which event names can be emitted by the type in the phetioEvents log. The "T" prefix in front of each type indicates that it is a thin "phet-io" wrapper type instead of the actual implementation simulation type. This section provides documentation for all of the common types, and was generated by running an instrumented simulation with the query parameter ?phet-io.docs. The list of all common types is given below:

GETTING STARTED

A good place to start is by downloading one of the example wrapper files, such as EventWrapper. Save this to your hard drive by clicking "View Page Source", then copying and pasting the page source to a file. After downloading the file, the relative paths must be replaced with absolute paths:

• Replace "../../lib/SimIFrameClient.js" with "https://phet-io.colorado.edu/0.1/sims/beers-law-lab/1.4.0-dev.5/phet-io/lib/SimIFrameClient.js"
• Replace "../../lib/WrapperUtils.js" with "https://phet-io.colorado.edu/0.1/sims/beers-law-lab/1.4.0-dev.5/phet-io/lib/WrapperUtils.js"
• Replace sim.URL with "https://phet-io.colorado.edu/0.1/sims/beers-law-lab/1.4.0-dev.5/phet-io/beers-law-lab_en-phetio.html"

The links for the SimIFrameClient, WrapperUtils and simulation itself should be taken from the same version of the simulation, this will ensure they are using a compatible communication protocol.

Tips and Tricks

Reset Issues

When the user presses the Reset All button in the simulation, it may overwrite some of the customization that has been previously applied (such as making a Node visible). Two workarounds for this problem are:

• Remove the Reset All button
• Add a listener to the Reset All button