ANCS (File Format): Difference between revisions

no edit summary
imported>Antidote
No edit summary
imported>Antidote
No edit summary
Line 1: Line 1:
The '''ANCS format''' defines characters for animation in Metroid Prime 1 and 2. Starting in Metroid Prime 3, it was replaced by the [[CHAR (Metroid Prime 3)|CHAR]] format. The extension stands for '''AN'''imation '''C'''haracter '''S'''et.
The '''ANCS format''' defines characters for animation in Metroid Prime 1 and 2. Starting in Metroid Prime 3, it was replaced by the [[CHAR (Metroid Prime 3)|CHAR]] format. The extension stands for '''AN'''imation '''C'''haracter '''S'''et.


{{todo|Notate Metroid Prime 2 differences.}}
{{research|3|Most of the file structure is known, but we still don't know what any of it actually is! Also, the table at the end of the file is unknown.}}
{{research|3|Most of the file structure is known, but we still don't know what any of it actually is! Also, the table at the end of the file is unknown.}}


__TOC__
__TOC__


== Header ==
== Root Structure ==
{| class="wikitable"
! Data Type
! Description
! Notes
|-
| u16
| Version
| Always 1
|-
| [[#CharacterSet|CharacterSet]]
| Character Set
| Contains multiple [[#CharacterInfo|CharacterInfo]] Entries
|-
| [[#AnimationSet|AnimationSet]]
| Animation Set
| Describes Meta Animations, Meta Transitions, Half Transitions, and Resource association
|-
|}


The ANCS format is split up into multiple nodes. Each node defines a character - a model, a skeleton, and a skin - and then sets a number of animation-related parameters on each one. At the end of the file, after every node, is a listing of [[ANIM (File Format)|ANIM]] and [[EVNT (File Format)|EVNT]] files.
== CharacterSet ==
 
There's a very short 8-byte header before the nodes begin.


{| class="wikitable"
{| class="wikitable"
! Offset
! Data Type
! Size
! Element Count
! Description
! Description
! Notes
|-
|-
| 0x0
| u16
| 2
| 1
| {{unknown|'''Unknown'''; always 1}}
| Version
| Always 1
|-
|-
| 0x2
| u32
| 2
| 1
| {{unknown|'''Unknown'''; always 1 (maybe actually one 32-bit magic?)}}
| [[#CharacterInfo|CharacterInfo]] count
| Number of characters in this set.
|-
|-
| 0x4
| [[#CharacterInfo|CharacterInfo]]
| 4
| character_info_count
| '''Node count'''
| Characters
|-
|
| 0x8
| colspan=2 {{unknown|Nodes begin}}
|}
|}


== Nodes ==
=== CharacterInfo ===
 
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Element Count
! Description
! Description
! Notes
|-
|-
| u32
| u32
| 1
| 1
| '''Node number'''; starts at 0, increases by 1 on each subsequent node
| id
| Used by the engine to as a unique identifier within the Character Set.
|-
|-
| u16
| u16
| 1
| 1
| {{unknown|Flags? This value can alter the structure of the file. Usually 6.}}
| Info Type Count
| Informs the engine which info types are present within the CharacterSet
|-
|-
| string
| string
| 1
| 1
| '''Node name''' (zero-terminated)
| Character Name
| Human readable name, useful for editors, the engine does not use this internally.
|-
| [[CMDL_(Metroid_Prime)|CMDL]]
| 1
| Character Model
|
|-
| [[CSKR_(File_Format)|CSKR]]
| 1
| Character Skin
|
|-
| [[CINF_(File_Format)|CINF]]
| 1
| Character Rig
|
|-
| u32
| 1
| Animation Count
| Animations in AnimationSet that specifically relate to this character, some characters make heavy use of this abstraction, Space Pirates being the biggest culprit.
|-
| [[#AnimationName|AnimationName]]
| animation_count
| Animation Names
| Animations linked to this character by name and index.
|-
| [[PASDatabase|PASDatabase]]
| 1
| Parameterized Animation State Data
| Not much is known about how this data is used.
|-
|-
| [[CMDL (Metroid Prime)|CMDL]]
| [[#ParticleResData|ParticleResData]]
| 1
| 1
| '''Model'''
| Particle systems used by this character
|
|-
|-
| [[CSKR (File Format)|CSKR]]
| u32
| 1
| colspan=2 {{unknown|'''Unknown'''}}
|-
| u32
| 1
| 1
| '''Skin'''
| {{unknown|'''Unknown'''}}
| Not present when info_type_count <= 9
|-
|-
| [[CINF (File Format)|CINF]]
| u32
| 1
| 1
| '''Skeleton'''
| {{unknown|'''Unknown'''}}
| Not present when info_type_count <= 9
|-
|-
| u32
| u32
| 1
| 1
| '''Animation count'''
| Animation AABB count
|}
| Only present when info_type_count > 1
 
|-
This struct then repeats ''animation count'' times:
| [[#AnimationAABB|AnimationAABB]]
 
| animation_aabb_count
{| class="wikitable"
| Animation bounds
! Type
| Only present when info_type_count > 1
! Count
|-
! Description
| u32
| 1
| Effect Count
| Only present when info_type_count > 1
|-
| [[#Effect|Effect]]
| effect_count
| Effects used by this character, including which bones they're attached to
| Only present when info_type_count > 1
|-
| [[CMDL_(Metroid_Prime)|CMDL]]
| 1
| Overlay Model for status effects, such as ice when frozen
| Only present when info_type_count > 3
|-
| [[CSKR_(File_Format)|CSKR]]
| 1
| Overlay Skin for status effects, such as ice when frozen
| Only present when info_type_count > 3
|-
| u32
| 1
| Animation Index Count
| The total number of animations used by this, only present when info_type_count > 4
|-
| u32
| animation_index_count
| Indices of each animation used by this character
| Only present when info_type_count > 4
|-
|-
| u32
| u32
| 1
| 1
| '''Animation number'''; starts with 0, increases by 1 on each subsequent animation
| {{unknown|'''Unknown'''}}
| Only present when info_type_count > 9
|-
|-
| u8
| u8
| 1
| 1
| {{unknown|'''Unknown'''; usually 0, only in Prime 1}}
| {{unknown|'''Unknown'''}}
| Only present when info_type_count > 9
|-
|-
| string
| u32
| 1
| 1
| '''Animation name''' (zero-terminated)
| Animation AABB Indexed Count
| Only present when info_type_count > 9
|-
| [[#AnimationAABB_Indexed|AnimationAABB]]
| animation_aabb_indexed_count
| Animation bounds, referenced by index
| Only present when info_type_count > 9
|}
|}


=== PAS Database ===
====AnimationName====
 
The next part of the file is the PAS Database, which creates animation states and sets parameters on them. The PAS Database header is structured:
 
{| class="wikitable"
{| class="wikitable"
! Offset
! Data Type
! Size
! Element Count
! Description
! Description
! Notes
|-
|-
| 0x0
| u32
| 4
| 1
| '''"PAS4" magic''' fourCC
| Index
| The index into AnimationSet's MetaAnimation table.
|-
|-
| 0x4
| string
| 4
| 1
| '''Anim state count'''
| {{unknown|'''Unknown'''}}
| Not present when info_type_count >= 10
|-
|-
| 0x8
| string
| 4
| 1
| '''Default state''' (will be 0xFFFFFFFF on files with no anim states)
| Animation Name
| The name of the index ref'd Animation
|}
|}


==== Anim State ====
===ParticleResData===
 
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Element Count
! Description
! Description
! Notes
|-
|-
| u32
| u32  
| 1
| 1
| {{unknown|'''Unknown'''}}
| [[PART_(File_Format)|PART]] count
| How many particle systems are used by this character
|-
| [[PART_(File_Format)|PART]]
| part_count
| The particle systems used by this character
|-
|-
| u32
| u32  
| 1
| 1
| '''Parm Info count''' (PC)
| [[SWHC_(File_Format)|SWHC]] count
| How many swooshes are used by this character
|-
|-
| u32
| [[SWHC_(File_Format)|SWHC]]
| swhc_count
| The swooshes used by this character
|-
| u32  
| 1
| 1
| '''Anim Info count''' (AC)
| {{unknown|'''Unknown Count'''}}
| How many unknown systems are used by this character
|-
| UniqueID32
| unknown_count
| The unknown systems used by this character
|-
|-
| [[#Parm Info|Parm Info]]
| u32
| PC
| 1
| '''Parm Info'''
| [[ELSC_(File_Format)|ELSC]] count
| How many electric systems are used by this character
|-
|-
| [[#Anim Info|Anim Info]]
| [[ELSC_(File_Format)|ELSC]]
| AC
| else_count
| '''Anim Info'''
| The electric systems used by this character
|}
|}


===== Parm Info =====
===AnimationAABB===
{| class="wikitable"
! Data Type
! Description
|-
| string
| Name
|-
| CAABox
| Animation bounds
|}


===Effect===
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Element Count
! Description
! Description
|-
|-
| u32
| string
| 1
| 1
| '''Parm Type'''; enum ranging from 0 to 4, see below for possible values
| Name
|-
|-
| u32
| u32
| 1
| 1
| {{unknown|'''Unknown'''}}
| Component Count
|-
| float
| 1
| {{unknown|'''Unknown'''}}
|-
|-
| ParmType
| [[#EffectComponent|EffectComponent]]
| 2
| component_count
| '''Parms'''
| Effect Components
|}
|}


These are the possible types that can be specified by Parm Type:
====EffectComponent====
 
{| class="wikitable"
{| class="wikitable"
! Value
! Data Type
! Size
! Description
! Type
|-
| string
| Name
|-
| FourCC
| Type
|-
|-
| 0
| UniqueID32
| 4
| Resource as defined by Type
| s32
|-
|-
| 1
| string
| 4
| Bone to attach the effect to
| u32
|-
|-
| 2
| 4
| float
| float
| {{unknown|'''Unknown'''}}
|-
|-
| 3
| u32
| 1
| {{unknown|'''Unknown'''}}
| bool
|-
|-
| 4
| u32
| 4
| {{unknown|'''Unknown'''}}
| enum
|}
|}


===== Anim Info =====
===AnimationAABB Indexed===
 
The only difference between this and the previous [[#AnimationAABB|AnimationAABB]] is the fact that animations are referenced by index, rather than by name.
The Anim Info structure is a little unorthodox. It starts with an unknown 32-bit value, and then is followed by a set of values. There's one value present per Parm Info instance, and the type of each value corresponds to that Parm Info's Parm Type setting.
 
=== Particles ===
 
Note: if the flag value at the start of the node is 5 instead of 6, one of these values is missing. It's currently not known specifically which one it toggles, so be careful. However if the value is 10 the data is from Metroid Prime 2 and special attention must be paid in order to properly read the information.


==AnimationSet==
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Element Count
! Description
! Description
! Notes
! Notes
|-
| u16
| 1
| Info Count
| Enumeration of the presence of certain sections
|-
|-
| u32
| u32
| 1
| 1
| '''Particle count''' (PC)
| Animation Count
|
| How many animations there are in the set
|-
|-
| [[PART (File Format)|PART]]
| [[#Animation|Animation]]
| PC
| animation_count
| '''Particle file IDs'''
| Animations that can be referenced by characters
|
|
|-
|-
| u32
| u32
| 1
| 1
| '''Swoosh particle count''' (SC)
| Transition Count
| How many transitions there are in the set
|-
| [[#Transition|Transition]]
| transition_count
| Transitions that can be referenced by characters
|
|
|-
|-
| [[SWHC (File Format)|SWHC]]
| [[#MetaTransition|MetaTransition]]
| SC
| 1
| '''Swoosh particle file IDs'''
| Default Transition
|
|
|-
|-
| u32
| u32
| 1
| 1
| Additive Animation Count
| How many additive animations there are
|-
| [[#AdditiveAnimation|AdditiveAnimation]]
| additive_animation_count
| Additive animations that can be referenced in some fashion
| Reference method is currently unknown, presumably PASDatabase.
|-
| float
| 1
| Time A
| {{unknown|'''Unknown'''}}
|-
| float
| 1
| Time B
| {{unknown|'''Unknown'''}}
| {{unknown|'''Unknown'''}}
|
|-
|-
| u32
| u32
| 1
| 1
| '''Electric particle count''' (EC)
| Half Transition Count
|
| How many half transitions there in the set, Only present if info_count > 2
|-
|-
| [[ELSC (File Format)|ELSC]]
| [[#HalfTransition|HalfTransition]]
| EC
| half_transition_Count
| '''Electric particle file IDs'''
| Half Transitions
|
| Only present if info_count > 2
|-
|-
| u32
| u32
| 1
| 1
| {{unknown|'''Unknown'''}}
| Animation Resource Count
|
| Only present if info_count > 3, and not present at all in MP2
|-
| [[#AnimationResource|AnimationResource]]
| animation_resource_count
| Animation Resources
| Only present if info_count > 3, and not present at all in MP2
|-
|-
| u32
| u32
| 1
| 1
| {{unknown|'''Unknown'''}}
| Event Count
| Only in Metroid Prime 2
| Only present in MP2
|-
|-
| u32
| [[EVNT_(File_Format)|EVNT]]
| 1
| event_count
| {{unknown|'''Unknown'''}}
| Animation Events
| Only in Metroid Prime 2
| Only present in MP2
|}
|}


=== Animations ===
===Animation===
 
This section begins with a 32-bit count value, then this struct repeats:
 
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Description
! Description
|-
|-
| string
| string
| 1
| Name
| '''Animation name'''
|-
|-
| float
| [[#MetaAnimation|MetaAnimation]]
| 6
| Animation configuration
| {{unknown|'''Unknown'''; possibly an AABB}}
|}
|}


=== Effects ===
===MetaAnimation===
MetaAnimations can be one of five types, and may contain children.
{| class="wikitable"
! Data Type
! Description
|-
| [[#EMetaAnimationType|EMetaAnimationType]]
| The Animation type
|-
| [[#Primitive|Primitive]], [[#Blend|Blend]], [[#Blend|PhaseBlend]], [[#Random|Random]] or [[#Sequence|Sequence]]
| The animation description, including name, animation ID, and index used to connect character animations references to actual animations.
|}


This section is used for effect placement - binding particles to bones, which is used for things like Space Pirate eye fire. It starts with a 32-bit count value, then this struct repeats:
====EMetaAnimationType====
{| class="wikitable"
! Name
! Value
|-
| Primitive
| 0
|-
| Blend
| 1
|-
| PhaseBlend
| 2
|-
| Random
| 3
|-
| Sequence
| 4
|}


====Primitive====
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Description
! Description
! Notes
! Notes
|-
| [[ANIM_(File_Format)|ANIM]]
| Animation ID
| The asset ID for this particular animation
|-
| u32
| Index
| The ID used by characters to reference this animation
|-
|-
| string
| string
| 1
| Name
| '''Effect name'''
| The animations name
|
|-
| float
| colspan=2 {{unknown|'''Unknown'''}}
|-
|-
| u32
| u32
| 1
| colspan=2 {{unknown|'''Unknown'''}}
| {{unknown|'''Unknown'''}}
|}
|
 
====Blend====
Blend's structure is shared between Blend and PhaseBlend, with the only currently known difference being the animation type value.
{| class="wikitable"
! Data Type
! Description
! Notes
|-
|-
| string
| [[#MetaAnimation|MetaAnimation]]
| 1
| Animation A
| '''Effect name 2'''
| The animation to, presumably, blend from
|  
|-
|-
| char
| [[#MetaAnimation|MetaAnimation]]
| 4
| Animation B
| '''"PART" fourCC'''
| The animation to, presumably, blend to
|
|-
|-
| [[PART (File Format)|PART]]
| float
| 1
| colspan=2 {{unknown|'''Unknown'''}}
| '''Particle file ID'''
|
|-
|-
| string
| bool
| 1
| colspan=2 {{unknown|'''Unknown'''}}
| '''Bone name'''
|}
| Metroid Prime 1 only
 
====Random====
Random may contain one or more children in an Animation -> Probability pair following this structure:
{| class="wikitable"
! Data Type
! Element Count
! Description
! Notes
|-
|-
| u32
| u32
| 1
| 1
| {{unknown|'''Unknown'''}}
| Animation Count
| Metroid Prime 2 only
| The number of child animations
|-
| [[#AnimProbabilityPair|AnimProbabilityPair]]
| animation_count
| The animations to select from
| The exact manner these are used is currently unknown
|}
 
=====AnimProbabilityPair=====
{| class="wikitable"
! Data Type
! Description
! Notes
|-
|-
| float
| [[#MetaAnimation|MetaAnimation]]
| 1
| The animation use if the probability factor is met
| {{unknown|'''Unknown'''}}
|
|
|-
|-
| u32
| u32
| 1
| Probability
| {{unknown|'''Unknown'''}}
| How probability is used is not currently known
|
|}
 
====Sequence====
Sequence is a fairly easy to understand type, it simply plays a list of animations in succession as each animation finishes
{| class="wikitable"
! Data Type
! Element Count
! Description
|-
|-
| u32
| u32
| 1
| 1
| {{unknown|'''Unknown'''}}
| Animation Count
|
|-
| [[#MetaAnimation|MetaAnimation]]
| animation_count
| The animations to play in a sequence
|}
|}


=== Footer ===
===Transition===
{| class="wikitable"
! Data Type
! Description
! Notes
|-
| u32
| Animation Index A
| The animation to transition from
|-
| u32
| Animation Index B
| The animation to transition to
|-
| [[#MetaTransition|MetaTransition]]
| Transition configuration
| Describes how the transition is performed
|}


The end of the node structure contains this data:
===MetaTransition===
Meta Transitions can be one of four types, and may contain animations.
{| class="wikitable"
! Data Type
! Description
|-
| [[#ETransitionType|EMetaTransitionType]]
| The type of transition
|-
| [[#TransAnimation|TransAnimation]], [[#TransTransition|TransTransition]], [[#TransTransition|TransPhaseTransition]], TransNoTransition
| The transition configuration
|}
====EMetaTransitionType====
{| class="wikitable"
! Name
! Value
|-
| TransAnimation
| 0
|-
| TransTransition
| 1
|-
| TransPhaseTransition
| 2
|-
| TransNoTransition
| 3
|}


====TransAnimation====
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Count
! Description
! Description
! Notes
|-
|-
| [[CMDL (Metroid Prime)|CMDL]]
| [[#MetaAnimation|MetaAnimation]]
| 1
| The animation to use while transitioning
| {{unknown|'''Unknown model'''}}
|}
|
 
====TransTransition====
{| class="wikitable"
! Data Type
! Description
|-
|-
| [[CSKR (Metroid Prime)|CSKR]]
| float
| 1
| Time
| {{unknown|'''Unknown skin'''}}
|
|-
|-
| u32
| u32
| 1
| {{unknown|'''Unknown'''}}
| ActionID Count (AC)
|-
|
| bool
| {{unknown|'''Unknown'''}}
|-
| bool
| {{unknown|'''Unknown'''}}
|-
|-
| u32
| u32
| AC
| {{unknown|'''Unknown'''}}
| Action IDs
|}
| Indices into the AnimationSet of used MetaAnimations.
 
===AdditiveAnimation===
Additive animations simply reference an existing animation within the above animation table, and has two unknown floats.
{| class="wikitable"
! Data Type
! Description
|-
|-
| u32
| u32
| 1
| Animation Index
|-
| float
| {{unknown|'''Unknown'''}}
| {{unknown|'''Unknown'''}}
| Only in Metroid Prime 2
|-
|-
| u8
| float
| 1
| {{unknown|'''Unknown'''}}
| {{unknown|'''Unknown bool?'''}}
| Only in Metroid prime 2
|}
|}


=== Metroid Prime 2 Unknown Struct ===
===Half Transition===
Immediately following the the footer is a second count/struct pair that only appears in Metroid Prime 2, it is currently unknown what purpose this serves. The count is a 32bit integer and is directly followed by an array of the following struct:
A half transition is very similar to a regular transition, but has less configuration information, any other differences are currently unknown
{| class="wikitable"
! Data Type
! Description
|-
| u32
| Animation Index
|-
| [[#MetaTransition|MetaTransition]]
| Transition configuration.
|}


===AnimationResource===
{| class="wikitable"
{| class="wikitable"
! Type
! Data Type
! Description
! Description
|-
|-
| u32
| UniqueID32
| '''Action ID'''
| Animation Asset ID
|-
|-
| CAABox
| UniqueID32
| {{unknown|'''Unknown'''}}
| Event Asset ID
|}
|}


Anonymous user