Difference between revisions of "Script Path"

From GTAMods Wiki
Jump to navigation Jump to search
m
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''Spath'''*.dat files are '''script path''' files used only in [[Vice City]] to attach and move objects along a path. These files are located in the maps/data folder in the Vice City directory. These files, which mainly contain coordinates, can be controlled by the <code>[[main.scm]]</code> script file. By default, Vice City has only one script path file, <code>spath0.dat</code>, which controls Cortez's yacht in the mission "All Hands On Deck!" Additional script path files can be created by incrementing the number at the end of the file name by one, i.e. <code>spath1.dat</code>, <code>spath2.dat</code>, etc.
+
[[File:VCSpath.jpg|thumb|right|250px|Vice City's <code>spath0.dat</code> map]]
 +
A '''Script Path''' (also named '''Object Path''') lets the [[main.scm|script]] in [[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 <code>{{Dir|vc}}\data\paths\spath0.dat</code>, 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 (<code>spath1.dat</code>, <code>spath2.dat</code>, <code>spath3.dat</code>, 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 [[Saves (GTA VC)#Block 17: Script Paths|block 17 of the save file]]. The concept for script paths closely resembles [[flight.dat|flight]] paths used for airborne NPC vehicles.
  
Script paths was preceded by binary <code>[[chase.dat|chase*.dat]]</code> files from [[GTA 3]] and are succeeded by the binary [[Carrec|R3]] file format in [[San Andreas]] and [[GTA IV]].
+
== Format for spath*.dat ==
 +
{{Pre|1=
 +
NumNodes
 +
X Y Z
 +
}}
  
== Format ==
+
{|class="wikitable center-col-1 center-col-2"
The file starts with the number of lines coordinates that are to be read in the file. The rest of the file contains X, Y, and Z coordinates linked as a path in the game. Undefined lines of coordinates will use the center of the game (0, 0, 0) for the path.
+
!style="width: 3em;" |{{Icon|VC}}
 +
!style="width: 12em;" |Identifier
 +
!style="width: 6em;" |Type
 +
!Description
 +
|-
 +
!colspan="4" |Section 1: Number of path nodes
 +
|-
 +
|A ||NumNodes ||integer ||The number of lines that are to be read from the file.
 +
|-
 +
!colspan="4" |Section 2: Path nodes
 +
|-
 +
|A,B,C ||X, Y, Z ||float[3] ||X, Y, Z coordinates, each line linked to create a path
 +
|-
 +
|colspan="4" {{a|l}} |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.
  
== Scripting ==
+
== Mission script ==
The following information uses [[Sanny Builder]] to explain how to use these files through the <code>main.scm</code> file. First, the script path files needs to be defined in the script file using opcode [[049C]].
+
The following example explains how <code>spath0.dat</code> 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: <span style="color:blue">0@</span> = scripted_path_file 0 width 5.0
+
{{Pre|class=sb-code|1=
Next, objects need to be created either by opcode [[0107]] or [[029B]]. These objects need to be attached to the path using opcode [[049D]].
+
[[049C]]: <span class="nv">$722</span> = scripted_path_file <span class="m">0</span> width <span class="m">90.0</span>
049D: attach_scripted_file <span style="color:blue">0@</span> with_object <span style="color:blue">1@</span>
+
}}
Lastly, the attached objects can start moving along the path using opcode [[049E]].
+
 
049E: set_scripted_file <span style="color:blue">0@</span> speed_to 5.0
+
Next, objects need to be created using opcode [[029B]] (opcode [[0107]] can also be used to create them).
Additional opcodes related to script paths include [[049F]], which warps the objects along the path instead of moving it, and opcode [[04A1]], which removes all references of the specified script path from the game. All of these attributes are saved in the [[Saves (GTA VC)#Block 17: Script Paths|save]] file so that you don't have to reapply the attributes again.
+
{{Pre|class=sb-code|1=
 +
[[029B]]: <span class="nv">$714</span> = init_object <span class="nt">#YT_MAIN_BODY</span> at -<span class="m">375.499</span> -<span class="m">1322.31</span> <span class="m">9.81124</span>
 +
[[029B]]: <span class="nv">$715</span> = init_object <span class="nt">#YT_MAIN_BODY2</span> at -<span class="m">375.499</span> -<span class="m">1322.31</span> <span class="m">9.81124</span>
 +
[[029B]]: <span class="nv">$717</span> = init_object <span class="nt">#YT_DOORS14</span> at -<span class="m">375.499</span> -<span class="m">1322.31</span> <span class="m">9.81124</span>
 +
[[029B]]: <span class="nv">$718</span> = init_object <span class="nt">#YT_TMP_BOAT</span> at -<span class="m">375.499</span> -<span class="m">1322.31</span> <span class="m">9.81124</span>
 +
[[029B]]: <span class="nv">$719</span> = init_object <span class="nt">#LODMAIN_BODY</span> at -<span class="m">375.499</span> -<span class="m">1322.31</span> <span class="m">9.81124</span>
 +
}}
 +
 
 +
These objects are attached to the path using opcode [[049D]].
 +
{{Pre|class=sb-code|1=
 +
[[049D]]: attach_scripted_file <span class="nv">$722</span> with_object <span class="nv">$714</span>
 +
[[049D]]: attach_scripted_file <span class="nv">$722</span> with_object <span class="nv">$715</span>
 +
[[049D]]: attach_scripted_file <span class="nv">$722</span> with_object <span class="nv">$717</span>
 +
[[049D]]: attach_scripted_file <span class="nv">$722</span> with_object <span class="nv">$718</span>
 +
[[049D]]: attach_scripted_file <span class="nv">$722</span> with_object <span class="nv">$719</span>
 +
}}
 +
 
 +
Lastly, opcode [[049E]] is used to prevent the yacht from moving along the path.
 +
{{Pre|class=sb-code|1=
 +
[[049E]]: set_scripted_file <span class="nv">$722</span> speed_to <span class="m">0.0</span>
 +
}}
 +
 
 +
During the mission, the yacht's speed varies and is warped along the path in two occasions using opcode [[049F]].
 +
{{Pre|class=sb-code|1=
 +
[[049E]]: set_scripted_file <span class="nv">$722</span> speed_to <span class="m">5.0</span>
 +
<span class="c1">// ...</span>
 +
[[049F]]: set_scripted_file <span class="nv">$722</span> distance_along_path_to <span class="m">2700.0</span>
 +
}}
 +
 
 +
When you fail the mission, the yacht is reset back to the beginning.
 +
{{Pre|class=sb-code|1=
 +
[[049F]]: set_scripted_file <span class="nv">$722</span> distance_along_path_to <span class="m">0.0</span>
 +
[[049E]]: set_scripted_file <span class="nv">$722</span> speed_to <span class="m">0.0</span>
 +
}}
 +
 
 +
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.
 +
{{Pre|class=sb-code|1=
 +
0108: destroy_object <span class="nv">$714</span>
 +
0108: destroy_object <span class="nv">$715</span>
 +
0108: destroy_object <span class="nv">$717</span>
 +
0108: destroy_object <span class="nv">$718</span>
 +
0108: destroy_object <span class="nv">$719</span>
 +
04A1: release_scripted_file <span class="nv">$722</span>
 +
}}
 +
 
 +
Note that if a script path is actively moving objects, replays will be disabled.
  
 
== See also ==
 
== See also ==
* [[Carrec|Carrec.img]]
+
* {{Icon|3}} [[chase.dat|Chase scene]]
 +
* {{Icon|SA}} {{Icon|4}} [[Carrec|Car recording]]
 +
 
 +
{{VC-navi}}
  
[[Category:Map Formats]][[Category:Mission_Script]][[Category:GTA VC]]
+
[[Category:Map Formats]][[Category:Mission Script]]

Latest revision as of 09:44, 4 September 2017

Vice City's spath0.dat map

A Script Path (also named Object Path) lets the script in 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
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 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