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.
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.
The type of the Component.
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.
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 true if the Component is part of an Entity.
Returns true if the Component is part of the Game (via the Entity it belongs to).
Helper shortcut for this.game.session.localPeer.
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.
When an Entity with the "DYNAMIC" collider response type gets moved by the
collision system, onCollisionCorrection gets called on that Entity.
The movement the collision system applied
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.
The other Entity we have made contact with
Details about the collision contact
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.
The other Entity we were in contact with
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.
The other Entity we are in contact with
Details about the collision contact
Called whenever the local user makes a new friend, i.e. sends a friend request
that gets accepted, or receives one that they accept.
At this point, the friend user is already fully registered an is listed
in this.localPeer.user.friends, and friend.isFriend is true.
Note that this callback is called only for friend users that are already in
this multiplaye game and not offline, playing a different game or playing solo.
the user, in the multiplayer game, that just became a friend of the local user.
Called whenever a friend of the local user stopped being one, i.e. the
local user clicked "unfriend" or the friend did on their end.
At this point, the friend user is already unregistered an is not listed
in this.localPeer.user.friends anymore, friend.isFriend is false.
Note that this callback is called only for friend users that are already in
this multiplaye game and not offline, playing a different game or playing solo.
the user that was a friend of the local user but isn't anymore.
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.
The message name, as specified by the sender
Any data included with the message, as specified by the sender
The peer which sent the message
Called whenever a new peer has just joined the multiplayer game.
At this point, the peer is already in this.game.session.peers.
The peer.user is also set up and available.
Note that you can't assume that a new peer necessarily means a new user:
the user might have already been part of the game
(i.e. listed in this.game.session.users), if they were playing the game
on different peers, i.e browser tabs or devices.
Also, the remote peer might not have spawned a player entity yet
so you can't assume it is already replicated/present in the local game yet.
Baring all this in mind, it is still possible to sendMessage to the
new peer.
The peer that just joined the game
Called whenever a peer has just left the multiplayer game.
At this point, the peer has already been removed from this.game.session.peers.
If the peer was the server one, the onServerPeerChanged callback would have
been called first.
Like with onPeerConnected, you can't assume that the user associated with
the departed peer has also left the game (i.e, isn't listed in
this.game.session.users). That's because the same user can be connected
to the game with multiple peers, i.e. browser tabs or devices.
For technical reasons, a Peer object can only exist if it's in-game,
which is why the departed peer is provided as a peerId here.
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.
An Error object with info about why the request failed.
The same number returned from SaveData.write. You can use this to associate a call of onSaveDataSyncFailed a particular write request you made.
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.
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.
The same number returned from SaveData.write. You can use this to associate a call of onSaveDataSynced a particular write request you made.
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.
Called whenever the server peer of the multiplayer game changes.
At this point, the new server peer is already in effect and you can know
about it by calling this.game.session.serverPeer.
Currently, a server change only happens when the server peers disconnects,
but in the future the system could decide to change server dynamically to improve
network performance and therefore elect a new one while the old one is still in the game.
When the server peer disconnects, the onServerPeerChanged is first called,
then the onPeerDisconnected one.
For technical reasons, a Peer object can only exist if it's in-game,
which is why the previous server is only provided as a prevServerPeerId here.
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.
The other entity which we have started overlapping with.
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.
The other entity which we have stopped overlapping with.
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.
The other entity which we are overlapping with.
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.
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.
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.
Arguments passed to the
description,numberRange,hidden, andmultilineproperty decorators can be accessed via thedecoratorMetadataproperty. ThedecoratorMetadataproperty 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
myNumberwhich you used thedescriptionandnumberRangedecorators on,this.decoratorMetadatawould contain the values passed to those decorators, like so: