PhET-iO API Documentation

This document is a snapshot of the phet-io and simulation api for this given sim version.

Type Documentation

Current Instance Documentation

SimIFrameClient.launchSim()

/**
     * Launch the simulation with the specified options, see below for options documentation:
     * @param {string} URL - the URL of the simulation to launch
     * @param {Object} [options], keys and defaults specified below
     * @public
     */
    launchSim: function( URL, options ) {

      options = options || {};
      var defaults = {

        // {boolean} True if the query parameters from the wrapper should propagate through to the simulation.
        passThroughQueryParameters: true,

        // {function} called when any message is delivered from the simulation
        phetioEventsListener: null,

        // {function} called after launch is called
        callback: function() {},

        // {Object[]} an array of {phetioID,method,args} that specifies PhET-iO calls to make before the sim launches
        // These customizations will be applied as the sim starts up.
        expressions: [],

        // {Function} Callback after the sim has been fully initialized and is ready to be displayed.
        onSimInitialized: function() {},

        // {Function} Callback after the PhET-iO layer in the simulation frame is ready for communication.  It can receive some
        // PhET-iO commands (such as adding listeners or customization expressions) before the sim starts to launch.
        onPhETiOInitialized: function() {},

        // {Boolean} Whether states should be emitted in the data stream every frame.
        // Can be overriden by the phetioEmitStates query parameter
        emitStates: false,

        // {Boolean} Whether input events should be emitted in the data stream every frame.
        // Can be overriden by the phetioEmitInputEvents query parameter
        emitInputEvents: false,

        // {Object} default is an empty object. This metadata will be logged in the simStarted event on sim launch.
        simStartedMetadata: {}
      };
      // 

PhET-iO Query Parameters

{
    /**
     * For phet-io use relative path for finding the sim, instead of launching from phet-io.colorado.edu
     */
    relativeSimPath: { type: 'flag' },

    /**
     * when running a simulation using phetio.js, outputs states and deltas within the phetioEvents data stream, see phetio.js
     */
    phetioEmitDeltas: {
      type: 'boolean',
      defaultValue: false
    },

    /**
     * when emitting deltas using phetio.js (see phetioEmitDeltas) emit deltas that are empty, to simplify playback in some systems like Metacog.
     */
    phetioEmitEmptyDeltas: {
      type: 'boolean',
      defaultValue: false
    },

    /**
     * emit the Scenery input events such as pointer moves, presses, releases, dt values and window resizes
     * to support playback in a live simulation.
     */
    phetioEmitInputEvents: {
      type: 'boolean',
      defaultValue: false
    },

    /**
     * when running a simulation using phetio.js, outputs the state at the end of every frame\
     */
    phetioEmitStates: {
      type: 'boolean',
      defaultValue: false
    },

    /**
     * evaluate expressions on phet-io wrapper objects, like: ?phetioExpressions=[["beaker.beakerScreen.soluteSelector","setVisible",[true]]]
     */
    phetioExpressions: {
      type: 'string',
      defaultValue: '[]'
    },

    /**
     * Specifies where to log phetioEvents
     */
    phetioLog: {
      type: 'string',
      defaultValue: null,
      validValues: [
        null, // no logging
        'console', // stream to console in JSON format
        'lines' // stream colorized human-readable events to the console (Chrome and Firefox only)
      ]
    },

    /**
     * Causes a phet-io simulation to launch, even without a wrapper "go-ahead" step, see phet-io#181
     */
    phetioStandalone: { type: 'flag' },

    /**
     * This will throw an internal sim error instead of passing it back out of the sim. A handy
     * workaround for testing and debugging.
     */
    phetioThrowInvocationErrors: { type: 'flag' },

    /**
     * When running as phet-io assertions are normally thrown when uninstrumented objects are encountered.
     * Setting this to false will allow the simulation to proceed.  Useful for partially instrumented simulations.
     */
    phetioValidateTandems: {
      type: 'boolean',
      defaultValue: true
    },

    /**
     * This is a debug tool for instrumentation. It is designed to be used to get a large list of instances that aren't
     * yet tandemized. See https://github.com/phetsims/phet-io/issues/1047 for more details.
     */
    printMissingTandems: {
      type: 'flag'
    }
  }

PhET Query Parameters

{

    // Whether accessibility features are enabled or not.  Use this option to render the Parallel DOM for
    // keyboard navigation and screen reader based auditory descriptions.
    accessibility: { type: 'flag' },

    /**
     * Master volume control for the simulation (for Vibe sounds).
     * 1.0 is unity volume, 2.0 is double volume, etc.
     */
    audioVolume: {
      type: 'number',
      defaultValue: 1,
      isValidValue: function( value ) { return value >= 0; }
    },

    /**
     * specifies the brand that should be used in requirejs mode
     */
    brand: {
      type: 'string',
      defaultValue: 'adapted-from-phet',
      validValues: [ 'phet', 'phet-io', 'adapted-from-phet' ]
    },

    /**
     * When present, will trigger changes that are more similar to the build environment.
     * Right now, this includes computing higher-resolution mipmaps for the mipmap plugin.
     */
    buildCompatible: { type: 'flag' },

    /**
     * enables cache busting in requirejs mode.
     */
    cacheBuster: {
      type: 'boolean',
      defaultValue: true
    },

    /**
     * The color profile used at startup, relevant only for sims that support multiple color profiles.
     * Such sims are required to have a 'default' profile.  If a sim supports a 'project mode' then
     * it should also have a 'projector' profile.  Other profile names are not currently standardized.
     */
    colorProfile: {
      type: 'string',
      defaultValue: 'default'
    },

    /**
     * enables developer-only features, such as showing the layout bounds
     */
    dev: { type: 'flag' },

    /**
     * enables assertions
     */
    ea: { type: 'flag' },

    /**
     * Enables all assertions, as above but with more time-consuming checks
     */
    eall: { type: 'flag' },

    /**
     * Randomly sends mouse events to sim.
     */
    fuzzMouse: { type: 'flag' },

    /**
     * if fuzzMouse=true, this is the average number of mouse events to synthesize per frame.
     */
    fuzzRate: {
      type: 'number',
      defaultValue: 100,
      isValidValue: function( value ) { return value > 0; }
    },

    /**
     * When a simulation is run from the PhET iOS app, it should set this flag. It alters statistics that the sim sends
     * to Google Analytics and potentially other sources in the future.
     */
    'phet-app': { type: 'flag' },

    /**
     * When a simulation is run from the PhET Android app, it should set this flag. It alters statistics that the sim sends
     * to Google Analytics and potentially other sources in the future.
     */
    'phet-android-app': { type: 'flag' },

    /**
     * Launches the game-up-camera code which delivers images to requests in BrainPOP/Game Up/SnapThought
     */
    gameUp: { type: 'flag' },

    /**
     * Enables logging for game-up-camera, see gameUp
     */
    gameUpLogging: { type: 'flag' },

    /**
     * Enables support for Legends of Learning platform, including broadcasting 'init' and responding to pause/resume.
     */
    legendsOfLearning: { type: 'flag' },

    /**
     * test with a specific locale
     */
    locale: {
      type: 'string',
      defaultValue: 'en'
    },

    /**
     * plays event logging back from the server, provide an optional name for the session
     */
    playbackInputEventLog: { type: 'flag' },

    /**
     * Fires a post-message when the sim is about to change to another URL
     */
    postMessageOnBeforeUnload: { type: 'flag' },

    /**
     * passes errors to test-sims
     */
    postMessageOnError: { type: 'flag' },

    /**
     * triggers a post-message that fires when the sim finishes loading, currently used by aqua test-sims
     */
    postMessageOnLoad: { type: 'flag' },

    /**
     * shows profiling information for the sim
     */
    profiler: { type: 'flag' },

    /**
     * adds a menu item that will open a window with a QR code with the URL of the simulation
     */
    qrCode: { type: 'flag' },

    /**
     * enables input event logging, provide an optional name for the session, log is available via PhET menu
     */
    recordInputEventLog: { type: 'flag' },

    /**
     * Specify a renderer for the Sim's rootNode to use.
     */
    rootRenderer: {
      type: 'string',
      defaultValue: null,
      validValues: [ null, 'canvas', 'svg', 'dom', 'webgl' ] // see Node.setRenderer
    },

    /**
     * Array of one or more logs to enable in scenery 0.2+, delimited with commas.
     * For example: ?sceneryLog=Display,Drawable,WebGLBlock results in [ 'Display', 'Drawable', 'WebGLBlock' ]
     */
    sceneryLog: {
      type: 'array',
      elementSchema: {
        type: 'string'
      },
      defaultValue: null
    },

    /**
     * Scenery logs will be output to a string instead of the window
     */
    sceneryStringLog: { type: 'flag' },

    /**
     * Indicates the screen that will be initially selected on the home screen.
     * If showHomeScreen is false, go immediately to this screen.
     * Like query parameter 'screens', the value is 1-based; e.g. 'screenIndex=2' selects the 2nd screen.
     * Use this query parameter only with multi-screen sims.
     */
    screenIndex: {
      type: 'number',
      defaultValue: 1
    },

    /**
     * Specifies the set of screens that appear in the sim, and their order.  Uses 1-based (not zero-based) and ","
     * delimited string such as "1,3,4" to get the 1st, 3rd and 4th screen.
     */
    screens: {
      type: 'array',
      elementSchema: {
        type: 'number'
      },
      defaultValue: null
    },

    /**
     * Displays an overlay of the current bounds of each CanvasNode
     */
    showCanvasNodeBounds: { type: 'flag' },

    /**
     * Displays an overlay of the current bounds of each scenery.FittedBlock
     */
    showFittedBlockBounds: { type: 'flag' },

    /**
     * if false, go immediately to screenIndex
     */
    showHomeScreen: {
      type: 'boolean',
      defaultValue: true
    },

    /**
     * Shows pointer areas as dashed lines. touchAreas are red, mouseAreas are blue.
     */
    showPointerAreas: { type: 'flag' },

    /**
     * Displays a semi-transparent cursor indicator for the location of each active pointer on the screen.
     */
    showPointers: { type: 'flag' },

    /**
     * Shows the visible bounds in ScreenView.js, for debugging the layout outside of the "dev" bounds
     */
    showVisibleBounds: { type: 'flag' },

    /**
     * override strings, value is JSON that is identical to string.json files
     */
    strings: {
      type: 'string',
      defaultValue: null
    },

    /**
     * Sets a string used for various i18n test.  The values are:
     *
     * double: duplicates all of the translated strings which will allow to see (a) if all strings
     *   are translated and (b) whether the layout can accommodate longer strings from other languages.
     *   Note this is a heuristic rule that does not cover all cases.
     *
     * long: an exceptionally long string will be substituted for all strings. Use this to test for layout problems.
     *
     * rtl: a string that tests RTL (right-to-left) capabilities will be substituted for all strings
     *
     * xss: tests for security issues related to https://github.com/phetsims/special-ops/issues/18,
     *   and running a sim should NOT redirect to another page. Preferably should be used for built versions or
     *   other versions where assertions are not enabled.
     *
     * none|null: the normal translated string will be shown
     *
     * {string}: if any other string provided, that string will be substituted everywhere. This facilitates testing
     *   specific cases, like whether the word 'vitesse' would substitute for 'speed' well.  Also, using "/u20" it
     *   will show whitespace for all of the strings, making it easy to identify non-translated strings.
     */
    stringTest: {
      type: 'string',
      defaultValue: null
    },

    /**
     * Enables WebGL rendering. See https://github.com/phetsims/scenery/issues/289
     */
    webgl: {
      type: 'boolean',
      defaultValue: true
    }
  }