Difference between revisions of "Subobject and subsystem properties"

From FreeSpace Wiki
Jump to: navigation, search
m (Added explanation for $triggered: and added the missing colon to it)
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This page documents the properties that can be applied to subobjects.  
+
This page documents the properties that can be applied to subobjects and to subsystems in their respective properties data in the [[Model files|model file]].
 +
 
 +
==Important notes==
 +
* Subobject/subsystem properties data can be parsed in any order.
 +
* Occasionally an option may lack a trailing 'terminating character' like ':' or '=' from its description. In these cases any character can be used as the trailing 'terminating character'.
 +
* Buffer size of 256 is reserved for the characters in properties data.
 +
 
 +
==Subsystem Properties==
 +
* These can be applied to subsystems, some of which require the subsystem to have an associated subobject.
 +
{| border=0 align=right cellpadding=2 cellspacing=1 style="margin: 0 0 1em 1em; background: #202020; border: 1px #AA2020 solid; border-collapse: collapse; font-size: 95%;"
 +
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''''Key strings and their order for setting subsystems'''''
 +
|-
 +
| align="center"| ''engine''
 +
| Engine subsystem
 +
|-
 +
| align="center"| ''radar''
 +
| Radar dish subsystem
 +
|-
 +
| align="center"| ''turret''
 +
| Turret subsystem
 +
|-
 +
| align="center"| ''navigation''
 +
| Navigation subsystem
 +
|-
 +
| align="center"| ''communication''
 +
| Communication subsystem
 +
|-
 +
| align="center"| ''weapon''
 +
| Weapon control subsystem
 +
|-
 +
| align="center"| ''sensor''
 +
| Sensor subsystem
 +
|-
 +
| align="center"| ''solar''
 +
| Solar panel subsystem
 +
|-
 +
| align="center"| ''gas''
 +
| Gas collector subsystem
 +
|-
 +
| align="center"| ''activator''
 +
| '''''unused'''''
 +
|-
 +
|}
 +
 
 +
===$name===
 +
*Defines the alternate name for the subsystem (''string'')
 +
*Alternate subsystem names offer an alternative option for setting this via [[ships.tbl]] file or via mission data.
 +
 
 +
===$fov===
 +
*Valid only if the true subobject name (not the alternate defined above) contains string "turret" but not strings "radar" or "engine"
 +
*Defines the firing arc of the turret in degrees (''integer'')
 +
*Defaults to 180 degrees if omitted.
 +
 
 +
===$crewspot===
 +
*Valid only if the true subobject name (not the alternate defined above) contains string "turret" but not strings "radar" or "engine"
 +
*Marks the turret as 'crewspot'
 +
*Defines the name of the crewspot (''string'')
 +
*No actual function
 +
 
 +
===$triggered:===
 +
*Defines the subsystem as a rotating subsystem which can be triggered (animated) via [[Animation Code]]
 +
 
 +
===$rotate===
 +
*Marks the subsystem as a rotating subsystem
 +
*Defines the rotation time for the subsystem: the number of seconds to make a complete rotation (''float'')
 +
 
 +
===$rotate_time===
 +
*Marks the subsystem as a rotating subsystem - alternative to $rotate
 +
*Defines the rotation time for the subsystem: the number of seconds to make a complete rotation (''float'')
 +
 
 +
===$rotate_rate===
 +
*Marks the subsystem as a rotating subsystem - alternative to $rotate, with different units
 +
*Defines the rotation rate for the subsystem: the rotational velocity in radians per second (''float'')
 +
{{Table216|
 +
 
 +
===$rotate_accel===
 +
*Specifies the acceleration for a rotating or dumb-rotating subobject.  If not specified, acceleration is 0.5 radians per second per second (''float'', or ''"instant"'')
 +
}}
 +
 
 +
====$pbank====
 +
*Marks the rotation as primary weapon rotation
 +
*Defines the associated weapon bank (''integer'')
 +
<!-- ANY DETAILS ?? -->
 +
 
 +
====$stepped====
 +
*Defines the rotation as a stepped instead of continuous rotation
 +
 
 +
=====$steps=====
 +
*Defines the number of steps per complete rotation (''integer'')
 +
*Defaults to 8
 +
 
 +
=====$t_paused=====
 +
*Defines the pause time, in seconds, between steps (''float'')
 +
*Defaults to 2
 +
 
 +
