PhetioClient - Documentation

Constructor

new PhetioClient(frame)

Parameters:

Name	Type	Description
`frame`	HTMLIFrameElement	an HTML element that will house the PhET-iO simulation.

Members

(static) SIM_VERSION :SimVersion

The SimVersion as an object

Type:

SimVersion

(constant) CAMEL_CASE_SIMULATION_NAME :string

the name of the simulation in lowercase camelCasing

Type:

string

(constant) PHET_IO_LIB_ABSOLUTE_PATH :string

This is the path where the lib file has been deployed. This path uses the "MAJOR.MINOR" version, excluding the maintenance number, to get automatic bugfixes.

Type:

string

(constant) SIMULATION_DISPLAY_NAME :string

the name of the simulation as a title string, e.g. "Simulation Name"

Type:

string

(constant) SIMULATION_NAME :string

the hyphenated name of the simulation, e.g. "simulation-name"

Type:

string

SIMULATION_VERSION

Deprecated:

Deprecated, please use SIMULATION_VERSION_STRING

(constant) SIMULATION_VERSION_MAJOR_MINOR_STRING :string

The Simulation version in MAJOR.MINOR form (ignoring maintenance version), or 'UNBUILT' if not built.

Type:

string

(constant) SIMULATION_VERSION_STRING :string

the full version of the simulation, in the form of "MAJOR.MINOR.MAINTENANCE"

Type:

string

(constant) VERSION :string

The version of PhetioClient.js

Type:

string

VERSION_MAJOR_MINOR

Deprecated:

Deprecated, please use SIMULATION_VERSION_MAJOR_MINOR_STRING

Methods

(async, static) createFromStandardPhetioWrapper(simFrame, standardPhetioWrapperHTML, launchSimulationOptions)

Initializes a new PhetioClient instance by launching a sim that loads the given Standard PhET-iO Wrapper data.

Parameters:

Name	Type	Description
`simFrame`	HTMLIFrameElement
`standardPhetioWrapperHTML`	string
`launchSimulationOptions`	LaunchSimulationOptions	see launchSimulation

(async, static) createFromStandardWrapper()

Deprecated:

Deprecated, please use createFromStandardPhetioWrapper().

(async, static) getAPIFile(simVersion, optionsopt) → {Promise.<Object>}

Load the phet-io API file and deliver it in the callback. See the PhET-iO API JSON in the wrapper index for more information.

Parameters:

Name	Type	Attributes	Default	Description
`simVersion`	string
`options`	Object	<optional>	`null`

Returns:

Type: Promise.<Object>

(static) getConfigFromStandardPhetioWrapper(standardPhetioWrapperHTML)

Decodes the state from a phetioConfig object.

Parameters:

Name	Type	Description
`standardPhetioWrapperHTML`	string	the configuration data generated by PhetioClient

(static) getSimulationURL(debug) → {string}

Method that gets the URL for launching the PhET-iO simulation HTML. Set the `src` of the iframe with this function's return value. Note that when using PhetioClient.launchSimulation(), that function calls this and sets the source as part of that method.

Example

const productionClientURL = phetio.PhetioClient.getSimulationURL( false );
const developmentClientURL = phetio.PhetioClient.getSimulationURL( true );

Parameters:

Name	Type	Description
`debug`	boolean	whether to load the debug version of the sim, for development purposes. When true, this loads the version of the simulation with more verbose error handling.

Returns:

Type: string

(static) getSimURL()

Deprecated:

Deprecated, please use getSimulationURL().

(static) getStateFromConfig() → {object}

Decodes the state from a phetioConfig object.

Returns:

- the simulation state object

Type: object

(static) getStateFromStandardPhetioWrapper(standardPhetioWrapperHTML) → {object}

Given the text from a standardPhetioWrapperHTML, decode and return the simulation state portion within the config.

Parameters:

Name	Type	Description
`standardPhetioWrapperHTML`	string

Returns:

