Action

Overview

One core aspect of vAtoms on the BLOCKv platform includes interactivity. Users should be able to trigger any number of different behaviors on vAtoms to change their state, which can include modifying properties which determine user ownership, location and discover-ability on the map, and custom vAtom-specific attributes.

Actions are registered on templates, and are automatically available to be invoked on all vAtoms that are created from their respective template.

After creating a new template through the API, viewing the list of actions for that template will yield no results. That is because newly created templates will have no actions registered on them by default. To enable interactive behaviors for vAtoms, the publisher must register either a custom-built action, or one of the built-in actions available on the platform. To register an action, the publisher must specify all required/optional input parameters, output parameters, and the action's reactor. Reactors implement the actual code of the state change that the action call is meant to accomplish.

As was briefly mentioned above, the BLOCKv platform includes a few built-in actions along with accompanying reactor implementations in order to aid publishers in creating amazingly interactive and inter-operable vAtoms.

If a publisher would like to include these built-in behaviors on a vAtom, all that is required is to register the desired action on the vAtom's template. Please view the API reference document on Action Registration to view sample payloads for registering the built-in actions on a template.

Built-In Actions

Transfer

Allows a user who owns a specific vAtom to transfer ownership of that vAtom to another user.

Clone

Clones the vAtom and sends the copy to another user. The cloning parameters are defined in the Create Template Variation API reference document.

Drop

Drops a vAtom on the map. The user who dropped the vAtom is still considered the owner until somebody else picks it up (by calling the Pickup action).

Pickup

Picks up a vAtom that was previously dropped on the map. After calling this action, the vAtom changes ownership to whomever called the action and is no longer available on the map.

Acquire

Acquires a vAtom from a publisher. The difference between this action and the Transfer action is in who initiates the transfer of ownership.

The Transfer action must be called by the current owner of the vAtom, whereas the Acquire action can be called by any other user to effectively "take" the vAtom from the publisher (but only if the publisher signals that they would like this kind of behavior, by having the Acquire action registered).

As an example, the Acquire can be used to allow a user to take a picture of a billboard with a QR code on it containing a vAtom id, and call the Acquire action with this id as a parameter to move the vAtom into their own inventory.