Target - Documentation

Target

new Target(runtime, blocksnullable)

Parameters:

Name	Type	Attributes	Description
`runtime`	Runtime		Reference to the runtime.
`blocks`	Blocks	<nullable>	Blocks instance for the blocks owned by this target.

Members

_customState :Object.<string, *>

Dictionary of custom state for this target. This can be used to store target-specific custom state for blocks which need it. TODO: do we want to persist this in SB3 files?

Type:

Object.<string, *>

_edgeActivatedHatValues :Object.<string, *>

Currently known values for edge-activated hats. Keys are block ID for the hat; values are the currently known values.

Type:

Object.<string, *>

(non-null) blocks :Blocks

Blocks run as code for this target.

Type:

Blocks

comments :Object.<string, *>

Dictionary of comments for this target. Key is the comment id.

Type:

Object.<string, *>

id :string

A unique ID for this target.

Type:

string

runtime :Runtime

Reference to the runtime.

Type:

Runtime

variables :Object.<string, *>

Dictionary of variables and their values for this target. Key is the variable id.

Type:

Object.<string, *>

Methods

clearEdgeActivatedValues()

Clear all edge-activaed hat values.

createComment(id, blockId, text, x, y, width, height, minimized)

Creates a comment with the given properties.

Parameters:

Name	Type	Description
`id`	string	Id of the comment.
`blockId`	string	Optional id of the block the comment is attached to if it is a block comment.
`text`	string	The text the comment contains.
`x`	number	The x coordinate of the comment on the workspace.
`y`	number	The y coordinate of the comment on the workspace.
`width`	number	The width of the comment when it is full size
`height`	number	The height of the comment when it is full size
`minimized`	boolean	Whether the comment is minimized.

createVariable(id, name, type, isCloud)

Creates a variable with the given id and name and adds it to the dictionary of variables.

Parameters:

Name	Type	Description
`id`	string	Id of variable
`name`	string	Name of variable.
`type`	string	Type of variable, '', 'broadcast_msg', or 'list'
`isCloud`	boolean	Whether the variable to create has the isCloud flag set. Additional checks are made that the variable can be created as a cloud variable.

deleteMonitors()

Remove this target's monitors from the runtime state and remove the target-specific monitored blocks (e.g. local variables, global variables for the stage, x-position). NOTE: This does not delete any of the stage monitors like backdrop name.

deleteVariable(id)

Removes the variable with the given id from the dictionary of variables.

Parameters:

Name	Type	Description
`id`	string	Id of variable to delete.

(abstract) dispose()

Call to destroy a target.

duplicateVariable(id, optKeepOriginalIdopt) → (nullable) {Variable}

Create a clone of the variable with the given id from the dictionary of this target's variables.

Parameters:

Name	Type	Attributes	Description
`id`	string		Id of variable to duplicate.
`optKeepOriginalId`	boolean	<optional>	Optional flag to keep the original variable ID for the duplicate variable. This is necessary when cloning a sprite, for example.

Returns:

The duplicated variable, or null if the original variable was not found.

Type: Variable

duplicateVariables(optBlocksopt) → {object}

Duplicate the dictionary of this target's variables as part of duplicating. this target or making a clone.

Parameters:

Name	Type	Attributes	Description
`optBlocks`	object	<optional>	Optional block container for the target being duplicated. If provided, new variables will be generated with new UIDs and any variable references in this blocks container will be updated to refer to the corresponding new IDs.

Returns:

The duplicated dictionary of variables

Type: object

fixUpVariableReferences()

Fixes up variable references in this target avoiding conflicts with pre-existing variables in the same scope. This is used when uploading this target as a new sprite into an existing project, where the new sprite may contain references to variable names that already exist as global variables in the project (and thus are in scope for variable references in the given sprite).

If this target has a block that references an existing global variable and that variable does not exist in this target (e.g. it was a global variable in the project the sprite was originally exported from), merge the variables. This entails fixing the variable references in this sprite to reference the id of the pre-existing global variable.

