Skip to content

Battle SFX Sequence

Jump to bottom Edit New page
Tirlititi edited this page Nov 19, 2024 · 13 revisions

Table of Contents

Sequence File

The sequence of a battle special effect (SFX) controls various things related to that SFX: the frame when the damage applies, the movements and animations of the caster and the target, the fading of the background, etc. With the option SFXRework = 1, each SFX uses two sequence text files: - StreamingAssets/Data/SpecialEffects/ef[SFX ID]/PlayerSequence.seq that runs when a player character uses the SFX - StreamingAssets/Data/SpecialEffects/ef[SFX ID]/Sequence.seq that runs when a PlaySFX instruction is reached in another sequence file.

Exceptionally, a SFX may have no PlayerSequence.seq (when the SFX cannot be used by a player character) or Sequence.seq.

In addition, enemy binary sequences (contained in the assets with the extension .raw17.bytes) are automatically converted into text sequences. However, it is possible to define custom sequence text files for enemies as well in a mod folder with the use of Battle Patch. For that, create a .seq file in your mod folder, say [ModFolder]/FF9_Data/CustomEnemySequences/MaskedMan_TornadoPunch.seq and specify by which enemy(ies) and for which attack(s) it should be used with the attack entry SequenceFile. In the example of a custom attack of the Masked Man, that would be: 

 == Battle: 336 ==
 = Attack: 0 =
 SequenceFile: CustomEnemySequences/MaskedMan_TornadoPunch.seq

Format

A sequence text file may contain comments of the C++ style: everything on a line after // will be ignored. The file is case-sensitive.

Each line corresponds to an instruction. An instruction starts with a code, possibly followed by : and a list of arguments. The list of arguments is semi-colon-separated (;). Each argument is comprised of a key and a value, sometimes one of them being implicit. When both an argument key and value are explicit, they are separated by =.

Thus, instruction lines may have one of the following formats: 

 CODE
 CODE: ARG_KEY1=ARG_VALUE1 ; ARG_KEY2=ARG_VALUE2
 CODE: ARG_VALUE1 ; ARG_VALUE2 ; ARG_KEY3 ; ARG_KEY4=ARG_VALUE4

The value of an argument can be implicit if and only if it is a boolean type: the value is then implicitly set to True. The key of an argument can be implicit, in which case the keys are implicitly used in the order defined by the instruction table.

Threads

The flow control is done by the special codes StartThread, EndThread, and optionally one or multiple ElseThread in-between. These may define a condition for the enclosed instructions to run, may let several instruction threads run in parallel or may loop the enclosed instructions several times. 

StartThread
	// Enclosed instructions
EndThread

Conditional threads

When the argument Condition is provided, the enclosed instructions will run only if the condition is satisfied. The condition must be a NCalc formula returning a boolean value and that can use the parameters related to the command, the caster and the target.

Example: 

// The condition "CasterRow == 0 && AreCasterAndSelectedTargetsEnemies" checks that
// 1) The caster is in back row
// 2) The caster is an enemy of all of the targets selected by the command (ignoring the changes induced by Reflect or by target swap instructions)
StartThread: Condition = CasterRow == 0 && AreCasterAndSelectedTargetsEnemies
	MoveToPosition: Char=Caster ; RelativePosition=(0, 0, 400) ; Anim=MP_STEP_FORWARD
EndThread

A ElseThread is a thread that may run only if the previous thread's condition was not satisfied. It can use the same arguments as a StartThread.

Example: 

// Randomly play the SFX Fire, Blizzard or Thunder with 33% chance for each
StartThread: Condition = GetRandom(0, 3) == 0 ; Sync
	LoadSFX: SFX = Fire__Single ; Reflect
	WaitSFXLoaded: SFX = Fire__Single ; Reflect
	PlaySFX: SFX = Fire__Single ; Reflect
	WaitSFXDone: SFX = Fire__Single ; Reflect
