Aw object change
| Minimum requirements | ||
|---|---|---|
| Added in version 2.1 | ||
| SDK | build 13 | |
int aw_object_change (void)
Description
Changes an existing object.
Callback
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:
- AW_OBJECT_OLD_X is set to x coordinate of object (in cm's).
- AW_OBJECT_OLD_Z is set to z coordinate of object (in cm's).
- AW_OBJECT_OLD_NUMBER is set to object number (which is only unique to all objects within the same cell).
- AW_OBJECT_ID is set to 0.
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:
- AW_OBJECT_OLD_X is not used.
- AW_OBJECT_OLD_Z is not used.
- AW_OBJECT_OLD_NUMBER is set to 0.
- AW_OBJECT_ID is set to the object identifier (which is unique to all objects within the world).
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
(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);