- the simulation state object

Type: object

(async, static) replaceStaticClient(standardPhetioWrapperHTML)

Create a new static phetio.PhetioClient instance by loading the lib file in the htmlText. This makes it possible for one wrapper to be able to load from any Standard PhET-iO wrapper, even from a different version or different sim.

Parameters:

Name	Type	Description
`standardPhetioWrapperHTML`	string

addErrorListener(listener) → {function}

Adds a listener that is called when the sim errors, or if an invocation command from the wrapper causes an error.

Example

// Throw any errors that are returned by the sim, for debugging.
phetioClient.addErrorListener( error => throw error );

Parameters:

Name	Type	Description
`listener`	function	with a single {Error} argument.

Returns:

wrapped function that can be removed with PhetioClient.removeMessageListener()

Type: function

addPhetioInitializedListener(listener) → {function}

Adds a listener that is called when the sim frame is ready for intercommunication. This happens even before the sim is ready to launch. When this listener is called, commands can be sent to the PhetioEngineIO element in the sim to configure the sim and wire up listeners to the simulation before other phet-io elements are created and events are emitted. See the sim's PhetioEngineIO element for more information about what can be done with this listener. In this phase, only the `phetioEngine` element is interoperable. This listener will be removed once called, since "PhET-iO initialization" only happens once in the sim lifecycle. NOTE: This should not be called once PhET-iO has already been initialized, see PhetioClient.prototype.phetioStarted.

Example

phetioClient.addPhetioInitializedListener( async () => {
 await phetioClient.invokeAsync( 'phetioEngine', 'setRandomSeed', [ randomSeed ] );
 await phetioClient.invokeAsync( 'phetioEngine', 'launchSimulation' );
} );

Parameters:

Name	Type	Description
`listener`	function	called when PhET-iO is initialized in the sim frame

Returns:

wrapped function that can be removed with PhetioClient.removeMessageListener()

Type: function

addSimInitializedListener()

Deprecated:

Deprecated, please use addSimulationInitializedListener().

addSimulationInitializedListener(listener) → {function}

Adds a listener which is called when the sim has been initialized. This is when all screens have been constructed and the sim is ready to be displayed. Listeners added with this function will be able to call into the simulation and customize any phet-io elements that have been created during the startup sequence. Use this function to handle any manipulation of sim elements that is desired before the sim is displays and becomes interactive. This listener will be removed once called, since "sim initialization" only happens once in the sim lifecycle. NOTE: This should not be called once the Sim has already been initialized, see PhetioClient.prototype.simStarted.

Example

phetioClient.addSimulationInitializedListener( function() {
 phetioClient.invokeSequence( [ {
   phetioID: 'concentration.concentrationScreen.view.soluteControls',
   method: 'setVisible',
   args: [ false ]
 }, {
   phetioID: 'concentration.concentrationScreen.model.soluteProperty',
   method: 'setValue',
   args: [ 'concentration.solutes.copperSulfate' ]
 } ] );
} )

Parameters:

Name	Type	Description
`listener`	function	called when the sim is initialized

Returns:

wrapped function that can be removed with PhetioClient.removeMessageListener()

Type: function

dispose()

Release resources when the PhetioClient instance will no longer be used.

Example

// No longer using the phetioClient, so it can be disposed.
phetioClient.dispose();

getDebugModeEnabled() → {boolean}

Get if debug mode is enabled. This is the same value as using the "?phetioDebug=true" query parameter.

Returns:

Type: boolean

(async) getStandardPhetioWrapper()

Get the HTML string for the Standard PhET-iO Wrapper based on the current state of the running simulation.

invoke(phetioID, method, argsopt, callbackopt)

Primary way to send a command to the simulation frame from the wrapper frame. Given a phet-io element id, method name, and arguments, invoke the method asynchronously and return values and errors (in that order) as parameters in the callback.

Example