ElseThread: Condition = GetRandom(0, 2) == 0 ; Sync
	LoadSFX: SFX = Blizzard__Single ; Reflect
	WaitSFXLoaded: SFX = Blizzard__Single ; Reflect
	PlaySFX: SFX = Blizzard__Single ; Reflect
	WaitSFXDone: SFX = Blizzard__Single ; Reflect
ElseThread: Sync
	LoadSFX: SFX = Thunder__Single ; Reflect
	WaitSFXLoaded: SFX = Thunder__Single ; Reflect
	PlaySFX: SFX = Thunder__Single ; Reflect
	WaitSFXDone: SFX = Thunder__Single ; Reflect
EndThread

Synchronous and asynchronous threads

When a thread is run synchronously, the parent thread (the thread in which the StartThread instruction is in) waits for it to finish. Threads are asynchronous by default.

Example: 

// This thread is synchronous: the instructions below it will not run before it ends
StartThread: Sync
	MoveToPosition: Char = Caster ; RelativePosition = (0, 0, 400) ; Anim = MP_STEP_FORWARD
	WaitMove: Char = Caster
EndThread
// The following instruction waits for the caster to have moved
PlayAnimation: Char = Caster ; Anim = MP_IDLE_TO_CHANT
// This thread is asynchronous: the instructions below it run simultaneously
StartThread
	WaitAnimation: Char = Caster
	PlayAnimation: Char = Caster ; Anim = MP_CHANT
	WaitAnimation: Char = Caster
	PlayAnimation: Char = Caster ; Anim = MP_MAGIC
EndThread
// The following instruction runs as the caster starts playing its MP_IDLE_TO_CHANT animation
Message: Text=Prepare yourself to taste my magic!

Target swap

It is possible to define a new target for the enclosed instructions of a thread. This can be done in two ways: either defining a new target with the Target argument or by looping over all the current targets by enabling the TargetLoop argument. Note that a thread will never run if the Target defined for it is empty.

Example: 

StartThread: Target = AllPlayers
	// In this thread, every reference to the targets will reference all the player characters instead
	StartThread: TargetLoop
		// This thread will repeat as many times as there are player characters
		// "AllTargets" now references each one of them individually
	EndThread
	// Back to "AllTargets = AllPlayers"
EndThread
// Back to the original targets

Looping threads

It is possible for threads to loop, either by using the TargetLoop argument as explained above or by setting the LoopCount argument. LoopCount allows for instructions to apply a specified number of times. You can only use a constant number for now, not a variable looping count.

Looping threads may loop using two different patterns: either they execute simultaneously or they execute one after the other. Enabling the Chain argument, each instance of a thread waits for the previous one to have finished.

Example: 

// All the targets are moved upward simultaneously
StartThread: TargetLoop
	MoveToPosition: Char = AllTargets ; RelativePosition = (0, 400, 0) ; UseHeight ; Time = 10
EndThread
Wait: 10
// All the targets are now moved downward one after the other
StartThread: TargetLoop ; Chain
	MoveToPosition: Char = AllTargets ; RelativePosition = (0, -400, 0) ; UseHeight ; Time = 10
	WaitMove: Char = AllTargets
EndThread

List of instructions

A special argument, Reflect, can be used by any instruction: when enabled, the instruction will also run during the potential second cast of Reflect. This second cast triggers when a multi-target spell is reflected by some but not all of its targets: for the normal cast, the sequence's targets are the non-reflecting original targets, for the second cast, the sequence's targets are the characters or enemies on which the spell was reflected.

