Template:Op positions

Positions
Positions are the 3D math of the game. If you want to handle objects in space, you will inevitably have to deal with positions. Note that while most position-handling operations work both on global map and on the scenes, there are operations which will only work in one or another mode.

Each position consists of three parts: coordinates, rotation and scale.

Coordinates are three numbers - (X,Y,Z) - which define a certain point in space relative to the base of coordinates. Most of the time, the base of coordinates is either the center of the global map, or the center of the scene, but there may be exceptions. Note that all operations with coordinates nearly always use fixed point numbers.

Position rotation determines just that - rotation around corresponding world axis. So rotation around Z axis means rotation around vertical axis, in other words - turning right and left. Rotation around X and Y axis will tilt the position forward/backwards and right/left respectively.

It is common game convention that X world axis points to the East, Y world axis points to the North and Z world axis points straight up. However this is so-called global coordinates system, and more often than not you'll be dealing with local coordinates. Local coordinates are the coordinate system defined by the object's current position. For the object, his X axis is to the right, Y axis is forward, and Z axis is up. This is simple enough, but consider what happens if that object is turned upside down in world space? Object's Z axis will point upwards *from the object's point of view*, in other words, in global space it will be pointing *downwards*. And if the object is moving, then it's local coordinates system is moving with it... you get the idea.

Imagine the position as a small point with an arrow somewhere in space. Position's coordinates are the point's position. Arrow points horizontally to the North by default, and position's rotation determines how much was it turned in the each of three directions.

Final element of position is scale. It is of no direct relevance to the position itself, and it does not participate in any calculations. However it is important when you retrieve or set positions of objects. In this case, position's scale is object's scale - so you can shrink that wall or quite the opposite, make it grow to the sky, depending on your whim.

Designate axis like this: Pitch (Y), Yaw (Z), Roll (X).

Screen position (0, 0) - is left top corner. X-axis points to the right, and Y-axis points to the bottom.

In missions there is a differet direction of axis between local coordinates and global coordinates. In local coordinates X-axis points to the right, Y-axis points forward, Z-axis points upward. But in global coordinates Y-axis points backwards. So the left-top corner of the map has x=0, y=0 coordinates.

Generally angles are counted clockwise. Except global coordinates in mission scenes. In that case Z-rot is counted counterclockwise.

Generic position operations
init_position = 701
 * (init_position, ),
 * Sets position coordinates to [0,0,0], without any rotation and default scale.
 * Not initialized position has this values: (-1000,-1000,0, 0,0,0) fpm=1 (x,y,z, x-rot,y-rot,z-rot)

copy_position = 700
 * (copy_position, , ),
 * Makes a duplicate of position_source.

position_copy_origin = 719
 * (position_copy_origin, , ),
 * Copies coordinates from source position to target position, without changing rotation or scale.

position_copy_rotation = 718
 * (position_copy_rotation, , ),
 * Copies rotation from source position to target position, without changing coordinates or scale.

position_transform_position_to_parent = 716
 * (position_transform_position_to_parent, , , ),
 * Converts position from local coordinate space to parent coordinate space. In other words, if you have some position on the scene (anchor) and a position describing some place *relative* to anchor (for example [10,20,0] means "20 meters forward and 10 meters to the right"), after calling this operation you will get that position coordinates on the scene in . Rotation and scale is also taken care of, so you can use relative angles.

position_transform_position_to_local = 717
 * (position_transform_position_to_local, , , ),
 * The opposite to (position_transform_position_to_parent), this operation allows you to get source's *relative* position to your anchor. Suppose you want to run some decision making for your bot agent depending on player's position. In order to know where player is located relative to your bot you call (position_transform_position_to_local, , , ). Then we check position_dest's Y coordinate - if it's negative, then the player is behind our bot's back.

Position (X,Y,Z) coordinates
position_get_x = 726
 * Return position X coordinate (to the east, or to the right). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).
 * Return position X coordinate (to the east, or to the right). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).

position_get_y = 727
 * Return position Y coordinate (to the north, or forward). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).
 * Return position Y coordinate (to the north, or forward). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).