=====$t_transit=====
 +
*Defines the movement time, in seconds, between pauses (''float'')
 +
*Defaults to 2
 +
 
 +
=====$fraction_accel=====
 +
*Defines the fraction of the stepped rotation time used for acceleration (''float'')
 +
*Must be between 0 .. 0.5
 +
*Defaults to 0.3
 +
 
 +
{{Table224|
 +
===$translate===
 +
*Marks the subsystem as a translating subsystem
 +
*Defines the translation rate for the subsystem: the linear velocity in meters per second (''float'')
 +
 
 +
===$translate_rate===
 +
*Marks the subsystem as a translating subsystem - alternative to $translate
 +
*Defines the translation rate for the subsystem: the linear velocity in meters per second (''float'')
 +
 
 +
===$translate_accel===
 +
*Specifies the acceleration for a translating subobject.  If not specified, acceleration is 0.5 meters per second per second (''float'', or ''"instant"'')
 +
 
 +
====$stepped====
 +
*Defines the translation as a stepped instead of continuous translation
 +
 
 +
=====$reverse_after_step=====
 +
*Defines whether the subsystem should reverse direction after every step (''boolean'')
 +
*Defaults to true
 +
 
 +
=====$step_distance=====
 +
*Defines the distance, in meters, covered by one complete step (''float'')
 +
*Defaults to 25
 +
 
 +
=====$t_paused=====
 +
*Defines the pause time, in seconds, between steps (''float'')
 +
*Defaults to 2
 +
 
 +
=====$t_transit=====
 +
*Defines the movement time, in seconds, between pauses (''float'')
 +
*Defaults to 2
 +
 
 +
=====$fraction_accel=====
 +
*Defines the fraction of the stepped translation time used for acceleration (''float'')
 +
*Must be between 0 .. 0.5
 +
*Defaults to 0.3
 +
}}
  
 
==Subobject Properties==
 
==Subobject Properties==
''TODO: For now, just listing everything parsed in the code (a more logical organization probably exists)''
+
* These can be applied only to subsystem with their own separate subobject, or subobjects without subsystems.
===$triggered:===
+
 
