Script Path

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

A Script Path (also named Object Path) lets the script in Grand Theft Auto: Vice City attach objects to a path and control their movement along it. The coordinates for the path are stored in a plain text file located in \data\paths\spath0.dat, which is used by Cortez's yacht in the mission "All Hands On Deck!" The game can read any number of script path files in the same directory (spath1.dat, spath2.dat, spath3.dat, etc.) but it can only have up to three script paths loaded at a time. Up to six objects can be attached to a script path at a time. Data on the state and properties of a loaded script path are saved in block 17 of the save file. The concept for script paths closely resembles flight paths used for airborne NPC vehicles.

Format for spath*.dat

NumNodes
X Y Z
GTA Vice City Identifier Type Description
Section 1: Number of path nodes
A NumNodes integer The number of lines that are to be read from the file.
Section 2: Path nodes
A,B,C X, Y, Z float[3] X, Y, Z coordinates, each line linked to create a path
Repeat up to the number of path nodes

Undefined lines of coordinates will use the center of the world (0, 0, 0) as the point for the path.

Mission script

The following commands along with their details relate directly to the script path in the game's mission script.

INITIALISE_OBJECT_PATH

INITIALISE_OBJECT_PATH (opcode 049C) is a command that requests a script path file to be used by other related commands. It can be released using CLEAR_OBJECT_PATH. The first parameter comes from the path file's number at the end of the file name, i.e. spath0.dat would use a value of 0, spath1.dat would use a value of 1, etc. The second parameter denotes how far from the path can the object be when traveling along the path. The larger the value, the more smooth the path can be, while the smaller the value, the more rigid the path can be. More than one variables can handle one script path file. Only one script path file was used in the original script but additional script paths can be created and used.

START_OBJECT_ON_PATH

START_OBJECT_ON_PATH (opcode 049D) is a command that attaches an object to the script path. The object is relocated to the current position of the path by the center of its bounding box so it does not matter how or where the object was created beforehand. The object's position and heading cannot be changed after being attached. Once the first object is attached to the path, the path will immediately start with a speed of 1.0 though that can be changed through SET_OBJECT_PATH_SPEED. This command can only be used a maximum of six times per script path; any more times do not attach the object and may cause game instability.

SET_OBJECT_PATH_SPEED

SET_OBJECT_PATH_SPEED (opcode 049E) is a command that sets the speed in units per second of the script path. A negative value is acceptable, allowing objects on the path to move backwards.

SET_OBJECT_PATH_POSITION

SET_OBJECT_PATH_POSITION (opcode 049F) is a command that sets the distance in units to put attached objects along the script path. 0.0 is the beginning of the path and the distance will never exceed the total distance of the path.

Example

The following example explains how spath0.dat is used in the original script in Sanny Builder's format to move Cortez's yacht. First, the script path is initialized using opcode 049C.

049C: $722 = scripted_path_file 0 width 90.0

Next, objects need to be created using opcode 029B (opcode 0107 can also be used to create them).

029B: $714 = init_object #YT_MAIN_BODY at -375.499 -1322.31 9.81124
029B: $715 = init_object #YT_MAIN_BODY2 at -375.499 -1322.31 9.81124
029B: $717 = init_object #YT_DOORS14 at -375.499 -1322.31 9.81124
029B: $718 = init_object #YT_TMP_BOAT at -375.499 -1322.31 9.81124
029B: $719 = init_object #LODMAIN_BODY at -375.499 -1322.31 9.81124

These objects are attached to the path using opcode 049D.

049D: attach_scripted_file $722 with_object $714
049D: attach_scripted_file $722 with_object $715
049D: attach_scripted_file $722 with_object $717
049D: attach_scripted_file $722 with_object $718
049D: attach_scripted_file $722 with_object $719

Lastly, opcode 049E is used to prevent the yacht from moving along the path.

049E: set_scripted_file $722 speed_to 0.0

During the mission, the yacht's speed varies and is warped along the path in two occasions using opcode 049F.

049E: set_scripted_file $722 speed_to 5.0
// ...
049F: set_scripted_file $722 distance_along_path_to 2700.0

When you fail the mission, the yacht is reset back to the beginning.

049F: set_scripted_file $722 distance_along_path_to 0.0 
049E: set_scripted_file $722 speed_to 0.0

When you pass the mission, the objects and path are no longer needed so they are removed from the game using opcodes 0108 and 04A1 respectively.

0108: destroy_object $714
0108: destroy_object $715
0108: destroy_object $717
0108: destroy_object $718
0108: destroy_object $719
04A1: release_scripted_file $722

Note that if a script path is actively moving objects, replays will be disabled.

See also

Copyrighted

This page is licensed under the GNU Free Documentation Licence. This page has a separate license to the CC-BY-SA that applies to most of Grand Theft Wiki.

The full text of the GNU FDL v1.2 is here. Click the "History" button to see the full list of authors. See Grand Theft Wiki:Copyright for more detail on our copyright policy.

GNU Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
See Grand Theft Wiki:Copyright for more information.