dot big bang

Developer API
Menu

Class UserScriptComponent<Generics>

All
  • Public
  • Public/Protected
  • All

Type parameters

  • Generics: { gameSaveData: SaveData<any, any> }

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Properties

Optional decoratorMetadata

decoratorMetadata: {}

Arguments passed to the description, numberRange, hidden, and multiline property decorators can be accessed via the decoratorMetadata property. The decoratorMetadata property holds an object whose keys correspond to the decorated properties on the UserScriptComponent subclass and whose values contain the arguments the decorators were called with.

For instance, if you have a property named myNumber which you used the description and numberRange decorators on, this.decoratorMetadata would contain the values passed to those decorators, like so:

{
  myNumber: {
    description: "It's a nice number",
    numberRange: [0, 10]
  }
}

Type declaration

  • [key: string]: { description?: string; hidden?: boolean; multiline?: boolean; numberRange?: [number, number] }
    • Optional description?: string
    • Optional hidden?: boolean
    • Optional multiline?: boolean
    • Optional numberRange?: [number, number]

enabled

enabled: boolean

Whether the component is enabled or not. This can be changed both programmatically and by the editor UI.

Lifecycle methods (tick, onCollisionEnter, etc) are not called on disabled components.

Readonly id

id: string

The 36-character identifier string of the Component. The id is unique within the Entity is belongs to. Currently, the same id may be used by another Component on a different Entity.

Readonly type

type: ComponentType

The type of the Component.

Accessors

entity

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

    Returns Entity

game

  • get game(): Game<{ saveData: Generics["gameSaveData"] }>

  • Gets the Game the Component is part of (via the Entity it belongs to). This throws an exception if the Component is not in the game. Use the isInGame property to test for that.

    Returns Game<{ saveData: Generics["gameSaveData"] }>

isInEntity

  • get isInEntity(): boolean

  • Returns true if the Component is part of an Entity.

    Returns boolean

isInGame

  • get isInGame(): boolean

  • Returns true if the Component is part of the Game (via the Entity it belongs to).

    Returns boolean

localPeer

  • get localPeer(): Peer

  • Helper shortcut for this.game.session.localPeer.

    Returns Peer

Methods

Optional dispose

  • dispose(): void

  • When an Entity is being removed, the dispose method is called at the end of the frame, prior to removal. dispose is also called when stopping the game in the editor.

    If you have allocated any resources in places other than this, you should put cleanup code in dispose that removes those resources.

    Returns void

Optional onCollisionCorrection

  • onCollisionCorrection(correctionVector: Vector3): void

  • When an Entity with the "DYNAMIC" collider response type gets moved by the collision system, onCollisionCorrection gets called on that Entity.

    Parameters

    • correctionVector: Vector3

      The movement the collision system applied

    Returns void

Optional onCollisionEnter

  • When the colliders of two entities first make contact, and at least one of the two entities has collider response type "STATIC" or "DYNAMIC", and the two colliders are on the same layer, onCollisionEnter gets called. onCollisionEnter gets called on both Entities involved in the contact.

    Parameters

    • otherEntity: Entity

      The other Entity we have made contact with

    • contact: CollisionContact

      Details about the collision contact

    Returns void

Optional onCollisionExit

  • onCollisionExit(otherEntity: Entity): void

  • When the colliders of two entities were in contact, and they stop being in contact, and at least one of the two entities has collider response type "STATIC" or "DYNAMIC", and the two colliders are on the same layer, onCollisionExit gets called. onCollisionExit gets called on both Entities involved in the contact.

    onCollisionExit can be called when a contact ceases due to Entity removal, in which case it will be called just prior to removal.

    Parameters

    • otherEntity: Entity

      The other Entity we were in contact with

    Returns void

Optional onCollisionStay

  • While the colliders of two entities are in contact, and at least one of the two entities has collider response type "STATIC" or "DYNAMIC", and the two colliders are on the same layer, onCollisionStay gets called once per tick. onCollisionStay gets called on both Entities involved in the contact.

    Parameters

    • otherEntity: Entity

      The other Entity we are in contact with

    • contact: CollisionContact

      Details about the collision contact

    Returns void

Optional onMessage

  • onMessage(messageType: string, messagePayload: any, sourcePeer: Peer): void

  • onMessage is called when a remote peer sends a network message to an entity.

    onMessage always gets called at the beginning of a frame (before tick), once per received message.

    Remember that an Entity must have either the 'net' or 'networked' tag in order to send and receive messages.

    Parameters

    • messageType: string

      The message name, as specified by the sender

    • messagePayload: any

      Any data included with the message, as specified by the sender

    • sourcePeer: Peer

      The peer which sent the message

    Returns void