Code Arguments
Wait Time (number): the frames to wait
WaitAnimation Char (character): the character(s) to wait for the animation to end.
WaitMove Char (character): the character(s) to wait for the movement to end.
WaitTurn Char (character): the character(s) to wait for the turning movement to end.
WaitSize Char (character): the character(s) to wait for the size change to end.
WaitSFXLoaded SFX (SFX): the SFX to wait the loading for.
Instance (SFX instance): an ID in case several SFX of the same kind are used.
WaitSFXDone SFX (SFX): the SFX to wait the execution for.
Instance (SFX instance): an ID in case several SFX of the same kind are used.
WaitReflect No argument
Channel Type (channel name): the name of the channel type.
Char (character): the channeling character.
SkipFlute (boolean): by default, the flute sounds (1501, 1507 and 1508) are played when Eiko channels wearing a flute; this behaviour can be deactivated.
StopChannel Char (character): the channeling character.
LoadSFX SFX (SFX): the SFX to load.
Char (character): the caster of the visual effect.
Target (character): the target(s) of the visual effect.
TargetPosition (position): a custom position for visual effects allowing it.
UseCamera (boolean): force the usage or not of camera movements.
FirstBone (bone): bone of the caster, for the visual effect usage.
SecondBone (bone): bone of the caster, for the visual effect usage.
Args (number): unknown.
MagicCaster (character): the magic caster of the visual effect for Magic Sword-like effects.
PlaySFX SFX (SFX): the SFX to play.
Instance (SFX instance): an ID in case several SFX of the same kind are used.
JumpToFrame (number): add a delay to the SFX execution when negative; skip the start of the effect when positive.
SkipSequence (boolean): do not run the corresponding Sequence.seq file.
HideMeshes (SFX mesh list): prevent the rendering of SFX meshes.
MeshColors (SFX mesh colors): multiply SFX mesh RGB color channels with a custom color.
CreateVisualEffect SPS (number) or SHP (number) or SFXModel (file path): the ID or path of the visual effect to use.
Char (character): to show the visual effect on each of these characters.
Bone (bone): the attachment point of the effect.
Offset (position): an offset to add to the effect's position (or the "average position" in case of SFX Model).
Size (decimal): the scaling factor of the visual effect.
Time (number): the duration of the visual effect.
Speed (decimal): the speed factor for the effect's animation.
UseSHP (boolean) or UseSFXModel: specify that the first argument provided is a SHP ID or a SFX model path.
Turn Char (character): the character(s) to turn.
BaseAngle (base angle): the base angle to turn to.
Angle (angle): the offset to the base angle.
Time (number): the duration of the turning movement.
UsePitch (boolean): interpret the angle offset as a pitch instead of an orientation.
PlayAnimation Char (character): the character(s) to play the animation of.
Anim (animation): the animation to play.
Speed (decimal): the speed ratio of the animation.
Loop (boolean): make the animation loop.
Palindrome (boolean): make the animation play back and forth.
Frame (number): the frame to start the animation at.
PlayTextureAnimation Char (character): the character(s) to play the texture animation of.
Anim (number): the ID of the texture animation to play.
Once (boolean): play it once.
Stop (boolean): stop it instead of playing it.
ToggleStandAnimation Char (character): the character(s) to change the default animations of (it should be an enemy).
Alternate (boolean): use the alternate animations.
MoveToTarget Char (character): the character(s) to move.
Target (character): the character(s) to move to.
Offset (position): the offset to the target position.
Distance (decimal): the distance offset toward the target.
Time (number): the duration of the movement.
Anim (animation): the animation to play during the movement (setup the duration).
MoveHeight (boolean): also move the height of the character.
UseCollisionRadius (boolean): add the target's radius to the distance (single-target only).
IsRelativeDistance (boolean): use the moving character's position as a basis instead of the target's position.
MoveToPosition Char (character): the character(s) to move.
AbsolutePosition (position): the position to move to.
RelativePosition (position): the offset added to the absolute position.
Time (number): the duration of the movement.
Anim (animation): the animation to play during the movement (setup the duration).
MoveHeight (boolean): also move the height of the character.
ChangeSize Char (character): the character(s) to rescale.
Size (size): the new size.
Time (number): the duration of the rescale.
ScaleShadow (boolean): also rescale the shadow.
IsRelative (boolean): the new size is relative to the current size.
ShowMesh Char (character): the character(s) to show/hide.
Enable (boolean): either show or hide.
Mesh (mesh list): the meshes to show/hide.
Time (number): the fading duration.
IsDisappear (boolean): make the character completly disappear.
ShowShadow Char (character): the character(s) to show/hide the shadow of.
Enable (boolean): either show or hide.
ChangeCharacterProperty Char (character): the character(s) to change the property of.
Property (property type): the property to change.
Value (property value): the updated value.
PlaySound Sound (sound): the sound ID or name.
SoundType (sound type): the sound type.
Volume (decimal): the sound's volume.
Pitch (decimal): the sound's pitch.
Panning (decimal): the sound's panning.
StopSound Sound (sound): the sound ID or name.
SoundType (sound type): the sound type.
EffectPoint Char (character): the character(s) to apply the ability's effect on.
Type (effect type): either the damage point, the figure point or both.
Message Text (message): the text to display. The arguments TextUS, TextJP etc. can be used for language-dependant messages.
Title (boolean): whether the message is a title or a dialog (influences the message box's appearance).
Priority (number): the priority of the message over other messages.
SetBackgroundIntensity Intensity (decimal): the intensity ratio.
Time (number): the fading time.
HoldDuration (number): the duration of the intensity drop.
ShiftWorld Offset (position): the offset by which the world is moved (characters and background, but not camera nor SFX).
Angle (angle): the angle(s) by which the world is rotated.
SetVariable Variable (variable type): the variable to change.
Index (depends on variable type): either the array index or a string key.
Value (variable value): the updated value.
SetupReflect Delay (reflect delay): the delay to wait before the reflect visual effect gets displayed.
ActivateReflect No argument
StartThread
ElseThread 		Condition (formula): see Conditional threads.
LoopCount (number): see Looping threads.
Target (character): see Target swap.
TargetLoop (boolean): see Target swap.
Chain (boolean): see Looping threads.
Sync (boolean): see Sync and async threads.
EndThread No argument
MOVE_WATER Char (character): the character(s) to move.
Type (Single/Multi/Sword): the type of Water-spell movement.
Time (number): the duration of the movement.

Argument types

Type Possible values
character AllTargets: the targets of the thread, subject to target swap or reflect bounce.
AllNonTargets: all the units except those in AllTargets.
RandomTarget: a random target amongst AllTargets.
Caster: the user of the command.
AllPlayers: the player's team.
AllEnemies: the enemy team.
Everyone: both teams.
Zidane, Vivi, Dagger, Steiner, Freya, Quina, Eiko, Amarant, Cinna, Marcus, Blank, Beatrix: the corresponding player character if present.
FirstTarget, SecondTarget etc.: the corresponding target amongst AllTargets if there are at least that many.
A number: the character(s) as a bit flag.
MatchingCondition({Condition}): a NCalc formula specifying a custom condition, eg. MatchingCondition(IsPlayer != CasterIsPlayer && Level < CasterLevel) for picking all the caster's enemies that are of a lower level.
bone Target: the bone that is used for target selection.
Weapon: the weapon's bone, if any.
Root: the bone 0, which is always the model's root bone (usually somewhere around the chest).
Icon:{number}: one of the 6 icon attachement points, from 0 to 5 (eg. Icon:2 is the "mouth" attachement point, used by the SHP of Silence).
A number: the bone ID.
SFX Weapon: for player characters, the SFX corresponding to the character's attack.
A SFX name: see the list.
A SFX numerical ID: see the list.
All (doesn't apply to LoadSFX): all the SFX loaded.
SFX instance A number: the SFX row in the list of loaded SFX, starting from 1; when the SFX type is also provided, only count the SFX of the same type.
Note that not providing this argument will make the instruction refer to the latest SFX that was loaded by the thread.
SFX mesh list A comma-separated list of numbers: the list of SFX parts to hide, in their appearing order; hexadecimal numbers may also be provided to refer to specific mesh codes.
SFX mesh colors A color (R, G, B): a color multiplier for all the SFX meshes.
A comma-separated list of N:(R, G, B): a color multiplier for the N-th SFX mesh, in their appearing order.
A comma-separated list of 0xN:(R, G, B): a color multiplier for the SFX meshes identified by their mesh code.
channel name A channel name: a name amongst available channel types (Spell, Black, Summon and Enemy).
Notes: One may use a custom channel name by providing an asset StreamingAssets/Data/SpecialEffects/Common/Channel[Name].sfxmodel.
When unspecified, the channel is defaulted to "Enemy" for the Blue Magic command or enemy spells, "Black" for Black, Double Black and Magic Sword commands, "Summon" for summoning commands and "Spell" by default.
animation Current: the current character's animation.
Idle: the default character's idling animation. When using it with the instruction PlayAnimation for the command's caster or magic caster, it also triggers the "idling point" of the command at which the character is allowed to use another command.
A motion code: the corresponding battle animation (see the list).
An animation name: the name of the animation asset.
position A vector in (x, height, y) format: the vector position or offset.
A vector in (x, y) format: the vector position or offset with a 0 height.
Default (for the AbsolutePosition argument only): the base position of the character.
base angle Current: the current character's angle.
Default: the default character's angle.
A character: the angle toward specified character(s).
angle A decimal: the angle value in degrees.
A vector in (pitch, orientation, roll) format: the complete Euler angles.
size Reset: the default size (1, 1, 1).
A vector in (x, h, y) format: the size in each direction.
A decimal: the size in all directions.
mesh list All: all the meshes, including the weapon meshes and the shadow.
Weapon: the weapon meshes.
Shadow: the shadow mesh.
Vanish: the meshes hidden under the status Vanish.
Main: all the meshes except the weapon meshes and the shadow.
A number: the list of meshes as bit flags.
sound WeaponAttack: for player characters, the sound effect of swinging the weapon.
WeaponHit: for player characters, the sound effect of hitting with the weapon.
A number (for SoundEffect, Music and Song): the sound numerical ID.
A FMV name (for MovieAudio): the name of the corresponding FMV.
A sound path (for Default): the short path to the sound (the format is usually something like Sounds[Archive number]/SE[00]/se[000000]).
sound type A sound type: see SoundProfileType (default is SoundEffect).
effect type Effect: run the battle script to apply damage, statuses or other effects.
Figure: show the damage number(s) and/or effect messages.
Both: apply the effect point then the figure point.
reflect delay SFXLoaded: wait for any SFX to have loaded (NYI).
SFXPlay: wait for any SFX to have started playing (NYI).
SFXDone: wait for any SFX to have finished playing (NYI).
A number: the time to wait.
property type base_pos: the base position of the character.
tar_bone: the target bone ID of the character.
property value Original (for base_pos): the original battle position.
Current (for base_pos): the current position.
A vector (for base_pos): the absolute position to use.
A value (for tar_bone): the new value.
variable type _ZWrite: the battle background's ground opacity value (1 to make it opaque).
btl_seq: the battle sub-phase (see battle phases and battle sub-phases close, defeat, menu off and victory).
cmd_status: the battle command status (see command system statuses).
gEventGlobal: the array of "general" event script variables (see Hades Workshop's list); their modification here is done bytewise.
local: a dictionary that associates a number (the argument Value) to a string key (the argument Index); the parameter local_{Index} can then be used for thread conditions.
variable value A number: the new value.
A number in the format +N: the offset to add to the current value.
A number in the format &N: the bit flags to keep from the current value.
A number in the format |N: the bit flags to add to the current value.
Formula({Formula}): a NCalc formula that can use only the shared informations and the parameter Current for the previous value of the variable that is modified. For example, Formula(Current + 3) is synonymous to +3.
Add a custom footer
Add a custom sidebar
Clone this wiki locally