Aw object change

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


int aw_object_change (void)

Description

Changes an existing object.

Callback

AW_CALLBACK_OBJECT_RESULT

Notes

This method is similar to aw_object_add except for the additional attributes AW_OBJECT_OLD_X, AW_OBJECT_OLD_Z, AW_OBJECT_NUMBER, AW_OBJECT_ID and AW_OBJECT_OWNER.

The object to be changed can be specified in two ways. This is the old method for doing it:

The values of AW_OBJECT_NUMBER, AW_OBJECT_X and AW_OBJECT_Z usually come from within the context of AW_EVENT_CELL_OBJECT or AW_EVENT_OBJECT_ADD.

There is also new method which was introduced in version 4.1:

If AW_CALLBACK_OBJECT_RESULT is installed then AW_OBJECT_NUMBER will be set during the callback to indicate which object the result is for. This can be useful in applications that issue multiple asynchronous building requests.

An object identifier AW_OBJECT_ID is assigned to an object when it is added. It is a primary key of the world's cell database and so it does not change during update/change operations. It can be particularly useful when refering to already existing objects and provides a somewhat faster access for the world server to its database.

It is possible to tell which call to a method an AW_CALLBACK_OBJECT_RESULT is for. This is done by setting AW_OBJECT_CALLBACK_REFERENCE before calling it. The attribute will be set to the specified value when the call completes (only useful within the callback).

Important: Make sure to set AW_OBJECT_TYPE, AW_OBJECT_DATA and AW_OBJECT_OWNER. It's easy to forget setting AW_OBJECT_OWNER and fail to change an object because the bot instance does not have the needed rights to change the owner (i.e. AW_WORLD_EMINENT_DOMAIN_CAPABILITY or AW_WORLD_CARETAKER_CAPABILITY).

Arguments

None

Argument attributes

AW_OBJECT_OLD_NUMBER
AW_OBJECT_OLD_X
AW_OBJECT_OLD_Z
AW_OBJECT_ID
AW_OBJECT_OWNER
Owner of the object.
AW_OBJECT_TYPE
AW_OBJECT_X
East/West position of the object (in centimeters).
AW_OBJECT_Y
Altitude of the object (in centimeters).
AW_OBJECT_Z
North/South position of the object (in centimeters).
AW_OBJECT_YAW
Rotation around the y axis of the object (in tenths of a degree).
AW_OBJECT_TILT (1)
Rotation around the x axis of the object (in tenths of a degree).
AW_OBJECT_ROLL (1)
Rotation around the z axis of the object (in tenths of a degree).
AW_OBJECT_DESCRIPTION
AW_OBJECT_ACTION
AW_OBJECT_MODEL
AW_OBJECT_DATA
Only used when AW_OBJECT_TYPE is not set to AW_OBJECT_TYPE_V3 (see AW_OBJECT_TYPES in Aw.h).
AW_OBJECT_CALLBACK_REFERENCE

(1) Only used in worlds with AW_WORLD_ALLOW_3_AXIS_ROTATION enabled. If it is not enabled then these attributes will be set to 0 for the object.

Return values

RC_SUCCESS (1) (2)
RC_NOT_INITIALIZED (1)
RC_NO_INSTANCE (1)
RC_NO_CONNECTION (1)
The connection to the world is down.
RC_OBJECT_TYPE_INVALID (1)
RC_UNAUTHORIZED (2)
Must have build right.
RC_OUT_OF_BOUNDS (2)
RC_ENCROACHES (2)
RC_CANT_FIND_OLD_ELEMENT (2)
RC_ELEMENT_ALREADY_EXISTS (2)
RC_RESTRICTED_AREA (2)
RC_RESTRICTED_OBJECT (2)
Applies to Z-objects and V4 objects.
RC_RESTRICTED_COMMAND (2)
RC_NOT_CHANGE_OWNER (2)
RC_TOO_MANY_BYTES (2)
It would exceed the cell limit (see AW_WORLD_CELL_LIMIT).
RC_UNREGISTERED_OBJECT (2)
RC_DATABASE_ERROR (2)
RC_UNABLE_TO_SET_SEQUENCE (2)
Unable to increment sequence number of the sector.

(1) Possible return values when a callback is installed.

(2) Returned by the world server.

Returned attributes

AW_OBJECT_NUMBER
AW_OBJECT_ID
AW_OBJECT_CALLBACK_REFERENCE (1)
AW_CELL_X (1)
AW_CELL_Z (1)

(1) Added in SDK build 70.

Usage

Rotate clicked objects by 15 degrees.

void handle_object_click (void)
{
  /* note, all attributes except for AW_OBJECT_OLD_* have been set to the object that was clicked */
  int rc;

  /* using AW_OBJECT_ID to identify object */
  aw_int_set (AW_OBJECT_OLD_NUMBER, 0);
  aw_int_set (AW_OBJECT_OLD_X, 0);
  aw_int_set (AW_OBJECT_OLD_Z, 0);
  
  aw_int_set (AW_OBJECT_YAW, aw_int (AW_OBJECT_YAW) + 150);
  
  rc = aw_object_change ();
  if (rc != RC_SUCCESS)
    printf ("Unable to change object (reason %d)\n", rc);
  else
    puts ("Object changed");
}

aw_event_set (AW_EVENT_OBJECT_CLICK, handle_object_click);

See also