Optional onSaveDataSyncFailed

  • onSaveDataSyncFailed(error: Error, writeId: number, saveDataInstance: SaveData<any, any> & { status: { id: "FAILED" } }): void

  • When a SaveData's write method is called, a request is made to the server to persist that data. If that request fails (for instance, due to network connectivity problems), this method will be called.

    Note that calls to SaveData.read are optimistic; that is, if you call .write with some data, calling .read will return that same data even if it hasn't been synced yet.

    To retrieve information about the data that was being saved and the last known synced data, access saveDataInstance's status property. The status will always be in the "FAILED" state when this method is called, so saveDataInstance.status.dataWeTriedToSave and saveDataInstance.status.lastKnownSyncedData are guaranteed to be available.

    Parameters

    • error: Error

      An Error object with info about why the request failed.

    • writeId: number

      The same number returned from SaveData.write. You can use this to associate a call of onSaveDataSyncFailed a particular write request you made.

    • saveDataInstance: SaveData<any, any> & { status: { id: "FAILED" } }

      The SaveData instance that .write was called on. In most cases, this will be equivalent to this.game.saveData. This SaveData is guaranteed to have a "FAILED" status.

    Returns void

Optional onSaveDataSynced

  • onSaveDataSynced(writeId: number, saveDataInstance: SaveData<any, any> & { status: { id: "HEALTHY" } }): void

  • When a SaveData's write method is called, a request is made to the server to persist that data. When that request succeeds, this method will be called.

    Note that calls to SaveData.read are optimistic; that is, if you call .write with some data, calling .read will return that same data even if it hasn't been synced yet.

    Parameters

    • writeId: number

      The same number returned from SaveData.write. You can use this to associate a call of onSaveDataSynced a particular write request you made.

    • saveDataInstance: SaveData<any, any> & { status: { id: "HEALTHY" } }

      The SaveData instance that .write was called on. In most cases, this will be equivalent to this.game.saveData. This SaveData is guaranteed to have a "HEALTHY" status.

    Returns void

Optional onTriggerEnter

  • onTriggerEnter(otherEntity: Entity): void

  • When the colliders of two entities start to physically overlap, and at least one of the two entities has collider response type "TRIGGER", and the two colliders are on the same layer, onTriggerEnter gets called. onTriggerEnter gets called on both the "trigger" entity and the "non-trigger" entity.

    Parameters

    • otherEntity: Entity

      The other entity which we have started overlapping with.

    Returns void

Optional onTriggerExit

  • onTriggerExit(otherEntity: Entity): void

  • When the colliders of two entities were physically overlapping, and they stop overlapping, and at least one of the two entities has collider response type "TRIGGER", and the two colliders are on the same layer, onTriggerExit gets called. onTriggerExit gets called on both the "trigger" entity and the "non-trigger" entity.

    onTriggerExit can be called when overlapping ceases due to Entity removal, in which case it will be called just prior to removal.

    Parameters

    • otherEntity: Entity

      The other entity which we have stopped overlapping with.

    Returns void

Optional onTriggerStay

  • onTriggerStay(otherEntity: Entity): void

  • While the colliders of two entities are physically overlapping, and at least one of the two entities has collider response type "TRIGGER", and the two colliders are on the same layer, onTriggerStay gets called once per tick. onTriggerStay gets called on both the "trigger" entity and the "non-trigger" entity.

    Parameters

    • otherEntity: Entity

      The other entity which we are overlapping with.

    Returns void

Optional postCollisionTick

  • postCollisionTick(): void

  • The postCollisionTick method gets called by the game engine once per frame, after tick and after the game engine's collision system has run for this frame.

    Subclasses of UserScriptComponent may define a postCollisionTick method in order to add custom behavior. The postCollisionTick method is not present in the UserScriptComponent base class, but will be called if defined in a subclass.

    If any of the collision-related or trigger-related methods on UserScriptComponent have been called for this frame, postCollisionTick is guaranteed to be called after those collision methods (onCollisionEnter, onCollisionExit, onTriggerEnter etc).

    Like tick, the frequency at which the postCollisionTick method is called can vary based on system CPU/GPU utilization. As such, it should not be assumed that 16.66ms have passed between every call to postCollisionTick; it could be more, or less. Notably, when the game's browser tab is inactive, postCollisionTick will be called less often, and on high-refresh-rate monitors, postCollisionTick will be called more often. In order to implement time-aware game logic in a way that behaves consistently across framerates, you should always factor in the elapsed time since the last frame, which you can obtain via this.game.frameDeltaTime.

    See also tick.

    Returns void

Optional start

  • start(): void

  • The start method is a catch-all initialization function which gets called by the game engine called whenever a component is added to an Entity, including at Entity spawn time and at the start of the game.

    Subclasses of UserScriptComponent may define start in order to add custom initialization behavior. The start method is not present in the UserScriptComponent base class, but will be called if defined in a subclass.

    It should not be assumed that any other part of the Entity has been initialized when it is called.

    NOTE: start is also called whenever a script's code is edited while the game is running.

    Returns void

Optional tick

  • tick(): void

  • The tick method gets called by the game engine once per frame.

    Subclasses of UserScriptComponent may define tick in order to add custom behavior. The tick method is not present in the UserScriptComponent base class, but will be called if defined in a subclass.

    The frequency at which the tick method is called can vary based on system CPU/GPU utilization. As such, it should not be assumed that 16.66ms have passed between every call to tick; it could be more, or less. Notably, when the game's browser tab is inactive, tick will be called less often, and on high-refresh-rate monitors, tick will be called more often. In order to implement time-aware game logic in a way that behaves consistently across framerates, you should always factor in the elapsed time since the last frame, which you can obtain via this.game.frameDeltaTime.

    Returns void