position_get_z = 728
 * Return position Z coordinate (to the top). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).
 * Return position Z coordinate (to the top). Base unit is meters. Use (set_fixed_point_multiplier) to set another measurement unit (100 will get you centimeters, 1000 will get you millimeters, etc).

position_set_x = 729
 * Set position X coordinate.
 * Set position X coordinate.

position_set_y = 730
 * Set position Y coordinate.
 * Set position Y coordinate.

position_set_z = 731
 * Set position Z coordinate.
 * Set position Z coordinate.

position_move_x = 720
 * Moves position along X axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) X axis (i.e. whether the position will be moved to it's right/left, or to the global east/west).
 * Moves position along X axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) X axis (i.e. whether the position will be moved to it's right/left, or to the global east/west).

position_move_y = 721
 * Moves position along Y axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) Y axis (i.e. whether the position will be moved forward/backwards, or to the global north/south).
 * Moves position along Y axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) Y axis (i.e. whether the position will be moved forward/backwards, or to the global north/south).

position_move_z = 722
 * Moves position along Z axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) Z axis (i.e. whether the position will be moved to it's above/below, or to the global above/below - these directions will be different if the position is tilted).
 * Moves position along Z axis. Movement distance is in cms. Optional parameter determines whether the position is moved along the local (value=0) or global (value=1) Z axis (i.e. whether the position will be moved to it's above/below, or to the global above/below - these directions will be different if the position is tilted).

position_set_z_to_ground_level = 791
 * This will bring the position Z coordinate so it rests on the nearest ground level (i.e. an agent could stand on that position). This takes scene props with their collision meshes into account. Only works during a mission, so you can't measure global map height using this.
 * This will bring the position Z coordinate so it rests on the nearest ground level (i.e. an agent could stand on that position). This takes scene props with their collision meshes into account. Only works during a mission, so you can't measure global map height using this.

position_get_distance_to_terrain = 792
 * This will measure the distance between position and terrain below, ignoring all scene props and their collision meshes. Retrieves a negative value if underground. Operation only works on the scenes and cannot be used on the global map.
 * This will measure the distance between position and terrain below, ignoring all scene props and their collision meshes. Retrieves a negative value if underground. Operation only works on the scenes and cannot be used on the global map.

position_get_distance_to_ground_level = 793
 * This will measure the distance between position and the ground level, taking scene props and their collision meshes into account. Operation only works on the scenes and cannot be used on the global map.
 * Values can be negative if ground level is up to 1 meter aproximately.
 * Values can be negative if ground level is up to 1 meter aproximately.

Position rotation
position_get_rotation_around_x = 742
 * (position_get_rotation_around_x,, ),
 * Returns angle (in degrees) that the position is rotated around X axis (tilt forward/backwards).

position_get_rotation_around_y = 743
 * (position_get_rotation_around_y,, ),
 * Returns angle (in degrees) that the position is rotated around Y axis (tilt right/left).

position_get_rotation_around_z = 740
 * (position_get_rotation_around_z,, ),
 * Returns angle (in degrees) that the position is rotated around Z axis (turning right/left).

position_rotate_x = 723
 * (position_rotate_x,, ),
 * Rotates position around it's X axis (tilt forward/backwards).

position_rotate_y = 724
 * (position_rotate_y,, ),
 * Rotates position around Y axis (tilt right/left).

position_rotate_z = 725
 * (position_rotate_z,, , [use_global_z_axis]),
 * Rotates position around Z axis (rotate right/left). Pass 1 for use_global_z_axis to rotate the position around global axis instead.

position_rotate_x_floating = 738
 * (position_rotate_x_floating,, <angle_fixed_point>),
 * Same as (position_rotate_x), but takes fixed point value as parameter, allowing for more precise rotation.

position_rotate_y_floating = 739
 * (position_rotate_y_floating,, <angle_fixed_point>),
 * Same as (position_rotate_y), but takes fixed point value as parameter, allowing for more precise rotation.

position_rotate_z_floating = 734
 * (position_rotate_z_floating, <position_no>, <angle_fixed_point>, [use_global_z_axis]),
 * Version 1.161+. Same as (position_rotate_z), but takes fixed point value as parameter, allowing for more precise rotation.
 * Pass 1 for use_global_z_axis to rotate the position around global axis instead.

Position scale
position_get_scale_x = 735
 * (position_get_scale_x, <destination_fixed_point>, ),
 * Retrieves position scaling along X axis.

position_get_scale_y = 736
 * (position_get_scale_y, <destination_fixed_point>, ),
 * Retrieves position scaling along Y axis.

position_get_scale_z = 737
 * (position_get_scale_z, <destination_fixed_point>, ),
 * Retrieves position scaling along Z axis.

position_set_scale_x = 744
 * (position_set_scale_x,, <value_fixed_point>),
 * Sets position scaling along X axis.

position_set_scale_y = 745
 * (position_set_scale_y,, <value_fixed_point>),
 * Sets position scaling along Y axis.

position_set_scale_z = 746
 * (position_set_scale_z,, <value_fixed_point>),
 * Sets position scaling along Z axis.

Measurement of distances and angles
get_angle_between_positions = 705
 * (get_angle_between_positions, <destination_fixed_point>, <position_no_1>, <position_no_2>),
 * Calculates angle between positions, using positions as vectors. Only rotation around Z axis is used. In other words, the function returns the difference between Z rotations of both positions.

position_has_line_of_sight_to_position = 707
 * (position_has_line_of_sight_to_position, <position_no_1>, <position_no_2>),
 * Checks that you can see one position from another. This obviously implies that both positions must be in global space. Note this is computationally expensive, so try to keep number of these to a minimum.

get_distance_between_positions = 710
 * (get_distance_between_positions,, <position_no_1>, <position_no_2>),
 * Returns distance between positions in centimeters.

get_distance_between_positions_in_meters = 711
 * (get_distance_between_positions_in_meters,, <position_no_1>, <position_no_2>),
 * Returns distance between positions in meters.

get_sq_distance_between_positions = 712
 * (get_sq_distance_between_positions,, <position_no_1>, <position_no_2>),
 * Returns squared distance between two positions in centimeters.

get_sq_distance_between_positions_in_meters = 713
 * (get_sq_distance_between_positions_in_meters,, <position_no_1>, <position_no_2>),
 * Returns squared distance between two positions in meters.

position_is_behind_position = 714
 * (position_is_behind_position, <position_base>, <position_to_check>),
 * Checks if the second position is behind the first.

get_sq_distance_between_position_heights = 715
 * (get_sq_distance_between_position_heights,, <position_no_1>, <position_no_2>),
 * Returns squared distance between position *heights* in centimeters.

position_normalize_origin = 741
 * (position_normalize_origin, <destination_fixed_point>, ),
 * What this operation seems to do is calculate the distance between the zero point [0,0,0] and the point with position's coordinates. coordinates transforms so distance become 1 meter. Then x,y coordinates can be multiplied, for example, by 10 and new position will be 10 meters in that direction.

position_get_screen_projection = 750
 * (position_get_screen_projection, <position_screen>, <position_world>),
 * Calculates the screen coordinates of the position and stores it as position_screen's X and Y coordinates. Works in missions. Not shure if it works on global map.

Global map positions
map_get_random_position_around_position = 1627
 * (map_get_random_position_around_position, <dest_position_no>, <source_position_no>, ),
 * Returns a random position on the global map in the vicinity of the source_position.

map_get_land_position_around_position = 1628
 * (map_get_land_position_around_position, <dest_position_no>, <source_position_no>, ),
 * Returns a random position on the global map in the vicinity of the source_position. Will always return a land position (i.e. some place you can walk to).

map_get_water_position_around_position = 1629
 * (map_get_water_position_around_position, <dest_position_no>, <source_position_no>, ),
 * Returns a random position on the global map in the vicinity of the source_position. Will always return a water position (i.e. sea, lake or river).