The API reference of @playcanvas/editor-api 1.1.28: the classes and types for automating and extending the PlayCanvas Editor from its browser console or user scripts. The API is in beta.
The same pages as Markdown, for AI agents: llms-full.txt.
Class · extends Events · category: Other
The Asset class represents an asset in Editor.
new Asset(data?: any)
Constructor
Parameters
data (any, optional, default {}): The asset dataget history(): ObserverHistory
Gets observer history for this asset.
get observer(): AssetObserver
The observer object for this asset.
delete(): Promise<void>
Deletes this asset.
Returns Promise<void>
get(path: string): any
Gets value at path. See the Asset overview for a full list of properties.
Parameters
path (string): The pathReturns any: The value
has(path: string): boolean
Checks if path exists. See the Asset overview for a full list of properties.
Parameters
path (string): The pathReturns boolean: True if path exists
insert(path: any, value: any, index: any): boolean
Inserts value in array at path, at specified index. See the Asset overview for a full list of properties.
Parameters
path (any): The pathvalue (any): The valueindex (any): The index (if undefined the value will be inserted in the end)Returns boolean: Whether the value was inserted
instantiateTemplate(parent: Entity, options?: object): Promise<Entity>
Creates an instance of this template asset. Assumes this asset is a template asset.
Parameters
parent (Entity): The parent entityoptions (object, optional, default {})
options.extraData (object, optional): Extra data passed to the backend. Used by the Editor on specific cases.options.history (boolean, optional): Whether to record a history action.options.index (number, optional): The desired index under the parent to instantiate the template.options.select (boolean, optional): Whether to select the new entity.Returns Promise<Entity>: The new entity.
json(): Record<string, any>
Returns JSON representation of entity data
Returns Record<string, any>: - The data
latest(): Asset
Returns the latest version of the Asset from the Assets API.
Returns Asset: The asset
load(): Promise<void>
Loads asset from the server without subscribing to realtime changes.
Returns Promise<void>
loadAndSubscribe(): Promise<void>
Loads the asset's data from sharedb and subscribes to changes.
Returns Promise<void>
removeValue(path: any, value: any): boolean
Remove value from array at path. See the Asset overview for a full list of properties.
Parameters
path (any): The pathvalue (any): The valueReturns boolean: Whether the value was removed
replace(asset: Asset, options?: object): void
Replaces any references to this asset with references to the new asset specified.
Parameters
asset (Asset): The new asset.options (object, optional, default {})
options.history (boolean, optional): Whether to record a history action.set(path: string, value: any): boolean
Sets value at path. See the Asset overview for a full list of properties.
Parameters
path (string): The pathvalue (any): The valueReturns boolean: Whether the value was set
unset(path: string): boolean
Unsets value at path. See the Asset overview for a full list of properties.
Parameters
path (string): The pathReturns boolean: Whether the value was unset
static getFileUrl(id: number, filename: string): string
Gets the file URL for an asset file.
Parameters
id (number): The asset idfilename (string): The desired filenameReturns string: The file URL
Class · extends Events · category: Other
The Assets Editor API
new Assets(options?: object)
Constructor
Parameters
options (object, optional, default {})
options.autoSubscribe (boolean, optional): Whether to auto subscribe to asset changes when assets are loaded.get defaultUploadCompletedCallback(): (uploadId: number, asset: Asset) => any
set defaultUploadCompletedCallback(value: (uploadId: number, asset: Asset) => any)
Gets the default callback called when on asset upload succeeds.
get defaultUploadErrorCallback(): (uploadId: number, error: Error) => any
set defaultUploadErrorCallback(value: (uploadId: number, error: Error) => any)
Gets the default callback called when on asset upload fails.
get defaultUploadProgressCallback(): (uploadId: number, progress: number) => any
set defaultUploadProgressCallback(value: (uploadId: number, progress: number) => any)
Gets the default callback called when on asset upload progress.
get parseScriptCallback(): (asset: Asset) => any
set parseScriptCallback(value: (asset: Asset) => any)
Gets the callback which parses script assets.
add(asset: Asset): void
Adds asset to the list
Parameters
asset (Asset): The assetclear(): void
Removes all assets from the list
createAnimStateGraph(options?: object): Promise<Asset>
Creates new anim state graph asset.
Parameters
options (object, optional, default {})
options.data (object, optional): The asset data. See Asset for Animstategraph data.options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.Returns Promise<Asset>: The new asset
createBundle(options?: object): Promise<Asset>
Creates new bundle asset
Parameters
options (object, optional, default {})
options.assets (any[], optional): The assets that the bundle will containoptions.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.Returns Promise<Asset>: The new asset
createCss(options?: object): Promise<Asset>
Creates new CSS asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.text (string, optional): The CSSReturns Promise<Asset>: The new asset
createCubemap(options?: object): Promise<Asset>
Creates new cubemap asset
Parameters
options (object, optional, default {})
options.anisotropy (number, optional): Cubemap anisotropy value. Defaults to 1.options.folder (Asset, optional): The parent folder assetoptions.magFilter (number, optional): Cubemap magFilter value. Defaults to pc.FILTER_LINEAR.options.minFilter (number, optional): Cubemap minFilter value. Defaults to pc.FILTER_LINEAR_MIPMAP_LINEAR.options.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.textures (any[], optional): The textures for each cubemap face in this order:
right, left, up, down, front, backReturns Promise<Asset>: The new asset
createFolder(options: object): Promise<Asset>
Creates a new folder asset
Parameters
options (object)
options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressReturns Promise<Asset>: The new asset
createHtml(options?: object): Promise<Asset>
Creates new HTML asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.text (string, optional): The HTMLReturns Promise<Asset>: The new asset
createI18n(options?: object): Promise<Asset>
Creates new localization JSON asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.localizationData (object, optional): The localization data. If null then default data will be used.options.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.Returns Promise<Asset>: The new asset
createJson(options?: object): Promise<Asset>
Creates new JSON asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.json (object, optional): The JSONoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.spaces (number, optional): The number of spaces used for indentation. Defaults to 0
(tightly packed output).Returns Promise<Asset>: The new asset
createMaterial(options?: object): Promise<Asset>
Creates new material asset
Parameters
options (object, optional, default {})
options.data (Record<string, any>, optional): The material data. Default values will be used for missing fields. See Asset for material data.options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.Returns Promise<Asset>: The new asset
createScript(options?: object): Promise<Asset>
Creates new script asset
Parameters
options (object, optional, default {})
options.data (object, optional): The script data. See Asset for Script data.options.filename (string, optional): The filename of the script. This will also be the name of the script asset. If not defined it will be generated
from the name of the script.options.folder (Asset, optional): The parent folder assetoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.text (string, optional): The contents of the script. If none then boilerplate code will be used.Returns Promise<Asset>: The new asset
createShader(options?: object): Promise<Asset>
Creates new shader asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.text (string, optional): The GLSLReturns Promise<Asset>: The new asset
createSprite(options?: object): Promise<Asset>
Creates new sprite asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.frameKeys (any[], optional): The sprite's frame keysoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.pixelsPerUnit (number, optional): The sprite's pixels per unit value. Defaults to 100.options.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.renderMode (number, optional): The sprite's render mode. Defaults to pc.SPRITE_RENDERMODE_SIMPLE.options.textureAtlas (Asset, optional): The sprite's texture atlas assetReturns Promise<Asset>: The new asset
createTemplate(options: object): Promise<void>
Creates new template asset
Parameters
options (object)
options.entity (Entity): The entity to create the template fromoptions.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.Returns Promise<void>: The new asset
createText(options?: object): Promise<Asset>
Creates new text asset
Parameters
options (object, optional, default {})
options.folder (Asset, optional): The parent folder assetoptions.name (string, optional): The asset nameoptions.onProgress (Function, optional): Function to report progressoptions.preload (boolean, optional): Whether to preload the asset. Defaults to true.options.text (string, optional): The textReturns Promise<Asset>: The new asset
delete(assets: Asset[]): Promise<void>
Deletes specified assets
Parameters
assets (Asset[]): The assetsReturns Promise<void>
filter(fn: Function): any[]
Gets assets that satisfy function
Parameters
fn (Function): The function (takes an asset as an argument and returns boolean).Returns any[]: The assets
findOne(fn: Function): any
Finds first asset that satisfies function
Parameters
fn (Function): A function that takes an asset as an argument and returns boolean.Returns any: The asset
get(id: number): Asset
Gets asset by id
Parameters
id (number): The asset idReturns Asset: The asset
getAssetForScript(script: string): any
Gets the first script asset that contains the specified script
Parameters
script (string): The script nameReturns any: The script asset
getUnique(uniqueId: number): Asset
Gets asset by its unique id
Parameters
uniqueId (number): The unique idReturns Asset: The asset
instantiateTemplates(assets: Asset[], parent: Entity, options?: object): Promise<Entity[]>
Instantiates the specified template assets under the specified parent entity.
Parameters
assets (Asset[]): The template assets.parent (Entity): The parent entityoptions (object, optional, default {})
options.extraData (object, optional): Extra data passed to the backend. Used by the Editor on specific cases.options.history (boolean, optional): Whether to record a history action.options.index (number, optional): The desired index under the parent to instantiate the templates.options.select (boolean, optional): Whether to select the new entities.Returns Promise<Entity[]>: The new entities
list(): Asset[]
Returns array of all assets
Returns Asset[]: The assets
listByTag(...tags: any[]): any[]
Finds all assets with specified tags
Parameters
tags (any[]): The tags. If multiple tags are specified then assets that contain ANY of the specified
tags will be included. If an argument is an array of tags then assets that contain ALL of the tags in the array will be included.Returns any[]: The assets
loadAll(options?: object): Promise<void>
Loads all assets in the current project / branch. Does not subscribe to realtime changes.
Parameters
options (object, optional, default {})
options.view (string, optional): The desired view for the REST API e.g 'designer', 'shader-editor'. This might limit
the assets returned to a smaller subset depending on the view.Returns Promise<void>
loadAllAndSubscribe(options?: object): Promise<void>
Loads all assets in the current project / branch and subscribes to changes.
Parameters
options (object, optional, default {})
options.view (string, optional): The desired view for the REST API e.g 'designer', 'shader-editor'. This might limit
the assets returned to a smaller subset depending on the view.Returns Promise<void>
remove(asset: Asset): void
Removes asset from the list
Parameters
asset (Asset): The assetupload(data: AssetUploadArguments, settings?: TextureImportSettings | SceneImportSettings, onProgress?: Function): Promise<Asset>
Creates new asset
Parameters
data (AssetUploadArguments): The asset fieldssettings (TextureImportSettings | SceneImportSettings, optional, default {}): Import settingsonProgress (Function, optional, default null): Function to report progressReturns Promise<Asset>: The new asset
Class · category: Other
Provides methods to access the Assets schema
new AssetsSchema(schema: Schema)
Parameters
schema (Schema): The schema APIgetDefaultData(type: string): Record<string, any>
Gets default data for asset type
Parameters
type (string): The asset typeReturns Record<string, any>: The default data
getFieldsOfType(assetType: string, type: string): string[]
Gets a list of fields of a particular type for an asset type
Parameters
assetType (string): The type of the asset.type (string): The desired typeReturns string[]: A list of fields
Example
const materialAssetPaths = editor.schema.assets.getFieldsOfType('material', 'asset');
Class · category: Other
Provides methods to access the components schema
new ComponentSchema(schema: Schema)
Creates new instance of API
Parameters
schema (Schema): The schema APIgetDefaultData(component: string): Record<string, any>
Gets default data for a component
Parameters
component (string): The component nameReturns Record<string, any>: The default data
Example
const modelData = editor.schema.components.getDefaultData('model');
getFieldsOfType(componentName: string, type: string): string[]
Gets a list of fields of a particular type for a component
Parameters
componentName (string): The component nametype (string): The desired typeReturns string[]: A list of fields
Example
const buttonEntityFields = editor.schema.components.getFieldsOfType('button', 'entity');
list(): string[]
Gets a list of all the available components
Returns string[]: The components
Class · extends Events · category: Other
The entities editor API
new Entities()
Creates new API instance
get root(): Entity
Gets the root Entity
add(entity: Entity): void
Adds entity to list
Parameters
entity (Entity): The entityaddScript(entities: Entity[], scriptName: string, options?: object): Promise<void>
Like Entity.addScript but works on multiple entities using a single history action.
Parameters
entities (Entity[]): The entities.scriptName (string): The name of the script.options (object, optional, default {})
options.attributes (object, optional): The values of attributes. Each key is the name
of the attributes and each value is the value for that attribute. Leave undefined to
let the Editor set default values depending on the attribute types.options.history (boolean, optional): Whether to add a history action. Defaults to true.options.index (number, optional): The desired index in the entity's scripts order to add this script.Returns Promise<void>: A promise
clear(): void
Removes all entities from the list
copyToClipboard(entities: Entity[]): void
Copy specified entities to localStorage clipboard. Can be used to paste these entities later on.
Parameters
entities (Entity[]): The entitiescreate(data?: CreateEntityArguments, options?: object): Entity
Creates new entity and adds it to the hierarchy
Parameters
data (CreateEntityArguments, optional, default null): Initial data for the entityoptions (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.options.index (number, optional): The child index that this entity will have under its parent.options.select (boolean, optional): Whether to select new Entity. Defaults to false.Returns Entity: The new entity
Example
const root = editor.entities.create({
name: 'parent',
});
const child = editor.entities.create({
name: 'child',
parent: root,
});
delete(entities: Entity | Entity[], options?: object): Promise<void>
Delete specified entities
Parameters
entities (Entity | Entity[]): The entitiesoptions (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.Returns Promise<void>
Example
await editor.entities.delete([entity1, entity2]);
duplicate(entities: Entity[], options?: object): Promise<Entity[]>
Duplicates the specified entities under the same parent
Parameters
entities (Entity[]): The entitiesoptions (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.options.rename (boolean, optional): Whether to rename the duplicated entities. Defaults to false.options.select (boolean, optional): Whether to select the new entities. Defaults to false.Returns Promise<Entity[]>: The duplicated entities
Example
const duplicated = await editor.entities.duplicate(entities);
get(id: string): Entity
Gets entity by resource id
Parameters
id (string): The entity's resource idReturns Entity: The entity
Example
const entity = editor.entities.get(resourceId);
list(): any[]
Returns array of all entities
Returns any[]: The entities
Example
const entities = editor.entities.list();
console.log(entities.length);
pasteFromClipboard(parent: Entity, options?: object): Promise<Entity[]>
Paste entities copied into clipboard under the specified parent.
Parameters
parent (Entity): The parentoptions (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.Returns Promise<Entity[]>: The new entities
remove(entity: Entity, entityReferences?: object): void
Removes entity from the list
Parameters
entity (Entity): The entityentityReferences (object, optional, default null): A map of entity references to nullify
when this entity is removedremoveScript(entities: Entity[], scriptName: string, options?: object): void
Like Entity.removeScript but works on multiple entities using a single history action.
Parameters
entities (Entity[]): The entities.scriptName (string): The name of the script.options (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.reparent(data: ReparentArguments[], options?: object): void
Reparents entities under new parent.
Parameters
data (ReparentArguments[]): The reparenting dataoptions (object, optional, default {})
options.history (boolean, optional): Whether to record history. Defaults to trueoptions.preserveTransform (boolean, optional): Whether to preserve the transform of the entities. Defaults to false.Example
const child = editor.entities.create();
const parent = editor.entities.create();
editor.entities.reparent([{
entity: child,
parent: parent
}])
serverAdd(entityData: object): void
Called when an entity is added from the server
Parameters
serverRemove(entity: Entity): void
Called when an entity is removed from the server
Parameters
entity (Entity): The entitywaitToExist(entityIds: string[], timeoutMs: number, callback: (entities: Entity[]) => void): () => void
Waits for specified entity ids to be added to the scene. Once they are the callback is called with the entities as its argument.
Parameters
entityIds (string[]): The ids of the entities to wait fortimeoutMs (number): Number of ms to wait before stopping to waitcallback ((entities: Entity[]) => void): The callback to call when all entities have been added.
The signature is (Entity[]) => void.Returns () => void: Returns a cancel function which can be called to cancel calling the
callback when the entities are added.
Class · extends Events · category: Other
The Entity class represents an entity in the Editor.
new Entity(data?: any)
Creates new Entity
Parameters
data (any, optional, default {}): Optional entity dataget children(): Entity[]
The children entities. Warning: this creates a new array every time it's called.
get history(): ObserverHistory
The history object for this entity.
get observer(): EntityObserver
The observer object for this entity.
get parent(): Entity
The parent entity.
get viewportEntity(): any
The entity in the 3D viewport of the Editor.
addChild(entity: Entity): boolean
Adds entity as a child
Parameters
entity (Entity): The entityReturns boolean: Whether the child was added
addComponent(component: string, data?: {}): void
Adds a component to this Entity
Parameters
component (string): The component namedata ({}, optional, default {}): Default component data. Defaults values will be used for any missing fields.
For details on component properties see Entity.Example
editor.entities.root.addComponent('model', {
type: 'box'
});
addScript(scriptName: string, options?: object): Promise<void>
Adds a script to the script component of this entity. If a script component does not exist, this method will add the script component as well.
Parameters
scriptName (string): The name of the script.options (object, optional, default {})
options.attributes (object, optional): The values of attributes. Each key is the name
of the attributes and each value is the value for that attribute. Leave undefined to
let the Editor set default values depending on the attribute types.options.history (boolean, optional): Whether to add a history action. Defaults to true.options.index (number, optional): The desired index in the entity's scripts order to add this script.Returns Promise<void>: A promise
delete(options?: object): Promise<void>
Deletes entity (and its children)
Parameters
options (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.Returns Promise<void>: A promise
Example
editor.entities.root.findByName('door').delete();
depthFirst(fn: (entity: Entity) => void): void
Executes function for this entity and its children in depth first order.
Parameters
fn ((entity: Entity) => void): A function that takes an entity as an argumentExample
// get a list of all entities in the graph in depth first order
const entities = [];
editor.entities.root.depthFirst(entity => entities.push(entity));
duplicate(options?: object): Promise<Entity>
Duplicates entity under the same parent
Parameters
options (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.options.rename (boolean, optional): Whether to rename the duplicated entity. Defaults to false.options.select (boolean, optional): Whether to select the new entity. Defaults to false.Returns Promise<Entity>: The new entity
filter(fn: (entity: Entity) => boolean): Entity[]
Returns the entity and children that satisfy the function
Parameters
fn ((entity: Entity) => boolean): A function that takes an Entity and returns whether it should be included
in the resultReturns Entity[]: The result
Example
const doors = editor.entities.root.filter(entity => entity.get('name').startsWith('door'));
findByName(name: string): Entity
Finds first entity by name using depth-first search
Parameters
name (string): The nameReturns Entity: The entity
Example
const door = editor.entities.root.findByName('Door');
get(path: string): any
Gets value at path. See Entity for a list of properties.
Parameters
path (string): The pathReturns any: The value
Example
console.log(entity.get('position'));
has(path: string): boolean
Checks if path exists. See Entity for a list of properties.
Parameters
path (string): The pathReturns boolean: True if path exists
Example
console.log(entity.has('components.model'));
insert(path: string, value: any, index?: number): boolean
Inserts value in array at path, at specified index. See Entity for a list of properties.
Parameters
path (string): The pathvalue (any): The valueindex (number, optional): The index (if undefined the value will be inserted in the end)Returns boolean: Whether the value was inserted
Example
entity.insert('tags', 'a_tag');
insertChild(entity: Entity, index?: number): boolean
Inserts entity as a child at specified index.
Parameters
entity (Entity): The entityindex (number, optional, default undefined): The index. If undefined the child will be added in the end.Returns boolean: Whether the child was added
isDescendantOf(parent: Entity): boolean
Returns true if this entity is a descendant of the specified parent entity.
Parameters
parent (Entity): The parentReturns boolean: True if it is
json(): Record<string, any>
Returns JSON representation of entity data
Returns Record<string, any>: - The data
console.log(entity.json());
jsonHierarchy(): any
Returns a JSON representation of entity data. The children array of the entity gets recursively converted to an array of entity data instead of containing children resource ids.
Returns any: - The data
Example
const data = entity.jsonHierarchy();
console.log(data.children[0].name);
latest(): Entity
Returns the latest version of the Entity from the Entities API.
Returns Entity: The entity
listByTag(...tags: any[]): Entity[]
Finds all entities with specified tags
Parameters
tags (any[]): The tags. If multiple tags are specified then entities that contain ANY of the specified
tags will be included. If an argument is an array of tags then entities that contain ALL of the tags in the array will be included.Returns Entity[]: The entities
Example
// entities that have the following tag
const entities = editor.entities.root.listByTag('tag');
// entities that have any of the following tags
const entities = editor.entities.root.listByTag('tag', 'tag2');
// entities that have all of the following tags
const entities = editor.entities.root.listByTag(['tag', 'tag2']);
removeChild(entity: Entity): void
Removes entity from children
Parameters
entity (Entity): The entityremoveComponent(component: string): void
Removes a component from this Entity
Parameters
component (string): The component nameExample
editor.entities.root.removeComponent('model');
removeScript(scriptName: string, options?: object): void
Removes a script from the entity's script component.
Parameters
scriptName (string): The name of the script.options (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.removeValue(path: string, value: any): boolean
Remove value from array at path. See Entity for a list of properties.
Parameters
path (string): The pathvalue (any): The valueReturns boolean: Whether the value was removed
Example
entity.removeValue('tags', 'a_tag');
reparent(parent: Entity, index?: number, options?: object): void
Reparents entity under new parent
Parameters
parent (Entity): The new parentindex (number, optional, default null): The desired index. If undefined the entity will be added at the end of the parent's children.options (object, optional, default {})
options.history (boolean, optional): Whether to record a history action. Defaults to true.options.preserveTransform (boolean, optional): Whether to preserve the original transform after reparentingExample
const redHouse = editor.entities.root.findByName('red house');
const greenHouse = editor.entities.root.findByName('green house');
const door = redHouse.findByName('door');
door.reparent(greenHouse);
set(path: string, value: any): boolean
Sets value at path. See Entity for a list of properties.
Parameters
path (string): The pathvalue (any): The valueReturns boolean: Whether the value was set
Example
entity.set('position', [1, 0, 0]);
unset(path: string): boolean
Unsets value at path. See Entity for a list of properties.
Parameters
path (string): The pathReturns boolean: Whether the value was unset
Example
entity.unset('components.model');
Class · category: Other
Global variables
static accessToken: string
The user's access token
static apiUrl: string = ''
The REST API URL
static assets: Assets
The assets API
static branchId: string
The current branch id
static clipboard: Clipboard
The main clipboard
static entities: Entities
The entities API
static hasLegacyScripts: boolean
Whether this project is using legacy scripts
static history: History
The history API
static homeUrl: string = ''
The home URL
static jobs: Jobs
The jobs API
static messenger: Messenger
The messenger API
static projectId: number
The current project id
static realtime: Realtime
The realtime API
static schema: Schema
The schema API
static selection: Selection
The selection API
static settings: Settings
The settings API
static confirmFn(text: string, options?: object): Promise<boolean>
Alert function called when user confirmation is needed for an action. Defaults to the default browser popup but can be overridden to show your custom popup instead.
Parameters
text (string): The confirm dialog textoptions (object, optional, default {}): Options for the popup
options.noDismiss (boolean, optional): If true then user cannot dismiss the popup and will have to click yes or nooptions.noText (boolean, optional): Text for 'no' optionoptions.yesText (string, optional): Text for 'yes' optionReturns Promise<boolean>: True if the user confirmed, false otherwise
Class · extends Events · category: Other
The history API responsible for undo / redo.
new History()
Creates new instance of the API
get canRedo(): boolean
set canRedo(value: boolean)
Gets whether there are actions to redo.
get canUndo(): boolean
set canUndo(value: boolean)
Gets whether there are actions to undo.
get currentAction(): HistoryAction
Gets the current action
get lastAction(): HistoryAction
Gets the last action
add(action: HistoryAction): void
Adds history action
Parameters
action (HistoryAction): The actionExample
const prevSelection = editor.selection.items;
editor.history.add({
name: 'clear selection',
redo: () => { editor.selection.clear({ history: false }); },
undo: () => { editor.selection.set(prevSelection, { history: false }); },
});
addAndExecute(action: HistoryAction): void
Adds history action and execute redo
Parameters
action (HistoryAction): The actionExample
const prevSelection = editor.selection.items;
editor.history.addAndExecute({
name: 'clear selection',
redo: () => { editor.selection.clear({ history: false }); },
undo: () => { editor.selection.set(prevSelection, { history: false }); },
});
clear(): void
Clear history
Example
editor.history.clear();
redo(): void
Redo last action
Example
editor.history.redo();
undo(): void
Undo last action
Example
editor.history.undo();
Class · category: Other
Provides methods to access the render schema
new SceneSchema(schema: Schema)
Creates new instance of API
Parameters
schema (Schema): The schema APIgetDefaultPhysicsSettings(): Record<string, any>
Get the default physics scene settings for the project
Returns Record<string, any>: The default physics scene settings
Example
const scenePhysicsSettings = editor.schema.scene.getDefaultPhysicsSettings();
getDefaultRenderSettings(): Record<string, any>
Get the default render scene settings for the project
Returns Record<string, any>: The default physics scene settings
Example
const sceneRenderSettings = editor.schema.scene.getDefaultRenderSettings();
Class · extends Events · category: Other
The Scene Settings API provides access to the settings of the currently loaded scene.
new SceneSettings()
Creates new instance of the API
get history(): ObserverHistory
Gets the history object for this entity
get(path: string): any
Gets value at path. See the SceneSettings overview for a full list of properties.
Parameters
path (string): The pathReturns any: The value
Example
console.log(editor.settings.scene.get('render.fog'));
has(path: string): boolean
Checks if path exists. See the SceneSettings overview for a full list of properties.
Parameters
path (string): The pathReturns boolean: True if path exists
Example
console.log(editor.settings.scene.has('render.fog'));
json(): Record<string, any>
Returns JSON representation of scene settings data
Returns Record<string, any>: - The data
Example
console.log(editor.settings.scene.json());
set(path: string, value: any): boolean
Sets value at path. See the SceneSettings overview for a full list of properties.
Parameters
path (string): The pathvalue (any): The valueReturns boolean: Whether the value was set
Example
editor.settings.scene.set('render.fog', 'none');
Class · category: Other
Provides methods to access the Editor schema.
new Schema(schema: any)
Creates new instance of API
Parameters
schema (any)get assets(): AssetsSchema
Gets the assets schema
get components(): ComponentSchema
Gets the component schema
get scene(): SceneSchema
Gets the scene schema
get schema(): any
Gets the schema
get settings(): SettingsSchema
Gets the settings schema
getType(field: any, fixedLength?: number): string
Converts the specified schema field to a type recursively.
Parameters
field (any)fixedLength (number, optional, default 0)Returns string
Class · extends Events · category: Other
Selection API. Allows selecting Entities, Assets etc.
new Selection()
Constructor
get count(): number
Gets the number of selected items
get enabled(): boolean
set enabled(value: boolean)
Gets enabled state of the selection methods.
get history(): SelectionHistory
Gets the selection history
get item(): Entity | Asset
Gets the first selected item. Short for this.items[0].
get items(): (Entity | Asset)[]
Gets the selected items. This creates a new array every time it is called.
Example
editor.selection.items.add(editor.entities.root);
const selectedEntities = editor.selection.items;
add(item: any, options?: object): void
Add item to selection
Parameters
item (any)options (object, optional, default {})
options.history (boolean, optional)Example
// add root entity to selection
editor.selection.add(editor.entities.root);
clear(options?: object): void
Clears selection
Parameters
options (object, optional, default {})
options.history (boolean, optional)Example
editor.selection.clear();
has(item: any): boolean
Checks if item is in selection
Parameters
item (any)Returns boolean
Example
const isRootSelected = editor.selection.has(editor.entities.root);
remove(item: any, options?: object): void
Remove item from selection
Parameters
item (any)options (object, optional, default {})
options.history (boolean, optional)Example
// remove root entity from selection
editor.selection.remove(editor.entities.root);
set(items: any[], options?: object): void
Sets current selection
Parameters
items (any[])options (object, optional, default {})
options.history (boolean, optional)Example
// select root entity
editor.selection.set([editor.entities.root]);
toggle(item: any, options?: object): void
Toggle item selection
Parameters
item (any)options (object, optional, default {})
options.history (boolean, optional)Example
// toggle root entity selection
editor.selection.toggle(editor.entities.root);
Class · category: Other
Enables undo / redo of selection changes
new SelectionHistory(selection: Selection)
Constructor
Parameters
selection (Selection)get enabled(): boolean
set enabled(value: boolean)
Gets enabled state of selection undo / redo.
wrapAction(name: any, fn: () => void): void
Record history action after executing function. The history action will restore the previous selection.
Parameters
name (any)fn (() => void)Class · extends Events · category: Other
The settings for the Editor.
new Settings()
Creates new API instance
get scene(): SceneSettings
Gets the settings for the currently loaded scene.
Class · category: Other
Provides methods to access the settings schema
new SettingsSchema(schema: Schema)
Creates new instance of API
Parameters
schema (Schema): The schema APIgetDefaultProjectSettings(): Record<string, any>
Get the default settings for the project
Returns Record<string, any>: The default settings for the project
Example
const projectSettings = editor.schema.settings.getDefaultProjectSettings();
getDefaultProjectUserSettings(): Record<string, any>
Get the default settings for the user in the project
Returns Record<string, any>: The default settings for the user in the project
Example
const projectUserSettings = editor.schema.settings.getDefaultProjectUserSettings();
getDefaultUserSettings(): Record<string, any>
Get the default settings for the user
Returns Record<string, any>: The default settings for the user
Example
const userSettings = editor.schema.settings.getDefaultUserSettings();
Type alias · category: Other
Represents the data for an Animation asset.
type AnimationAssetData = undefined
Type alias · category: Other
Animation Component Properties.
type AnimationComponent = undefined
Type alias · category: Other
Anim Component Properties.
type AnimComponent = undefined
Type alias · category: Other
Represents the data for an AnimStateGraph asset.
type AnimstategraphAssetData = undefined
Type alias · category: Other
Represents the data for an Asset.
type AssetData = AnimationAssetData | AnimstategraphAssetData | BundleAssetData | CubemapAssetData | FontAssetData | MaterialAssetData | ModelAssetData | RenderAssetData | ScriptAssetData | SpriteAssetData | TextureAssetData | TextureAtlasAssetData | WasmAssetData
Type alias · category: Other
Represents an observer for an asset, extending the base Observer.
type AssetObserver = Observer & { apiAsset: Asset; history: ObserverHistory }
Type alias · category: Other
Represents an Asset.
What follows is a reference for all possible asset paths that can be passed to functions such as Asset#get and Asset#set.
type AssetProps = undefined
Type alias · category: Other
Arguments passed when uploading an asset file.
type AssetUploadArguments = undefined
Type alias · category: Other
AudioListener Component Properties.
type AudioListenerComponent = undefined
Type alias · category: Other
Represents the data for a Bundle asset.
type BundleAssetData = undefined
Type alias · category: Other
Button Component Properties.
type ButtonComponent = undefined
Type alias · category: Other
Camera Component Properties.
type CameraComponent = undefined
Type alias · category: Other
Collision Component Properties.
type CollisionComponent = undefined
Type alias · category: Other
Components of an Entity.
type Components = undefined
Type alias · category: Other
Data to create a new Entity
type CreateEntityArguments = undefined
Type alias · category: Other
Represents the data for a Cubemap asset.
type CubemapAssetData = undefined
Type alias · category: Other
Element Component Properties.
type ElementComponent = undefined
Type alias · category: Other
Represents an observer for an entity, extending the base Observer.
type EntityObserver = Observer & { apiEntity: Entity; entity: any; history: ObserverHistory; latestFn: () => Observer }
Type alias · category: Other
Represents an Entity.
What follows is a reference for all possible asset paths that can be passed to functions such as Entity#get and Entity#set.
Common Entity Properties:
type EntityProps = undefined
Type alias · category: Other
Represents the data for a Font asset.
type FontAssetData = undefined
Type alias · category: Other
LayoutChild Component Properties.
type LayoutChildComponent = undefined
Type alias · category: Other
LayoutGroup Component Properties.
type LayoutGroupComponent = undefined
Type alias · category: Other
Light Component Properties.
type LightComponent = undefined
Type alias · category: Other
Represents the data for a Material asset.
type MaterialAssetData = undefined
Type alias · category: Other
The MessagerClient interface extends the Events class and defines the methods and properties required for the Messenger client.
type MessagerClient = Events & { isConnected: boolean; authenticate: any; connect: any; projectWatch: any }
Type alias · category: Other
Represents the data for a Model asset.
type ModelAssetData = undefined
Type alias · category: Other
Model Component Properties.
type ModelComponent = undefined
Type alias · category: Other
ParticleSystem Component Properties.
type ParticleSystemComponent = undefined
Type alias · category: Other
Represents the data for a Render asset.
type RenderAssetData = undefined
Type alias · category: Other
Render Component Properties.
type RenderComponent = undefined
Type alias · category: Other
Data to reparent an entity under a new parent
type ReparentArguments = undefined
Type alias · category: Other
RigidBody Component Properties.
type RigidBodyComponent = undefined
Type alias · category: Other
Import settings used when uploading a scene (fbx etc.).
type SceneImportSettings = undefined
Type alias · category: Other
Represents an observer for the Scene Settings, extending the base Observer.
type SceneSettingsObserver = Observer & { history: ObserverHistory }
Type alias · category: Other
Represents the settings for the currently loaded scene.
type SceneSettingsProps = undefined
Type alias · category: Other
Screen Component Properties.
type ScreenComponent = undefined
Type alias · category: Other
Represents the data for a Script asset.
type ScriptAssetData = undefined
Type alias · category: Other
Script Component Properties.
type ScriptComponent = undefined
Type alias · category: Other
Scrollbar Component Properties.
type ScrollbarComponent = undefined
Type alias · category: Other
Scrollview Component Properties.
type ScrollviewComponent = undefined
Type alias · category: Other
Sound Component Properties.
type SoundComponent = undefined
Type alias · category: Other
Represents the data for a Sprite asset.
type SpriteAssetData = undefined
Type alias · category: Other
Sprite Component Properties.
type SpriteComponent = undefined
Type alias · category: Other
Represents the data for a Texture asset.
type TextureAssetData = undefined
Type alias · category: Other
Represents the data for a TextureAtlas asset.
type TextureAtlasAssetData = undefined
Type alias · category: Other
Import settings used when uploading a texture asset.
type TextureImportSettings = undefined
Type alias · category: Other
Represents the data for a Wasm asset.
type WasmAssetData = undefined
Variable · category: Other
The git revision of the Editor API library. This is a string of the git commit hash.
const revision: "PACKAGE_REVISION" = 'PACKAGE_REVISION'
Variable · category: Other
The version of the Editor API library. This is a string in semantic version format of major.minor.patch.
const version: "PACKAGE_VERSION" = 'PACKAGE_VERSION'
Class · category: Internal
Represents a custom clipboard with a specific name which stores a value in localStorage under that name
new Clipboard(name: string)
Constructor
Parameters
name (string): The name of the clipboard.get empty(): boolean
Gets whether the clipboard is empty
get value(): string | object
set value(value: string | object)
Gets the value stored in the clipboard.
Class · category: Internal
Basically a very large random number (128-bit) which means the probability of creating two that clash is vanishingly small.
static create(): string
Create an RFC4122 version 4 compliant GUID.
Returns string: A new GUID.
Class · extends Events · category: Internal
Facilitates tracking of asynchronous jobs.
finish(jobId: string): Function
Notifies that a job has finished. The specified job id is removed and the callback stored when the job was started is returned.
Parameters
jobId (string): The job idReturns Function: The function stored when the job was started
Example
const jobId = editor.jobs.start(() => console.log('job was finished'));
editor.jobs.finish(jobId)(); // prints 'job was finished'
start(fn: Function): string
Adds a new job. The specified function will be returned when the job is finished.
Parameters
fn (Function): A function to be stored for this job.Returns string: Returns a job id
Example
const jobId = editor.jobs.start(() => console.log('job was finished'));
editor.jobs.finish(jobId)(); // prints 'job was finished'
new Jobs()Class · category: Internal
Wrapper around native local storage
get(key: string): string | object
Gets a key from localStorage
Parameters
key (string): The keyReturns string | object: The value
has(key: string): boolean
Checks if key exists in local storage
Parameters
key (string): The keyReturns boolean: True or false
set(key: string, value: string | object): void
Stores a key-value to localStorage
Parameters
key (string): The keyvalue (string | object): The valueunset(key: string): void
Removes a key from localStorage
Parameters
key (string): The keyClass · extends Events · category: Internal
The Messenger API. The messenger receives messages when various things happen e.g. an asset is created etc.
new Messenger(messenger: MessagerClient)
Constructor
Parameters
messenger (MessagerClient): The instance of the Messenger client - this is
a different class which requires the Messenger client library to be downloaded.get isConnected(): boolean
Returns true if we are connected to the messenger server.
connect(url: string): void
Connects to the messenger server.
Parameters
url (string): The server URLClass · extends Events · category: Internal
Provides methods to communicate and load / save data to the realtime server
get assets(): RealtimeAssets
Gets the realtime assets API
get connection(): RealtimeConnection
Gets the realtime connection
get scenes(): RealtimeScenes
Gets the realtime scenes API
Class · extends Events · category: Internal
Represents an asset in sharedb
new RealtimeAsset(uniqueId: number, realtime: Realtime, connection: RealtimeConnection)
Constructor
Parameters
uniqueId (number): The unique asset idrealtime (Realtime): The realtime APIconnection (RealtimeConnection): The realtime connectionget data(): any
The asset data
get id(): number
The asset id - used in combination with branch id
get loaded(): boolean
Whether the asset is loaded
get uniqueId(): number
The asset's unique id
load(): void
Loads asset from sharedb and subscribes to changes.
submitOp(op: object, callback?: Function): void
Submits sharedb operation
Parameters
op (object): The operationcallback (Function, optional): The callbackunload(): void
Unloads asset from sharedb and unsubscribes from changes.
whenNothingPending(callback: Function): void
Calls the callback when there are no changes pending to be sent to the server
Parameters
callback (Function): The callbackClass · extends Events · category: Internal
Provides methods to load assets from sharedb
new RealtimeAssets(realtime: Realtime, connection: RealtimeConnection)
Constructor
Parameters
realtime (Realtime): The realtime APIconnection (RealtimeConnection): The realtime connectionget(id: number): RealtimeAsset
Gets an already loaded asset
Parameters
id (number): The asset's unique idReturns RealtimeAsset: The asset
load(id: number): RealtimeAsset
Loads an asset
Parameters
id (number): The asset's unique idReturns RealtimeAsset: The asset
unload(id: number): void
Unloads an asset
Parameters
id (number): The asset's unique idClass · extends Events · category: Internal
Handles connecting and communicating with the Realtime server.
new RealtimeConnection(realtime: Realtime)
Constructor
Parameters
realtime (Realtime): The realtime APIget authenticated(): boolean
Whether the server has authenticated the user
get connected(): boolean
Whether the user is connected to the server
get sharedb(): ShareDb
Gets the sharedb instance
connect(url: string): void
Connect to the realtime server
Parameters
url (string): The server URLdisconnect(): void
Disconnect from the server
endBulkSubscribe(): void
Stop bulk subscribing to documents
getDocument(collection: string, id: number): Doc<any>
Gets a sharedb document
Parameters
collection (string): The collection nameid (number): The document idReturns Doc<any>: The sharedb document
send(data: string): Promise<void>
Sends a string to the server
Parameters
data (string): The message dataReturns Promise<void>
sendMessage(name: string, data: object): void
Send message to server
Parameters
name (string): The message namedata (object): The message datastartBulkSubscribe(): void
Start bulk subscribing to documents
Class · extends Events · category: Internal
Represents a scene in sharedb
new RealtimeScene(uniqueId: number, realtime: Realtime, connection: RealtimeConnection)
Constructor
Parameters
uniqueId (number): The unique scene idrealtime (Realtime): The realtime APIconnection (RealtimeConnection): The realtime connectionget data(): any
The scene data
get id(): number
The scene id - used in combination with the branch id
get loaded(): boolean
Whether the scene is loaded
get uniqueId(): number
The scene's unique id
addEntity(entity: Entity): void
Add entity to scene
Parameters
entity (Entity): The entityload(): void
Loads scene from sharedb and subscribes to changes.
removeEntity(entity: Entity): void
Removes entity from scene (not from children of another entity)
Parameters
entity (Entity): The entitysubmitOp(op: object): void
Submits sharedb operation
Parameters
op (object): The operationunload(): void
Unloads scene from sharedb and unsubscribes from changes.
whenNothingPending(callback: Function): void
Calls the callback when there are no changes pending to be sent to the server
Parameters
callback (Function): The callbackClass · extends Events · category: Internal
Provides methods to load scenes from sharedb
new RealtimeScenes(realtime: Realtime, connection: RealtimeConnection)
Constructor
Parameters
realtime (Realtime): The realtime APIconnection (RealtimeConnection): The realtime connectionget current(): RealtimeScene
The current scene
load(sceneId: number): RealtimeScene
Loads a scene
Parameters
sceneId (number): The scene idReturns RealtimeScene: The scene
unload(sceneId: number): void
Unloads a scene
Parameters
sceneId (number): The scene idClass · category: Internal
Contains various utility methods
static deepCopy(data: Record<string, any>): Record<string, any>
Deep copy an object
Parameters
data (Record<string, any>): The data to copyReturns Record<string, any>: A copy of the data