Skip to content

phet-io-types

Under Construction

This documentation is auto-generated, and is a work in progress. Please see the source code at https://github.com/phetsims/tandem/blob/main/js/phet-io-types.ts for the most up-to-date information.

Overview

General TypeScript types that apply to PhET-iO features and architecture.

@author Michael Kauzmann (PhET Interactive Simulations) @author Sam Reid (PhET Interactive Simulations)

Type AbstractPhetioAPI

Abstraction for flattened or treelike PhetioAPI

import type { AbstractPhetioAPI } from 'scenerystack/tandem';

Type CompositeStateSchemaAPI

import type { CompositeStateSchemaAPI } from 'scenerystack/tandem';

Record<string, IOTypeName>

Type FlattenedAPIPhetioElements

The PhET-iO API as it is easiest to use in code. This takes PhetioAPI type (nested elements) and "expands" (flattens) each out so that the keys are phetioIDs.

import type { FlattenedAPIPhetioElements } from 'scenerystack/tandem';

Record<PhetioID, PhetioElement>

Type FullPhetioState

import type { FullPhetioState } from 'scenerystack/tandem';

Record<PhetioID, PhetioElementState | "DELETED">

Type IOTypeName

import type { IOTypeName } from 'scenerystack/tandem';

string

Type Method

import type { Method } from 'scenerystack/tandem';
  • returnType: string
  • parameterTypes: string[]
  • documentation: string
  • invocableForReadOnlyElements?: boolean

Type Methods

import type { Methods } from 'scenerystack/tandem';

Record<string, Method>

Type PhetioAPI

The PhET-iO API json structure as it appears in the api files. This nests PhET-iO Elements like the Studio tree, in part to save space in the file.

import type { PhetioAPI } from 'scenerystack/tandem';

AbstractPhetioAPI & { phetioElements: PhetioElements }

Type PhetioAPIVersion

import type { PhetioAPIVersion } from 'scenerystack/tandem';
  • major: number
  • minor: number

Type PhetioElement

import type { PhetioElement } from 'scenerystack/tandem';

Type PhetioElementData

import type { PhetioElementData } from 'scenerystack/tandem';

Type PhetioElementMetadata

import type { PhetioElementMetadata } from 'scenerystack/tandem';
  • phetioState: boolean
    Used in PhetioObjectOptions When true, includes the PhET-iO Element in the PhET-iO state (not automatically recursive, must be specified for children explicitly)
  • phetioReadOnly: boolean
    When true, you can only get values from the PhET-iO Element; no setting allowed. This option controls how PhET-iO wrappers can interface with this PhetioObject. Predominately this occurs via public methods defined on this PhetioObject's phetioType, in which some method are not executable when this flag is true. See ObjectIO.methods for further documentation, especially regarding invocableForReadOnlyElements. NOTE: PhetioObjects with {phetioState: true} AND {phetioReadOnly: true} are restored during via setState.
  • phetioEventType: string
    The category of event that this element emits to the PhET-iO Data Stream.
  • phetioDocumentation: string
    Useful notes about a PhET-iO Element, shown in the PhET-iO Studio Wrapper. It's an html string, so "<br>" tags are required instead of "\n" characters for proper rendering in Studio. NOTE! You must escape any HTML characters that are not intended to be rendered as HTML, use _.escape().
  • phetioHighFrequency: boolean
    High frequency events such as mouse moves can be omitted from data stream, see ?phetioEmitHighFrequencyEvents and PhetioClient.launchSimulation option @deprecated - see https://github.com/phetsims/phet-io/issues/1629#issuecomment-608002410
  • phetioPlayback: boolean
    When true, emits events for data streams for playback, see handlePlaybackEvent.js @deprecated
  • phetioFeatured?: boolean
    When true, this is categorized as an important "featured" element in Studio. If this is a featured PhET-iO Element. LinkedElements have no phetioFeatured because they defer to their core element
  • phetioDynamicElement: boolean
    If this element is a "dynamic element" that can be created and destroyed throughout the lifetime of the sim (as opposed to existing forever). indicates that an object may or may not have been created. Applies recursively automatically and should only be set manually on the root dynamic element. Dynamic archetypes will have this overwritten to false even if explicitly provided as true, as archetypes cannot be dynamic.
  • phetioDesigned: boolean
    Marking phetioDesigned: true opts-in to API change detection tooling that can be used to catch inadvertent changes to a designed API. A phetioDesigned:true PhetioObject (or any of its tandem descendants) will throw assertion errors on CT (or when running with ?phetioCompareAPI) when the following are true: (a) its package.json lists compareDesignedAPIChanges:true in the "phet-io" section (b) the simulation is listed in perennial/data/phet-io-api-stable © any of its metadata values deviate from the reference API
  • phetioTypeName: IOTypeName
    Specific to Metadata The name of the PhET-iO Type
  • phetioIsArchetype: boolean
    If this element is an archetype for a dynamic element.
  • phetioArchetypePhetioID?: string | null
    If an applicable dynamic element, this is the phetioID of its archetype.
  • phetioDynamicElementName?: string | null
    Specific to PhetioDynamicElementContainer instance, see that file for doc.

Type PhetioElementMetadataValue

import type { PhetioElementMetadataValue } from 'scenerystack/tandem';

PhetioElementMetadata[keyof PhetioElementMetadata]

Type PhetioElements

In tree structure

import type { PhetioElements } from 'scenerystack/tandem';

Type PhetioElementState

The "top level" state associated with a phetioID in state. This is NOT and never should be a "substate" or nested. value within a top-level state.

import type { PhetioElementState } from 'scenerystack/tandem';

Record<string, IntentionalAny>

Type PhetioID

import type { PhetioID } from 'scenerystack/tandem';

string

Type PhetioOverrides

import type { PhetioOverrides } from 'scenerystack/tandem';

Record<string, Partial<PhetioElementMetadata>>

Type PhetioState

import type { PhetioState } from 'scenerystack/tandem';

Record<PhetioID, PhetioElementState>

Type PhetioType

The API schema, for the actual class on the sim side see IOType.ts

import type { PhetioType } from 'scenerystack/tandem';

Type PhetioTypes

import type { PhetioTypes } from 'scenerystack/tandem';

Record<IOTypeName, PhetioType>

Type StateSchemaAPI

import type { StateSchemaAPI } from 'scenerystack/tandem';

string | CompositeStateSchemaAPI

Source Code

See the source for phet-io-types.ts in the tandem repository.