If this target has a block that references an existing global variable and that variable does exist in the target itself (e.g. it's a local variable in the sprite being uploaded), then the local variable is renamed to distinguish itself from the pre-existing variable. All blocks that reference the local variable will be updated to use the new name.

getAllVariableNamesInScopeByType(type, skipStagenullable) → {Array.<string>}

Get the names of all the variables of the given type that are in scope for this target. For targets that are not the stage, this includes any target-specific variables as well as any stage variables unless the skipStage flag is true. For the stage, this is all stage variables.

Parameters:

Name	Type	Attributes	Description
`type`	string		The variable type to search for; defaults to Variable.SCALAR_TYPE
`skipStage`	bool	<nullable>	Optional flag to skip the stage.

Returns:

A list of variable names

Type: Array.<string>

getCustomState(stateId) → {*}

Retrieve custom state associated with this target and the provided state ID.

Parameters:

Name	Type	Description
`stateId`	string	specify which piece of state to retrieve.

Returns:

the associated state, if any was found.

Type: *

(abstract) getName() → {string}

Return a human-readable name for this target. Target implementations should override this.

Returns:

Human-readable name for the target.

Type: string

lookupBroadcastByInputValue(name) → (nullable) {Variable}

Look up a broadcast message with the given name and return the variable if it exists. Does not create a new broadcast message variable if it doesn't exist.

Parameters:

Name	Type	Description
`name`	string	Name of the variable.

Returns:

Variable object.

Type: Variable

lookupBroadcastMsg(id, name) → (nullable) {Variable}

Look up a broadcast message object with the given id and return it if it exists.

Parameters:

Name	Type	Description
`id`	string	Id of the variable.
`name`	string	Name of the variable.

Returns:

Variable object.

Type: Variable

lookupOrCreateList(idnon-null, namenon-null) → (non-null) {Varible}

Look up a list object for this target, and create it if one doesn't exist. Search begins for local lists; then look for globals.

Parameters:

Name	Type	Description
`id`	string	Id of the list.
`name`	string	Name of the list.

Returns:

Variable object representing the found/created list.

Type: Varible

lookupOrCreateVariable(id, name) → (non-null) {Variable}

Look up a variable object, first by id, and then by name if the id is not found. Create a new variable if both lookups fail.

Parameters:

Name	Type	Description
`id`	string	Id of the variable.
`name`	string	Name of the variable.

Returns:

Variable object.

Type: Variable

lookupVariableById(id, name) → (non-null) {Variable}

Look up a variable object. Search begins for local variables; then look for globals.

Parameters:

Name	Type	Description
`id`	string	Id of the variable.
`name`	string	Name of the variable.

Returns:

Variable object.

Type: Variable

lookupVariableByNameAndType(name, type, skipStagenullable) → (nullable) {Variable}

Look up a variable object by its name and variable type. Search begins with local variables; then global variables if a local one was not found.

Parameters:

Name	Type	Attributes	Description
`name`	string		Name of the variable.
`type`	string		Type of the variable. Defaults to Variable.SCALAR_TYPE.
`skipStage`	bool	<nullable>	Optional flag to skip checking the stage

Returns:

Variable object if found, or null if not.

Type: Variable

mergeVariables(idToBeMerged, idToMergeWith, optReferencesToUpdatenullable, optNewNamenullable)

Merge variable references with another variable.

Parameters:

Name	Type	Attributes	Description
`idToBeMerged`	string		ID of the variable whose references need to be updated
`idToMergeWith`	string		ID of the variable that the old references should be replaced with
`optReferencesToUpdate`	Array.<Object>	<nullable>	Optional context of the change. Defaults to all the blocks in this target.
`optNewName`	string	<nullable>	New variable name to merge with. The old variable name in the references being updated should be replaced with this new name. If this parameter is not provided or is '', no name change occurs.

(abstract) onGreenFlag()

Called when the project receives a "green flag."

(abstract) postSpriteInfo(data)

Post/edit sprite info.

Parameters:

Name	Type	Description
`data`	object	An object with sprite info data to set.

renameVariable(id, newName)

Renames the variable with the given id to newName.

Parameters:

Name	Type	Description
`id`	string	Id of variable to rename.
`newName`	string	New name for the variable.

resolveVariableSharingConflictsWithTarget(blocks, receivingTarget)

Given a list of variable referencing fields, shares those variables with the target with the provided id, resolving any variable conflicts that arise using the following rules:

If this target is the stage, exit. There are no conflicts that arise from sharing variables from the stage to another sprite. The variables already exist globally, so no further action is needed.

If a variable being referenced is a global variable, do nothing. The global variable already exists so no further action is needed.

If a variable being referenced is local, and

The receiving target is a sprite: create a new local variable or merge with an existing local variable of the same name and type. Update all the referencing fields for the original variable to reference the new variable.
The receiving target is the stage: Create a new global variable with a fresh name and update all the referencing fields to reference the new variable.

Parameters:

Name	Type	Description
`blocks`	Array.<object>	The blocks containing potential conflicting references to variables.
`receivingTarget`	Target	The target receiving the variables

setCustomState(stateId, newValue)

Store custom state associated with this target and the provided state ID.

Parameters:

Name	Type	Description
`stateId`	string	specify which piece of state to store on this target.
`newValue`	*	the state value to store.

shareLocalVariableToSprite(varId, sprite, varRefs)

Share a local variable with a sprite, merging with one of the same name and type if it already exists on the sprite, or create a new one.

Parameters:

Name	Type	Description
`varId`	string	Id of the variable to share
`sprite`	Target	The sprite to share the variable with
`varRefs`	Array.<object>	A list of all the variable references currently being shared.

shareLocalVariableToStage(varId, varRefs)

Share a local variable (and given references for that variable) to the stage.

Parameters:

Name	Type	Description
`varId`	string	The ID of the variable to share.
`varRefs`	Array.<object>	The list of variable references being shared, that reference the given variable ID. The names and IDs of these variable references will be updated to refer to the new (or pre-existing) global variable.

updateEdgeActivatedValue(blockIdnon-null, newValue) → {*}

Update an edge-activated hat block value.

Parameters:

Name	Type	Description
`blockId`	string	ID of hat to store value for.
`newValue`	*	Value to store for edge-activated hat.

Returns:

The old value for the edge-activated hat.

Type: *