// Set the mass of "Planet 1" to be 123.45 (in the units defined by the model)
phetioClient.invoke( 'sim.introScreen.planet1.massProperty', 'setValue', [ 123.45 ] );

// Get the velocity vector for planet1
phetioClient.invoke( 'sim.introScreen.planet1.velocityProperty', 'getValue', [ ],
  function( velocity, error ){ ... }
);

Parameters:

Name	Type	Attributes	Description
`phetioID`	string		the id of the phet-io element
`method`	string		the name of the phet-io method
`args`	Array.<*>	<optional>	dependent on the method to invoke
`callback`	function	<optional>	invoked on completion of the invocations. Called with two parameters: 1. returnValue {*} - value the invoke call returns, undefined if nothing is returned 2. error {Error\|null} - if there was an error during the invoke, that is returned

(async) invokeAsync(phetioID, method, args)

Like invoke, but async and can be run with await. Returns the returnValue, or null if none.

Parameters:

Name	Type	Description
`phetioID`	string
`method`	string
`args`	Array.<any>

invokeSequence(sequence, callbackopt)

Method to send multiple commands synchronously, useful if the order of messages matters. The callback is called when the entire sequence is complete with return values and errors for all commands.

Example

// Example that sets several values at once, without checking the return values:
phetioClient.invokeSequence( [ {
  phetioID: 'colorVision.singleBulbScreen.model.flashlight.flashlightOnProperty',
  method: 'setValue',
  args: [ true ]
}, {
  phetioID: 'colorVision.singleBulbScreen.model.flashlight.flashlightWavelengthProperty',
  method: 'setValue',
  args: [ 532.5 ] // The middle of the green range
}, {
  phetioID: 'colorVision.singleBulbScreen.model.filter.filterVisibleProperty',
  method: 'setValue',
  args: [ true ]
}] );

// Example that invokes several commands and uses the return values:
phetioClient.invokeSequence( [
  { phetioID: 'sim.introScreen.model.durationProperty', method: 'getValue' },
  { phetioID: 'sim.introScreen.model.cart.vProperty', method: 'getValue' },
  { phetioID: 'sim.introScreen.model.leftForceProperty', method: 'getValue' },
  { phetioID: 'sim.introScreen.model.rightForceProperty', method: 'getValue' },
  { phetioID: 'sim.introScreen.model.netForceProperty', method: 'getValue' }
  ], function( duration, velocity, leftForce, rightForce, netForce,
               durationError, velocityError, leftForceError, rightForceError, netForceError ) {
    // ...
  });

Parameters:

Name	Type	Attributes	Description
`sequence`	Array.<Command>		Each "Invocation" entry in the array will be run async.
`callback`	function	<optional>	The arguments will depend on the return values of the methods invoked. The args will be first all return values followed by all errors. i.e. if there are five invocations in a sequence call, then there will be ten arguments in the callback. Further more if all are successful but the last, which returns an error, then there are still ten args, but (one indexed) args 6-9 will be null or undefined, and the tenth will be an {Error}.

invokeSequenceAsync() → {Promise.<Array.<any>>}

Like invokeSequence, but async and can be run with await.

Returns:

Type: Promise.<Array.<any>>

(async) launchSim()

Deprecated:

Deprecated, please use launchSimulation().

(async) launchSimulation(providedOptionsopt) → {Promise.<PhetioClient>}

This function is the main launch point for launching a PhET-iO simulation. At its core, it sends a message into the simulation to begin. Some options can be very helpful in customizing the simulation run before the launch command has been sent to the sim, see LaunchSimulationOptions object for more.

Example

