dot big bang

Developer API
Menu

Class Entity

All
  • Public
  • Public/Protected
  • All

Hierarchy

  • Entity

Index

Constructors

constructor

  • Creates a new blank Entity.

    Returns Entity

Properties

Readonly id

id: string

The 36-character identifier string of the Entity. The id is unique across all Entities of all Games.

Readonly localTransform

localTransform: Transform

The transform of the Entity (i.e. its position, rotation and scale), expressed relative to its parent. Changing the local transform of the Entity automatically updates its world transform.

name

name: string

The human readable name of the Entity.

Readonly tags

tags: StringSet

The collection of tag strings associated with the entity or describing it. Tags can be used by scripts to get entities of interest and act on them.

Readonly worldTransform

worldTransform: Transform

The transform of the Entity (i.e. its position, rotation and scale), in world space. Changing the world transform of the Entity automatically updates its local transform.

Accessors

components

  • get components(): Component[]
  • The list of all the Components in the Entity.

    Returns Component[]

game

  • Gets the Game the Entity is part of. This throws an exception if the Entity is not in the Game. Use the isInGame property to test for that.

    Returns Game

isInGame

  • get isInGame(): boolean
  • Returns true if the Entity is part of the Game.

    Returns boolean

isNetworked

  • get isNetworked(): boolean
  • Returns true if the Entity is replicated over the network on all the Peers in the Session. Returns false if the Entity only exists on the local Peer.

    Returns boolean

isOwnedLocally

  • get isOwnedLocally(): boolean
  • Returns true if the Entity is networked and if the local Peer owns (it in the dbb networking-model sense). Returns false otherwise. This is equivalent to entity.ownerPeer===this.game.session.localPeer or localPeer.ownsEntity(entity)

    Returns boolean

isSpawned

  • get isSpawned(): boolean
  • Returns true if the Entity has been created at game runtime, i.e. after the game started. Returns false if the Entity was loaded with the Game and was there when it started.

    Returns boolean

isTransformNetworked

  • get isTransformNetworked(): boolean
  • Returns true if the Entity is networked and its transform is also replicated. Returns false otherwise.

    Returns boolean

numComponents

  • get numComponents(): number
  • The number of Components in the Entity.

    Returns number

ownerPeer

  • get ownerPeer(): null | Peer
  • If the Entity is networked, returns the Peer that owns it (in the dbb networking-model sense). If the Entity isn't networked, returns null.

    Returns null | Peer

parentEntity

  • get parentEntity(): null | Entity
  • set parentEntity(parentEntity: null | Entity): any
  • The parent Entity, in the scene-graph sense, of the Entity. When this property is set, the local transform stays the same and the world transform is recalculated which may result in the Entity jumping to a different location. To visually keep the Entity at the same place, use the setParentEntity method with the preserveWorldTransform argument. If this Entity and the parent are networked, then the change is replicated over the network to all the Peers in the Session.

    Returns null | Entity

  • The parent Entity, in the scene-graph sense, of the Entity. When this property is set, the local transform stays the same and the world transform is recalculated which may result in the Entity jumping to a different location. To visually keep the Entity at the same place, use the setParentEntity method with the preserveWorldTransform argument. If this Entity and the parent are networked, then the change is replicated over the network to all the Peers in the Session.

    Parameters

    • parentEntity: null | Entity

    Returns any

Methods

addComponent

  • Adds the given Component to the Entity. If the Entity is networked, the Component is replicated over the network for all the Peers in the Session and added to their version of the same Entity there.

    Parameters

    Returns void

getBoundingBox

  • getBoundingBox(optionalTarget?: Box3): Box3
  • Gets the current bounding box of the Entity. This is either the bounding box of the first VoxelObjectComponent or SkeletalObjectComponent found on the Entity. When it comes from a VoxelObject, it is the box of the current frame in the animation. The bounding box is expressed in local Entity space. Apply the Entity worldTransform to it to get the box in world space.

    Parameters

    • Optional optionalTarget: Box3

      When not provided, the method creates an object to store the result and then returns it. Providing this argument avoids this object allocation.

    Returns Box3

getComponentById

  • getComponentById(id: string): null | Component
  • Gets the Component in the Entity with the given id, or null if there's no Component with such id. Components are assigned a unique id at creation so there can't be multiple Components with the same id.

    Parameters

    • id: string

      The id of the Component to look for.

    Returns null | Component

getComponentByIndex

  • getComponentByIndex(index: number): null | Component
  • Gets the index-th Component in the list of all the Components of the Entity (see the components property).

    Parameters

    • index: number

      The index of the requested Component.

    Returns null | Component