Non-turret subobjects require this property in order to be animatable using [[Animation_Code|Animation Code]].
+
===$dumb_rotate:===
===$dumb_rotate===
+
* Marks the subobject as a 'dumb rotating submodel' (i.e. a submodel that rotates but doesn't require a corresponding subsystem)
 +
* Defines the rotation time for the subobject: the number of seconds to make a complete rotation (''float'')
 +
 
 +
===$dumb_rotate_time===
 +
*Marks the subobject as a 'dumb rotating submodel' - alternative to $dumb_rotate
 +
*Defines the rotation time for the subobject: the number of seconds to make a complete rotation (''float'')
 +
 
 +
===$dumb_rotate_rate===
 +
*Marks the subobject as a 'dumb rotating submodel' - alternative to $dumb_rotate, with different units
 +
*Defines the rotation rate for the subobject: the rotational velocity in radians per second (''float'')
 +
 
 +
===$look_at:===
 +
* Causes the subobject to always "look at" (i.e. point to by rotating on its axis) the origin of another subobject
 +
* ''Integer'' index or ''string'' name of the subobject target
 +
 
 +
===$look_at_offset:===
 +
* Defines an angle offset for a '''$look_at:''' submodel
 +
* ''Float'' angle in degrees
 +
 
 
===$special===
 
===$special===
 +
* Defines special attributes for the subobject
 +
* String, either '''"subsystem"''', '''"no_rotate"''' or '''"shieldpoint"'''
 +
 +
===="subsystem"====
 +
* '''subsystem''' marks the subobject as an subsystem
 +
 +
===="no_rotate"====
 +
* Valid option if '''subsystem''' string was not used
 +
* Marks subobject as an object that should not rotate
 +
 +
===="shieldpoint"====
 +
{{Table371|
 +
* Only usable on special points ('''not''' on submodels).
 +
* Marks the special point as a shield point, see [[Model Point Shields]].}}
 +
 
===$no_collisions===
 
===$no_collisions===
Prevents collision detection from occurring on this subobject and all of its children (recursively).
+
* Prevents collision detection from occurring on this subobject and all of its children (recursively).
 +
 
 
===$nocollide_this_only===
 
===$nocollide_this_only===
Prevents collision detection from occurring on this subobject only (children collide normally).
+
* Prevents collision detection from occurring on this subobject only (children collide normally).
 +
 
 
===$collide_invisible===
 
===$collide_invisible===
Allows full collision detection for things painted with the special "invisible" texture (normally ships collide but weapons do not)
+
* Allows full collision detection for things painted with the special "invisible" texture (normally ships collide but weapons do not)
===$gun_rotation===
+
 
===[[Detail box|$detail_box]]===
+
===$gun_rotation:===
====[[Detail box|$box_min]]====
+
* Marks the submodel as using gun rotation
====[[Detail box|$box_max]]====
+
 
 +
===[[Detail box|$detail_box:]]===
 +
* Marks the subsystem as one with detail box
 +
====[[Detail box|$box_min:]]====
 +
====[[Detail box|$box_max:]]====
 +
====$box_offset:====
 +
{{Table373|
 +
* Optional offset of the detail box from the model center. Without this, the detail box is centered on the submodel.
 +
* Example: '''$offset: 0,0,-100.5''' to make the detail box be positioned 100.5m behind the ship's center.}}
 +
 
 +
===$detail_sphere:===
 +
{{Table3615|
 +
* Marks the subsystem as one with detail sphere. Detail spheres work exactly like detail boxes (see above), except that they only define a radius instead of a box.}}
 +
====$radius:====
 +
{{Table3615|
 +
* Defines the radius of the detail sphere (''float''). If not provided, defaults to the submodel radius.}}
 +
====$offset:====
 +
{{Table3615|
 +
* Optional offset of the detail sphere from the model center. Without this, the detail sphere is centered on the submodel.
 +
* Example: '''$offset: 0,0,-100.5''' to make the detail sphere be positioned 100.5m behind the ship's center.}}
 +
 
 +
===$rotation_axis:===
 +
{{Table202|
 +
* Defines the custom rotation axis of a submodel.  The point represents an axis vector in a particular direction, just like the X axis is the {1,0,0} vector.
 +
* Reads three comma separated ''floats'' enclosed in square or curly brackets.  It does not need to be a normalized vector.
 +
* '''$rotation_axis''' can be followed by whitespace, a colon, or an equals sign.}}
 +
 
 +
===$translation_axis:===
 +
{{Table224|
 +
* Defines the custom translation axis of a submodel.  The point represents an axis vector in a particular direction, just like the X axis is the {1,0,0} vector.
 +
* Reads three comma separated ''floats'' enclosed in square or curly brackets.  It does not need to be a normalized vector.
 +
* '''$translation_axis''' can be followed by whitespace, a colon, or an equals sign.}}
 +
 
 +
===$uvec:===
 +
{{Table3610|
 +
* Defines the "up" direction (vector) of a multipart turret. Usually it stands perpendicular to the ship surface. Doesn't need to be specified for multiparts with a vertical rotation axis.
 +
* Reads three comma separated ''floats''.  It does not need to be a normalized vector.
 +
* Forces turret normal into the same as the '''$uvec'''.
 +
* As of 20.2, '''$uvec''' can be followed by whitespace, a colon, or an equals sign.}}
 +
 
 +
===$fvec:===
 +
{{Table3610|
 +
* Defines the direction of the front a multipart turret will be facing. Doesn't need to be specified for multiparts with a vertical rotation axis.
 +
* Reads three comma separated ''floats''.  It does not need to be a normalized vector.
 +
* As of 20.2, '''$fvec''' can be followed by whitespace, a colon, or an equals sign.}}
  
===$uvec===
+
===$lod0_name===
The "up" direction of a multipart turret. Usually it stands perpendicular to the ship surface. Doesn't need to be specified for multiparts with a vertical rotation axis.
+
* Allows adding LODs to older models and changing from special points to modeled subsystems.
===$fvec===
+
* Example $lod0_name=enginea used on a subobject named engine would allow engineb, engienc, and engined to be used while preserving backward compatibility.  
The direction the front of a multipart turret will be facing. Doesn't need to be specified for multiparts with a vertical rotation axis.
+
 
===$name===
+
===$attach_thrusters===
 +
{{Table3615|
 +
* Allows thrusters associated with this submodel to follow its rotations.}}
 +
{{Warning|
 +
This flag is redundant. This behavior is active regardless of this flag.}}
  
 
[[Category:Modding]]
 
[[Category:Modding]]

Latest revision as of 20:25, 9 January 2024

This page documents the properties that can be applied to subobjects and to subsystems in their respective properties data in the model file.

Important notes

  • Subobject/subsystem properties data can be parsed in any order.
  • Occasionally an option may lack a trailing 'terminating character' like ':' or '=' from its description. In these cases any character can be used as the trailing 'terminating character'.
  • Buffer size of 256 is reserved for the characters in properties data.

Subsystem Properties

  • These can be applied to subsystems, some of which require the subsystem to have an associated subobject.
Key strings and their order for setting subsystems
engine Engine subsystem
radar Radar dish subsystem
turret Turret subsystem
navigation Navigation subsystem
communication Communication subsystem
weapon Weapon control subsystem
sensor Sensor subsystem
solar Solar panel subsystem
gas Gas collector subsystem
activator unused

$name

  • Defines the alternate name for the subsystem (string)
  • Alternate subsystem names offer an alternative option for setting this via ships.tbl file or via mission data.

$fov

  • Valid only if the true subobject name (not the alternate defined above) contains string "turret" but not strings "radar" or "engine"
  • Defines the firing arc of the turret in degrees (integer)
  • Defaults to 180 degrees if omitted.

$crewspot

  • Valid only if the true subobject name (not the alternate defined above) contains string "turret" but not strings "radar" or "engine"
  • Marks the turret as 'crewspot'
  • Defines the name of the crewspot (string)
  • No actual function

$triggered:

  • Defines the subsystem as a rotating subsystem which can be triggered (animated) via Animation Code

$rotate

  • Marks the subsystem as a rotating subsystem
  • Defines the rotation time for the subsystem: the number of seconds to make a complete rotation (float)

$rotate_time

  • Marks the subsystem as a rotating subsystem - alternative to $rotate
  • Defines the rotation time for the subsystem: the number of seconds to make a complete rotation (float)

$rotate_rate

  • Marks the subsystem as a rotating subsystem - alternative to $rotate, with different units
  • Defines the rotation rate for the subsystem: the rotational velocity in radians per second (float)
FS2 Open, 22.0:

$rotate_accel

  • Specifies the acceleration for a rotating or dumb-rotating subobject. If not specified, acceleration is 0.5 radians per second per second (float, or "instant")

$pbank

  • Marks the rotation as primary weapon rotation
  • Defines the associated weapon bank (integer)

$stepped

  • Defines the rotation as a stepped instead of continuous rotation
$steps
  • Defines the number of steps per complete rotation (integer)
  • Defaults to 8
$t_paused
  • Defines the pause time, in seconds, between steps (float)
  • Defaults to 2
$t_transit
  • Defines the movement time, in seconds, between pauses (float)
  • Defaults to 2
$fraction_accel
  • Defines the fraction of the stepped rotation time used for acceleration (float)
  • Must be between 0 .. 0.5
  • Defaults to 0.3


FS2 Open, 23.0:

$translate

  • Marks the subsystem as a translating subsystem
  • Defines the translation rate for the subsystem: the linear velocity in meters per second (float)

$translate_rate

  • Marks the subsystem as a translating subsystem - alternative to $translate
  • Defines the translation rate for the subsystem: the linear velocity in meters per second (float)

$translate_accel

  • Specifies the acceleration for a translating subobject. If not specified, acceleration is 0.5 meters per second per second (float, or "instant")

$stepped

  • Defines the translation as a stepped instead of continuous translation
$reverse_after_step
  • Defines whether the subsystem should reverse direction after every step (boolean)
  • Defaults to true
$step_distance
  • Defines the distance, in meters, covered by one complete step (float)
  • Defaults to 25
$t_paused
  • Defines the pause time, in seconds, between steps (float)
  • Defaults to 2
$t_transit
  • Defines the movement time, in seconds, between pauses (float)
  • Defaults to 2
$fraction_accel
  • Defines the fraction of the stepped translation time used for acceleration (float)
  • Must be between 0 .. 0.5
  • Defaults to 0.3

Subobject Properties

  • These can be applied only to subsystem with their own separate subobject, or subobjects without subsystems.

$dumb_rotate:

  • Marks the subobject as a 'dumb rotating submodel' (i.e. a submodel that rotates but doesn't require a corresponding subsystem)
  • Defines the rotation time for the subobject: the number of seconds to make a complete rotation (float)

$dumb_rotate_time

  • Marks the subobject as a 'dumb rotating submodel' - alternative to $dumb_rotate
  • Defines the rotation time for the subobject: the number of seconds to make a complete rotation (float)

$dumb_rotate_rate

  • Marks the subobject as a 'dumb rotating submodel' - alternative to $dumb_rotate, with different units
  • Defines the rotation rate for the subobject: the rotational velocity in radians per second (float)

$look_at:

  • Causes the subobject to always "look at" (i.e. point to by rotating on its axis) the origin of another subobject
  • Integer index or string name of the subobject target

$look_at_offset:

  • Defines an angle offset for a $look_at: submodel
  • Float angle in degrees

$special

  • Defines special attributes for the subobject
  • String, either "subsystem", "no_rotate" or "shieldpoint"

"subsystem"

  • subsystem marks the subobject as an subsystem

"no_rotate"

  • Valid option if subsystem string was not used
  • Marks subobject as an object that should not rotate

"shieldpoint"

FS2 Open, 3.7.2:
  • Only usable on special points (not on submodels).
  • Marks the special point as a shield point, see Model Point Shields.

$no_collisions

  • Prevents collision detection from occurring on this subobject and all of its children (recursively).

$nocollide_this_only

  • Prevents collision detection from occurring on this subobject only (children collide normally).

$collide_invisible

  • Allows full collision detection for things painted with the special "invisible" texture (normally ships collide but weapons do not)

$gun_rotation:

  • Marks the submodel as using gun rotation

$detail_box:

  • Marks the subsystem as one with detail box

$box_min:

$box_max:

$box_offset:

FS2 Open, 3.7.4:
  • Optional offset of the detail box from the model center. Without this, the detail box is centered on the submodel.
  • Example: $offset: 0,0,-100.5 to make the detail box be positioned 100.5m behind the ship's center.

$detail_sphere:

FS2 Open, 3.6.16:
  • Marks the subsystem as one with detail sphere. Detail spheres work exactly like detail boxes (see above), except that they only define a radius instead of a box.

$radius:

FS2 Open, 3.6.16:
  • Defines the radius of the detail sphere (float). If not provided, defaults to the submodel radius.

$offset:

FS2 Open, 3.6.16:
  • Optional offset of the detail sphere from the model center. Without this, the detail sphere is centered on the submodel.
  • Example: $offset: 0,0,-100.5 to make the detail sphere be positioned 100.5m behind the ship's center.

$rotation_axis:

FS2 Open, 21.0:
  • Defines the custom rotation axis of a submodel. The point represents an axis vector in a particular direction, just like the X axis is the {1,0,0} vector.
  • Reads three comma separated floats enclosed in square or curly brackets. It does not need to be a normalized vector.
  • $rotation_axis can be followed by whitespace, a colon, or an equals sign.

$translation_axis:

FS2 Open, 23.0:
  • Defines the custom translation axis of a submodel. The point represents an axis vector in a particular direction, just like the X axis is the {1,0,0} vector.
  • Reads three comma separated floats enclosed in square or curly brackets. It does not need to be a normalized vector.
  • $translation_axis can be followed by whitespace, a colon, or an equals sign.

$uvec:

FS2 Open 3.6.10:
  • Defines the "up" direction (vector) of a multipart turret. Usually it stands perpendicular to the ship surface. Doesn't need to be specified for multiparts with a vertical rotation axis.
  • Reads three comma separated floats. It does not need to be a normalized vector.
  • Forces turret normal into the same as the $uvec.
  • As of 20.2, $uvec can be followed by whitespace, a colon, or an equals sign.

$fvec:

FS2 Open 3.6.10:
  • Defines the direction of the front a multipart turret will be facing. Doesn't need to be specified for multiparts with a vertical rotation axis.
  • Reads three comma separated floats. It does not need to be a normalized vector.
  • As of 20.2, $fvec can be followed by whitespace, a colon, or an equals sign.

$lod0_name

  • Allows adding LODs to older models and changing from special points to modeled subsystems.
  • Example $lod0_name=enginea used on a subobject named engine would allow engineb, engienc, and engined to be used while preserving backward compatibility.

$attach_thrusters

FS2 Open, 3.6.16:
  • Allows thrusters associated with this submodel to follow its rotations.
Warning: This flag is redundant. This behavior is active regardless of this flag.