Aw object add

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


int aw_object_add (void)

Description

Adds a new object to the world.

Callback

AW_CALLBACK_OBJECT_RESULT

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

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

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");

See also