getComponentByType

  • getComponentByType<COMPONENT_TYPE_ENUM_MEMBER, COMPONENT_CLASS_TYPE>(componentType: COMPONENT_TYPE_ENUM_MEMBER): null | COMPONENT_CLASS_TYPE
  • Gets the first component of this Entity of the given type or null if no such component exists.

    Type parameters

    • COMPONENT_TYPE_ENUM_MEMBER: ComponentType

    • COMPONENT_CLASS_TYPE: Object | LegacyTransformComponent | LegacyScriptComponent | CollisionComponent | CameraComponent | VoxelObjectComponent | SkeletalObjectComponent | TextComponent | ParticleSystemComponent | SoundComponent | SoundcloudComponent

    Parameters

    • componentType: COMPONENT_TYPE_ENUM_MEMBER

      The type of the component to get.

    Returns null | COMPONENT_CLASS_TYPE

getComponentsByType

  • getComponentsByType<COMPONENT_TYPE_ENUM_MEMBER, COMPONENT_CLASS_TYPE>(componentType: COMPONENT_TYPE_ENUM_MEMBER): COMPONENT_CLASS_TYPE[]
  • Gets the components of this Entity of the given type.

    Type parameters

    • COMPONENT_TYPE_ENUM_MEMBER: ComponentType

    • COMPONENT_CLASS_TYPE: Object | LegacyTransformComponent | LegacyScriptComponent | CollisionComponent | CameraComponent | VoxelObjectComponent | SkeletalObjectComponent | TextComponent | ParticleSystemComponent | SoundComponent | SoundcloudComponent

    Parameters

    • componentType: COMPONENT_TYPE_ENUM_MEMBER

      The type of the components to get.

    Returns COMPONENT_CLASS_TYPE[]

getLargestBoundingBox

  • getLargestBoundingBox(optionalTarget?: Box3): Box3
  • Gets the largest bounding box of the Entity. This is either the bounding box of the first VoxelObjectComponent or SkeletalObjectComponent found on the Entity. When it comes from a VoxelObject, it is the largest box encompassing all the frames in the animation. The bounding box is expressed in local Entity space. Apply the Entity worldTransform to it to get the box in world space.

    Parameters

    • Optional optionalTarget: Box3

      When not provided, the method creates an object to store the result and then returns it. Providing this argument avoids this object allocation.

    Returns Box3

getUserScriptComponent

  • getUserScriptComponent(userScript: UserScript): any
  • Gets the first UserScriptComponent on this Entity that uses the given UserScript resource. If such component exists, it is returned as an "any" object. A disabled UserScriptComponent will not be returned by this method.

    Parameters

    • userScript: UserScript

      The UserScript resource which the component to look for uses.

    Returns any

getUserScriptComponentByName

  • getUserScriptComponentByName(userScriptName: string): any
  • Gets the first UserScriptComponent on this Entity that uses the UserScript resource with the given name. If such component exists, it is returned as an "any" object. A disabled UserScriptComponent will not be returned by this method.

    Parameters

    • userScriptName: string

    Returns any

removeComponent

  • removeComponent(component: Component): void
  • Removes the given Component from the Entity. If the Entity is networked, the removal operation happens for all Peers of the Session on their respective version of the same Entity.

    Parameters

    Returns void

sendEvent

  • sendEvent(methodName: string, ...rest: any[]): void
  • Calls the method specified by its name on all UserScriptComponents of the Entity. If a UserScriptComponent doesn't implement a method with that name, it's just skipped. The extra arguments after the method name are used as the arguments of the method to be called on each UserScriptComponent. This method throws an error if this Entity isn't part of the Game (for eg, it's freshly created from a Template but hasn't been added yet).

    Parameters

    • methodName: string

      The name of the method to try to call on each UserScriptComponent of this Entity.

    • Rest ...rest: any[]

      The arguments to pass to the method to be called on the UserScriptComponents.

    Returns void

setParentEntity

  • setParentEntity(parentEntity: null | Entity, preserveWorldTransform: boolean): void
  • Sets the parent Entity, in the scene-graph sense, of the Entity. If preserveWorldTransform is true, the Entity visually remains at the same location because its local transform is adjusted so the world transform stays the same. When it is false, it is the other way round: the world transform is adjusted so the local transform stay the same. As a result the Entity may jump to a different location. This is equivalent to setting the parentEntity property. If this Entity and the parent are networked, then the change is replicated over the network to all the Peers in the Session.

    Parameters

    • parentEntity: null | Entity
    • preserveWorldTransform: boolean

    Returns void

teleport

  • teleport(transform: Transform, local?: boolean): void
  • Teleports the entity to the specified location/transform. Teleporting is just like setting the entity transform, except that if its transform is networked and owned by this peer, then, on the other peers the movement won't be interpolated. The entity will just appear instantly at the new location for them, just like it does for the owner peer.

    Parameters

    • transform: Transform

      The transform to set the entity to (world by default, see local argument).

    • Optional local: boolean

      If true, set the localTransform of the entity with the provided one, instead of the worldTransform.

    Returns void