Dynamic Object

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article



The Dynamic object synchronizing framework allows you to create moving things or sync other simple data in a virtual world. A dynamic object is controlled by one client, and sends updates to other clients if they are within 25 meters of the object.

The Dynamic object framework consists of three functionalities:

  • Entity state synchronization among clients via Internet
  • Exclusive ownership of a certain entity in a virtual world (based on the ARItem facility)
  • Synchronizing entity's parent-children relationship for vehicles.


A dynamic object script runs on each client. The framework causes each client's version of the script to go to the same state as the owner (the client controlling the object). It is up to the developer to handle the owner/non-owner cases when different behavior is desired within a state.

Additional sync parameters are communicated from the owner to all non-owners via the SynchronizedParameters method, which sends data once per second (syncPeriod). These parameters are accessible via the SyncParameters table, e.g. self.ballMtl = self.SyncParameters.ballMtl; (variables are not automatically set for the non-owner).


Dynamic objects rely on a network connection, so testing should be done in the client (BlueMars>Export>Check city in BlueMars from the Editor), rather than in the Editor. If it is desired to have the dynamic object simulated in the Editor, System.IsEditor() can be used in code to create exception cases.


ARDynamicObject Methods

ARDynamicObject.Setup (dynobjclass)

Sets up the dynamic object entity to access following inherited members.

After you defined the entity table, call this method like this:

ARDynamicObject.Setup (ARElevator)

In this example, ARElevator is the entity class.

Instance Members


A table to refer the synchronized parameters.

When a client receives synchronization information from the object's owner, some members of the SyncParameters will be changed to the new value.

Inherited Methods

After you call ARDynamicObject.Setup (dynobjclass), you can call following methods on your dynamic object entities.

dynobj:GetOwner ()

Returns the owner entity or nil if not owned.

dynobj:IsOwnedByLocalAvatar ()

Returns true if owned by local avatar, otherwise false.

dynobj:AttachAvatar (avatar_ent)

Attach specified avatar entity onto the dynamic object (uses Entity/AttachChild). Then the avatar entity will be a child entity of the dynamic object entity so the avatar will move with dynamic object.

NOTE: When an avatar is being attached to other entity, the avatar can't walk on the parent entity.

Please see the example for some tips on playing an animation after calling AttachAvatar.

dynobj:DetachAvatar (avatar_ent)

Detach the specified avatar entity from the dynamic object (uses Entity/DetachThis(0)).

dynobj:UpdateState (state, params)

Updates the state or synchronized parameters of a dynamic object. You can call this function if and only if your client have a ownership of the dynamic object.

state (string): current state of the dynamic object entity

params (table): parameters (key-value pairs) to synchronize

dynobj:TakeOwnership ()

Tries to get a ownership of the dynamic object. If it success, you will be able to control the dynamic object.

dynobj:ReleaseOwnership ()

Releases the ownership.


dynobj:SynchronizedParameters ()

This method is called when the system is going to synchronize the status of the dynamic object (normally once per second). You can override this method to specify values synchronized automatically.

function ARElevator:SynchronizedParameters ()
  return {t = self.t} -- synchronize only the value of "t"

If you omit this method, no parameters will be synchronized.

dynobj:OnOwnershipReleased ()

Called when a dynamic object is released (via a call to ReleaseOwnership or upon the owner leaving). If this callback is defined in the script, it will be executed.

The callback function can be defined like this:

function ARElevator:OnOwnershipReleased ()
  self:Init ()  -- put it back to original position


The ARElevator and TicTacToe are Dynamic Object examples.

AttachAvatar example

An example from the forum illustrates the order necessary to start an animation (in this case, seated) after attaching an avatar to a moving dynamic object:

    if (self:IsOwnedByLocalAvatar()) then
      --(1) attach the driver to move with the boat
      self.driver:SetLocalPos(self.driveroffset); --move to seat
      self.driver:SetDirectionVector(self:GetDirectionVector()); --look forward
      --(2) send anim signal
      --(3) disable auto-idling
      self.driver:EnableGroundAlignment(0, false);    --disable ground alignment (for seat)
      self.driver:SetColliderMode(1);                 --disable collision
      --(4) play local animation
      local animFile = "animations/ar/human/"..self.driver:GetAvatarBaseModel().."/standard/AR_SeatedChairShiftWeight-02.dba";
      self.driver:StartAnimationAR(animFile, {blendTime=0, speed=1, loop=true});

As indicated by the distance limits, dynamic objects are not intended to move far.

Seated animation

Here's a simpler example of starting a seated animation for a stationary dynamic object:

    self.avatar.ARAvatarAnim:EnableAvatarAnimCtl(false);    --disable auto-idling 
    self.avatar:EnableGroundAlignment(0, false);    --disable ground alignment (for seat)
    self.avatar:SetColliderMode(1);                 --disable collision
    local animFile = "animations/ar/human/"..self.avatar:GetAvatarBaseModel().."/standard/AR_SeatedChairShiftWeight-02.dba";
    self.avatar:StartAnimationAR(animFile, {blendTime=0, speed=1, loop=true}); --play animation

Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools