User:Jackoalan/Particle Script - Revision history

Jackoalan: Redirected page to Particle Script

2016-02-29T02:58:15Z

Redirected page to Particle Script

Show changes

Jackoalan at 02:48, 29 February 2016

2016-02-29T02:48:08Z

Jackoalan at 01:19, 29 February 2016

2016-02-29T01:19:23Z

Jackoalan at 22:29, 28 February 2016

2016-02-28T22:29:38Z

Jackoalan at 22:15, 28 February 2016

2016-02-28T22:15:41Z

Jackoalan at 07:11, 28 February 2016

2016-02-28T07:11:52Z

Jackoalan at 06:54, 28 February 2016

2016-02-28T06:54:29Z

Show changes

Jackoalan at 03:58, 28 February 2016

2016-02-28T03:58:25Z

Jackoalan at 01:53, 28 February 2016

2016-02-28T01:53:20Z

Jackoalan: Created page with "{{research|1|Details are subject to corrections}} Retro games feature a uniform, fixed-function '''Particle Script''' system for describing various geometrical effects and wea..."

2016-02-27T23:55:36Z

Created page with "{{research|1|Details are subject to corrections}} Retro games feature a uniform, fixed-function '''Particle Script''' system for describing various geometrical effects and wea..."

New page

{{research|1|Details are subject to corrections}}
Retro games feature a uniform, fixed-function '''Particle Script''' system for describing various geometrical effects and weapon systems.
The PAK archives contain binary resources using [[wikipedia:FourCC|FourCCs]] to build a [[wikipedia:Associative_array|key-value dictionary]].
These codes correspond to application-specific parameters controlling the system in question.

The scripts use a [[wikipedia:Dataflow programming|dataflow paradigm]] built around value-generating ''element'' classes of the following types:

* [[#Int Elements|Int]]
* [[#Real Elements|Real]] (float)
* [[#Vector Elements|Vector]] (3-component float)
* [[#Mod Vector Elements|Mod Vector]] (3-component float)
** Velocity vector in/out
** Position vector in/out
* [[#Color Elements|Color]] (4-component float, internally converted to RGBA8)
* [[#UV Elements|UV]] ([[TXTR_(File_Format)|TXTR]] reference and [[wikipedia:UV_mapping|UV coordinate]] source)
* [[#Emitter Elements|Emitter]]
** Initial position vector (3-component float)
** Initial velocity vector (3-component float)

The system features several subclasses that output generated values through <code>GetValue</code> as a function of the current frame index.
These implementations may recursively accept input from other elements, permitting effect designs of scalable complexity.

== File Layout ==

All effect script file formats are read linearly to populate a ''descriptor'' tree of element nodes:

* Script Magic FourCC (see [[#Script Types|table below]])
* Parameters
** Key FourCC
** Value Parameter(s) (one of:)
*** <code>NONE</code>: null value (equivalent to not specifying the key at all)
*** Element FourCC ([[#Elements|see below]])
**** Child Elements (count/types according to parent)
* <code>_END</code>

== Script Types ==

{| class="wikitable"
!Type
!Magic
!Purpose
|-
|[[PART (File Format)|PART]]
|<code>GPSM</code>
|Particle element generator
|-
|[[SWHC (File Format)|SWHC]]
|<code>SWSH</code>
|Swoosh generator
|-
|[[ELSC (File Format)|ELSC]]
|<code>ELSM</code>
|Electric generator
|-
|[[DPSC (File Format)|DPSC]]
|<code>DPSM</code>
|Decal generator
|-
|[[WPSC (File Format)|WPSC]]
|<code>WPSM</code>
|Projectile weapon configuration
|-
|[[CRSC (File Format)|CRSC]]
|<code>CRSM</code>
|Projectile collision response configuration
|}

== Elements ==

Many of the animated qualities in particle scripts are achieved with dynamic ''elements''.
These elements provide I/O interfaces and internally process numeric data that passes through.
They may also gather data from other sources within the particle system's state.

=== Int Elements ===

{| class="wikitable"
! FourCC
! Parameters
! Description
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
{{ParticleElementRow|ADD_|IntElement a, IntElement b|Add|Returns ''a'' + ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|CHAN|IntElement a, IntElement b, IntElement thresholdFrame|Time Chain|Returns ''a'' when current frame index is less-than ''thresholdFrame'', otherwise ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|CLMP|IntElement min, IntElement max, IntElement val|Clamp|Returns ''val'' clamped between ''min'' and ''max''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|CNST|s32 value|Constant|Returns ''value'' on every call|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|DETH|IntElement passthrough, IntElement thresholdFrame|Death|Always returns ''passthrough'', and signals out-of-band to cease updating the system when the current frame index exceeds ''thresholdFrame''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|GAPC||{{unknown|'''Unknown'''}}||{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|GEMT||{{unknown|'''Unknown'''}}||{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|GTCP||{{unknown|'''Unknown'''}}||{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|ILPT|IntElement percent|Lifetime Percent|Queries the frame index at ''percent''/100.0 into the lifetime of the particle instance|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|IMPL|IntElement val|Impulse|Returns ''val'' ONLY at frame index 0, then returns 0 for subsequent frames|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|IRND|IntElement a, IntElement b|Initial Random|Rolls a random value between ''a'' and ''b'' on frame index 0; returns that value for subsequent frames|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|KEYE|[[#Keyframe Emitter Template|KeyframeEmitterData]] data|Keyframe Emitter|List of synchronized animation keys|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|KEYP|[[#Keyframe Emitter Template|KeyframeEmitterData]] data|Keyframe Emitter|List of percentage-tweened animation keys|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|MODU|IntElement a, IntElement b|Modulo|Returns ''a'' % ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|MULT|IntElement a, IntElement b|Multiply|Returns ''a'' * ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|PULS|IntElement aDuration, IntElement bDuration, IntElement a, IntElement b|Pulse|Returns ''a'' for ''aDuration'' frames then ''b'' for ''bDuration'' frames, then repeats this cycle|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|RAND|IntElement a, IntElement b|Random|Rolls a random value between ''a'' and ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|SPAH|IntElement val, IntElement waitMin, IntElement waitMax|Sample And Hold|Stores ''val'' for a random count of frames between ''waitMin'' and ''waitMax'' and repeats this cycle|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|SUB_|IntElement a, IntElement b|Subtract|Returns ''a'' - ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|TSCL|RealElement dv|Time Scale|Returns ''dv'' times the current frame index (rounding down to nearest integer)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
|}

=== Real Elements ===

{| class="wikitable"
! FourCC
! Parameters
! Description
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
{{ParticleElementRow|ADD_|RealElement a, RealElement b|Add|Returns ''a'' + ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|CHAN|RealElement a, RealElement b, IntElement thresholdFrame|Time Chain|Returns ''a'' when current frame index is less-than ''thresholdFrame'', otherwise ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|CLMP|RealElement min, RealElement max, RealElement val|Clamp|Returns ''val'' clamped between ''min'' and ''max''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticleElementRow|CNST|float value|Constant|Returns ''value'' on every call|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
|}

=== Vector Elements ===

=== Mod Vector Elements ===

=== Color Elements ===

=== UV Elements ===

=== Emitter Elements ===

=== Keyframe Emitter Template ===

<code>KEYE</code> and <code>KEYP</code> elements are able to statically encode a list of key values for all element types (except UV and Emitter elements).
''T'' represents the type being encoded.

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| u32
| Percentage-Tweening Flag
| If non-zero, this is a <code>KEYP</code> and there are exactly 100 keys in the list; all of these keys are linearly-interpolated over the lifetime of the particle instance (however long that may be)
|-
| u32
| {{unknown|'''Unknown'''}}
| Not used by <code>GetValue</code>
|-
| u8
| Loop Flag
| If non-zero, the key values are looped between ''loopStart'' and ''loopEnd'' indices (does not apply to <code>KEYP</code>)
|-
| u8
| {{unknown|'''Unknown'''}}
| Not used by <code>GetValue</code>
|-
| u32
| Loop End
| Final key index in the loop
|-
| u32
| Loop Start
| First key index in the loop
|-
| u32
| Key Count
| Count of keys encoded in the list
|-
| T[keyCount]
| Keys
| The actual key values themselves
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

@@ Line 259: / Line 259: @@
 <div class="atex"></div>
 -->
 <div class="thumbcaption">Example of an ATEX map used in the closing cinematic (spoilers)</div>
 </div>
@@ Line 275: / Line 274: @@
 ! DKCTF
 {{ParticleElementRow|CNST|[[TXTR_(File_Format)|TXTR]]&nbsp;tex|Constant|References ''tex'' for sampling using constant UV rectangle points (0,0) (1,1)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
-{{ParticleElementRow|ATEX|[[TXTR_(File_Format)|TXTR]]&nbsp;tex, IntElement&nbsp;tileW, IntElement&nbsp;tileH, IntElement&nbsp;strideW, IntElement&nbsp;strideH, IntElement&nbsp;cycleFrames, bool&nbsp;loop|Animated Texture||{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
+{{ParticleElementRow|ATEX|[[TXTR_(File_Format)|TXTR]]&nbsp;tex, IntElement&nbsp;tileW, IntElement&nbsp;tileH, IntElement&nbsp;strideW, IntElement&nbsp;strideH, IntElement&nbsp;cycleFrames, bool&nbsp;loop|Animated Texture|References ''tex'' for sampling using UV tiles scanned left-to-right, top-to-bottom as individual frames of animation. The UV coordinates are scaled and offset using the ''tile'' and ''stride'' parameters in texels. All tiles of the image are played over the course of ''cycleFrames''. If ''loop'' is set, the tiles repeat, otherwise lingers on the final tile.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 |}
 === Emitter Elements ===
 === Keyframe Emitter Template ===

← Older revision		Revision as of 01:19, 29 February 2016
Line 237:		Line 237:

	=== UV Elements ===		=== UV Elements ===
		+
		+	<div class="thumb tright">
		+	<div class="thumbinner" style="width:130px;">
		+	[[File:ATEX_example.png]]
		+	[[File:ATEX_example_crunchy.gif]]
		+	<!--
		+	<style type="text/css">
		+	.atex
		+	{
		+	width: 32px;
		+	height: 32px;
		+	background: url('/retromodding/images/9/99/ATEX_example_css.png') left center;
		+	zoom: reset;
		+	animation: play .8s steps(16) infinite;
		+	}
		+	@keyframes play
		+	{
		+	100% { background-position: -512px; }
		+	}
		+	</style>
		+	<div class="atex"></div>
		+	-->
		+	<div style="width:32px; height:32px; background: url('/retromodding/images/9/99/ATEX_example_css.png') left center; zoom: reset; animation: play .8s steps(16) infinite;"></div>
		+	<div class="thumbcaption">Example of an ATEX map used in the closing cinematic (spoilers)</div>
		+	</div>
		+	</div>
		+
		+	{\| class="wikitable"
		+	! FourCC
		+	! Parameters
		+	! Description
		+	! Notes
		+	! MP1
		+	! MP2
		+	! MP3
		+	! DKCR
		+	! DKCTF
		+	{{ParticleElementRow\|CNST\|[[TXTR_(File_Format)\|TXTR]] tex\|Constant\|References ''tex'' for sampling using constant UV rectangle points (0,0) (1,1)\|{{check}}\|{{check}}\|{{check}}\|{{check}}\|{{check}}}}
		+	{{ParticleElementRow\|ATEX\|[[TXTR_(File_Format)\|TXTR]] tex, IntElement tileW, IntElement tileH, IntElement strideW, IntElement strideH, IntElement cycleFrames, bool loop\|Animated Texture\|\|{{check}}\|{{check}}\|{{check}}\|{{check}}\|{{check}}}}
		+	\|}

	=== Emitter Elements ===		=== Emitter Elements ===

@@ Line 138: / Line 138: @@
 {{ParticleElementRow|LFTW|RealElement&nbsp;a, RealElement&nbsp;b|Lifetime Tween|Linearly-interpolates ''a'' to ''b'' over the lifetime of the particle instance|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|MULT|RealElement&nbsp;a, RealElement&nbsp;b|Multiply|Returns ''a'' * ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
-{{ParticleElementRow|PAPn||Particle System Access Parameter|Accesses the value stored into ADV[1-8] for each system update|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
+{{ParticleElementRow|PAPn||Particle System Advance Parameter|Accesses the value stored into ADV[1-8] for each system update|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|PRLW||Particle Rotation or Line Width|Returns the rotation (in degrees) or line width for the current particle instance|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|PSLL||Particle Size or Line Length|Returns the size or line length for the current particle instance|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
@@ Line 202: / Line 202: @@
 {{ParticleElementRow|BNCE|VectorElement&nbsp;planePoint, VectorElement&nbsp;planeNormal, RealElement&nbsp;friction, RealElement&nbsp;restitution, bool&nbsp;dieOnPenetrate|Bounce|Maintains the state of an unbounded plane in local space, defined by ''planePoint'' and ''planeNormal''. If the particle's position penetrates this plane, it will either be destroyed if ''dieOnPenetrate'' is set, or a [[wikipedia:Deflection_(physics)|deflection]] will occur. This deflection accounts for [[wikipedia:Friction#Coefficient_of_friction|''friction'']] along the plane and [[wikipedia:Coefficient_of_restitution|''restitution'']] of the objects represented by the particles.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|CHAN|ModVectorElement&nbsp;a, ModVectorElement&nbsp;b, IntElement&nbsp;thresholdFrame|Time Chain|Returns ''a'' when current frame index is less-than ''thresholdFrame'', otherwise ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
-{{ParticleElementRow|CNST|RealElement&nbsp;x, RealElement&nbsp;y, RealElement&nbsp;z|Constant|Composes a mod vector from 3 float components. If all 3 components are ''Constant'', then the internal representation is an optimized <code>CVector3f</code> data-structure. This vector is set as the velocity out when called.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
+{{ParticleElementRow|CNST|RealElement&nbsp;x, RealElement&nbsp;y, RealElement&nbsp;z|Constant|Composes a mod vector from 3 float components. If all 3 components are ''Constant'', then the internal representation is an optimized <code>CVector3f</code> data-structure. This vector overrides the particle's velocity in units/frame.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
-{{ParticleElementRow|EMPL|VectorElement&nbsp;implodePoint, RealElement&nbsp;velocityScale, RealElement&nbsp;maxRadius, RealElement&nbsp;minRadius, bool&nbsp;enableMinRadius|Exponential Implosion|Integrates a cumulative implosion force over time by influencing the velocity (not the position) of particles within ''maxRadius'' of ''implodePoint'' (and outside ''minRadius'' if ''enableMinRadius'' set). The velocity of these particles is set as (particleVelocity + ''velocityScale'' * (''implodePoint'' - particlePosition)).|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
+{{ParticleElementRow|EMPL|VectorElement&nbsp;implodePoint, RealElement&nbsp;velocityScale, RealElement&nbsp;maxRadius, RealElement&nbsp;minRadius, bool&nbsp;enableMinRadius|Exponential Implosion|Integrates a cumulative implosion force over time by influencing the velocity of particles within ''maxRadius'' of ''implodePoint'' (and outside ''minRadius'' if ''enableMinRadius'' set). The velocity of these particles is set as (particleVelocity + ''velocityScale'' * (''implodePoint'' - particlePosition)) units/frame.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
-{{ParticleElementRow|IMPL|VectorElement&nbsp;implodePoint, RealElement&nbsp;velocityScale, RealElement&nbsp;maxRadius, RealElement&nbsp;minRadius, bool&nbsp;enableMinRadius|Implosion|Integrates a cumulative implosion force-differential over time by influencing the velocity (not the position) of particles within ''maxRadius'' of ''implodePoint'' (and outside ''minRadius'' if ''enableMinRadius'' set). The velocity of these particles is set as (particleVelocity + (''velocityScale'' / magnitude(''implodePoint'' - particlePosition)) * (''implodePoint'' - particlePosition)).|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
+{{ParticleElementRow|EXPL|RealElement&nbsp;impulseMagnitude, RealElement&nbsp;falloffFactor|Explode|Rolls a random, normalized vector scaled by ''impulseMagnitude'' on frame 0 and sets this as the particle's velocity in units/frame. Subsequent frames multiply the velocity by ''falloffFactor''.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
-{{ParticleElementRow|LMPL|VectorElement&nbsp;implodePoint, RealElement&nbsp;velocityScale, RealElement&nbsp;maxRadius, RealElement&nbsp;minRadius, bool&nbsp;enableMinRadius|Linear Implosion|Integrates a non-cumulative implosion force-differential over time by influencing the velocity (not the position) of particles within ''maxRadius'' of ''implodePoint'' (and outside ''minRadius'' if ''enableMinRadius'' set). The velocity of these particles is set as ((''velocityScale'' / magnitude(''implodePoint'' - particlePosition)) * (''implodePoint'' - particlePosition)).|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
+{{ParticleElementRow|GRAV|VectorElement&nbsp;acceleration|Gravity|Integrates a simple cumulative ''acceleration'' in units/frame<sup>2</sup>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 |}

@@ Line 151: / Line 151: @@
 {{ParticleElementRow|VYTR|VectorElement vec|Vector Y To Real|Extracts Y component of ''vec''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|VZTR|VectorElement vec|Vector Z To Real|Extracts Z component of ''vec''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 |}
 === Vector Elements ===
 === Mod Vector Elements ===

@@ Line 215: / Line 215: @@
 === Color Elements ===
 === UV Elements ===
@@ Line 223: / Line 243: @@
 === Keyframe Emitter Template ===
-<code>KEYE</code> and <code>KEYP</code> elements are able to statically encode a list of key values for all element types (except UV and Emitter elements).
+<code>KEYE</code> and <code>KEYP</code> elements statically encode a list of key values for all element types (except Mod Vector, UV and Emitter elements).
 ''T'' represents the type being encoded.

@@ Line 1: / Line 1: @@
-{{research|1|Details are subject to corrections}}
+{{research|1|Elements beyond MP1 need to be discovered and documented}}
 Retro games feature a uniform, fixed-function '''Particle Script''' system for describing various geometrical effects and weapon systems.
 The PAK archives contain binary resources using [[wikipedia:FourCC|FourCCs]] to build a [[wikipedia:Associative_array|key-value dictionary]].

@@ Line 119: / Line 119: @@
 ! DKCTF
 {{ParticleElementRow|ADD_|RealElement a, RealElement b|Add|Returns ''a'' + ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|CHAN|RealElement a, RealElement b, IntElement thresholdFrame|Time Chain|Returns ''a'' when current frame index is less-than ''thresholdFrame'', otherwise ''b''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|CLMP|RealElement min, RealElement max, RealElement val|Clamp|Returns ''val'' clamped between ''min'' and ''max''|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 {{ParticleElementRow|CNST|float value|Constant|Returns ''value'' on every call|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 |}
@@ Line 147: / Line 177: @@
 | u32
 | Percentage-Tweening Flag
-| If non-zero, this is a <code>KEYP</code> and there are exactly 100 keys in the list; all of these keys are linearly-interpolated over the lifetime of the particle instance (however long that may be)
+| If non-zero, this is a <code>KEYP</code> and there are exactly 101 keys in the list; all of these keys are linearly-interpolated over the lifetime of the particle instance (however long that may be)
 |-
 | u32