// Start the simulation with specific customizations, specified below.
// Example from a wrapper using Hooke's Law
phetioClient.launchSimulation( {
  queryString: 'screens=3&phetioEmitStates=false',

  // Callback for messages (events) from the sim's data stream
  onEvent: function( event ) {
    // ...
  },

  // Callback when PhET-iO is ready, before the simulation has started initialization
  onPhetioInitialized: async function() {

    // add a listener called whenever a phet-io element is created in the simulation, print out that created phetioID
    await phetioClient.invokeAsync( 'phetioEngine.phetioElementAddedEmitter', 'addListener', [
      function( phetioID ) {
        console.log( phetioID + ' has been created' );
      } ] );
  },

  // Callback when the sim is initialized
  onSimInitialized: async function() {
    console.log( 'sim initialized' );

    // Invoke a method on a variable in the simulation. Open the "Studio" wrapper to see all of the variables
    // and methods available in {{SIMULATION_NAME}} {{SIMULATION_VERSION_STRING}}
    await phetioClient.invokeAsync( 'phetioEngine', 'getState', [], function( state ) {
      console.log( 'got the simulation state: ' + JSON.stringify( state, null, 2 ) );
    } );
  }
} )

Parameters:

Name	Type	Attributes	Description
`providedOptions`	LaunchSimulationOptions	<optional>	optional parameters to pass to the launch sequence

Returns:

Type: Promise.<PhetioClient>

(async) loadStandardPhetioWrapperFromHTML(standardPhetioWrapperHTML, providedOptionsopt) → {Promise.<void>}

Load the given configuration and PhET-iO state into the simulation. This requires that the PhetioClient has started up its simulation before running. If the provided Standard PhET-iO Wrapper is from a prior version, then "migration" processors will help convert it to a compatible version and note any customizations that could not be migrated..

Parameters:

Name	Type	Attributes	Description
`standardPhetioWrapperHTML`	string
`providedOptions`	Object	<optional>

Returns:

Type: Promise.<void>

removeMessageListener(messageListener)

Removes a listener that receives a callback when a message is received from the simulation frame.

Parameters:

Name	Type	Description
`messageListener`	function	wrapped listener returned from the function adding the listener

setDebugModeEnabled(debugModeEnabled)

Set if debug mode is enabled. This is the same value as using the "?phetioDebug=true" query parameter. In general it is preferable to use the query parameter instead of this method, since hard coding debug mode can be dangerous.

Parameters:

Name	Type	Description
`debugModeEnabled`	boolean	if debug-mode is enabled

(async) setStateFromConfig(config) → {Promise.<void>}

Set the state to the simulation given a configuration data.

Parameters:

Name	Type	Description
`config`	object	the configuration data generated by PhetioClient

Returns:

Type: Promise.<void>

(async) setTargetAPIVersion(targetAPIVersion) → {Promise.<void>}

Set the sim version associated with the version of the sim the wrapper was created to work with. This is used to support API migrations with newer versions of the Sim and the PhET-iO API.

Parameters:

Name	Type	Description
`targetAPIVersion`	string	the sim version considered the "old version" in terms of migration

Returns:

Type: Promise.<void>

setValues(map, callbackopt)

Convenience function for calling the "setValue" method on multiple PhET-iO Elements. Note the order of application is not guaranteed.

Example

phetioClient.setValues( {

 // Properties
 'hookesLaw.energyScreen.view.viewProperties.appliedForceVectorVisibleProperty': true,
 'hookesLaw.energyScreen.view.viewProperties.displacementVectorVisibleProperty': true,

 // Visibility control panel (top right)
 'hookesLaw.energyScreen.view.visibilityControls.separator.visibleProperty': false,

 // Radio buttons
 'hookesLaw.energyScreen.view.visibilityControls.barGraphRadioButton.visibleProperty': false,
 'hookesLaw.energyScreen.view.visibilityControls.energyPlotRadioButton.visibleProperty': false,
 'hookesLaw.energyScreen.view.visibilityControls.forcePlotRadioButton.visibleProperty': false,
} );

Parameters:

Name	Type	Attributes	Description
`map`	Object.<string, *>		the key is the phetioID, and the value is the value given to the "setValue" method
`callback`	function	<optional>	callback passed to `invokeSequence`. See that method for details