Aw object add
| Minimum requirements | ||
|---|---|---|
| Added in version 2.1 | ||
| SDK | build 13 | |
int aw_object_add (void)
Description
Adds a new object to the world.
Callback
Notes
If this method returns RC_SUCCESS then AW_OBJECT_NUMBER will contain an object number that was assigned automatically by the SDK.
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 received by the SDK when the object has been successfully created. It can be particularly useful when refering to already existing objects (see aw_object_change and aw_object_delete) and provides a somewhat faster access for the world server to it's 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).
For version 4.1 and later: Make sure to set AW_OBJECT_TYPE and AW_OBJECT_DATA.
Arguments
None
Argument attributes
- 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_RESTRICTED_AREA (2)
- RC_OUT_OF_BOUNDS (2)
- RC_ENCROACHES (2)
- RC_ELEMENT_ALREADY_EXISTS (2)
- RC_TOO_MANY_BYTES (2)
- Would exceed cell limit.
- RC_RESTRICTED_OBJECT (2)
- Applies to Z-objects and V4 objects.
- RC_RESTRICTED_COMMAND (2)
- 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
int rc; aw_int_set (AW_OBJECT_TYPE, AW_OBJECT_TYPE_V3); aw_int_set (AW_OBJECT_X, 0); aw_int_set (AW_OBJECT_Y, 0); aw_int_set (AW_OBJECT_Z, 0); aw_int_set (AW_OBJECT_YAW, 0); aw_int_set (AW_OBJECT_TILT, 0); aw_int_set (AW_OBJECT_ROLL, 0); aw_string_set (AW_OBJECT_MODEL, "street1.rwx"); aw_string_set (AW_OBJECT_DESCRIPTION, "Cornerstone"); aw_string_set (AW_OBJECT_ACTION, "create sound xyz.mid"); rc = aw_object_add (); if (rc != RC_SUCCESS) printf ("Unable to add object (reason %d)\n", rc); else puts ("Object added");