HedgeDocs - User contributions [en]

PXD

2026-03-03T05:05:38Z

AdelQue:

{{Notice|type=warn|content=This page is unfinished.}}

===== If you are looking for tools to edit <code>.pxd</code> files, see [[PXD Animation Tools|PXD Animation Tools.]] =====

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Tokyo 2020 Olympic Games|Tokyo 2020 Olympic Games]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S Tokyo 2020 Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component for translation and scale is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

==== Posing and Transform Inheritance: ====
Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

# Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind.
#* In Blender, a bone's scale inheritance mode can be changed from `Full` to `Aligned` to achieve this effect
# Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

'''Trivia''': ''The inheritance and relationships behavior for bone transform values have been found to be identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hka</code> functions.''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

== Thanks ==

* [https://github.com/Turk645 Turk645:] Original uncompressed PXD blender importer scripts
* [https://github.com/WistfulHopes WistfulHopes:] ACL tools, blender export scripts
* [https://github.com/ik-01 ik-01]: Format and game code research, filling in gaps for unknown values
* [https://github.com/AdelQue AdelQue:] Format research, math relations and bone inheritance behaviors
[[Category:File Formats]]

PXD Animation Tools

2026-03-03T04:52:07Z

AdelQue: Updated format and links

{{ToolInfobox|title=PXD Animation Tools|author=WistfulHopes, AdelQue, Turk645|website=https://github.com/WistfulHopes/FrontiersAnimDecompress|download=https://github.com/WistfulHopes/FrontiersAnimDecompress/releases/latest|image=FrontiersAnimDecompressPreview.gif}}

[https://github.com/WistfulHopes/PXDAnimationTools PXD Animations Tools] (formerly known as "FrontiersAnimDecompress" and "Frontiers Animation Tools") is a [https://www.blender.org/ Blender] add-on for importing and exporting animation [[PXD|<code>.anm.pxd</code>]] and skeleton [[PXD|<code>.skl.pxd</code>]] files from various Hedgehog Engine 2 games. The tool officially supports most Hedgehog Engine 2 titles including [[Mario & Sonic at the Tokyo 2020 Olympic Games]], [[Sonic Origins]], [[Sonic Frontiers]], and [[Shadow Generations]].

The add-on can currently perform compressed/uncompressed batch animation imports, compressed batch animation exports, skeleton reorientation, and officially supports Blender versions from 3.6 to 4.5 (as a legacy add-on in 4.2+). The add-on is Windows-only as it uses a DLL for [https://github.com/nfrechette/acl ACL] compression and decompression.

More technical info about the supported file formats can be found on the [[PXD|dedicated PXD page.]]

== Downloads ==
The latest version of the tool at any point can be found [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ here.] The add-on should be installed as a zip file without extraction.

== Usage ==

====== A guide for animation editing using this tool can be found in [[Skeletal Animation Editing|Guide:Skeletal Animation Editing]]. ======

=== Text Overview: ===
A skeleton needs to be imported into the scene, and this skeleton must be selected in the viewport in order to import or export an animation. The add-on currently only reads bone indices from the animation file, so an animation can only be imported over the skeleton that it was originally made for. Batch functions can be found in the right ribbon of the viewport's sidebar, in the "PXD Animation" category under the "Animation" tab.

As long as all the bones' scale inheritance mode in your skeleton is set to "Aligned", and any targets for scale-modifying constraints follow the same inheritance mode, the skeleton should generally export exactly as you see in the viewport.

Per-animation settings (such as FPS and frame range) can be found in the "Action Editor" under the Dope Sheet editor. PXD specific settings may currently not show up for any animation that wasn't imported, or duplicated off of an imported animation.

When exporting custom skeletons, ensure that all bone names only contain alphanumeric characters. With the exception of underscores "_", any special characters (such as "." commonly auto-added to many duplicated resources in Blender) in bone names may cause a crash in-game upon loading.

In order to have a default game skeleton support mirroring in Blender, a skeleton must be imported using YX orientation (a togglable option in all import/export dialogues). If the skeleton is imported with this setting, all subsequent import/export operations from this add-on must enable YX orientation as well. If it is not properly called out, results in-game will not turn out as expected.

During batch operations, Blender may freeze and become unresponsive. The external Blender console window can (and should) be open so you may view a readout of the import progress instead of assuming the program is crashing. It is not recommended to batch imports hundreds of animations at a time. Depending on your hardware, you may want to play with a group of about 50 at a time or maybe up to 200 if you have a higher end system.

== History: ==
The PXD formats were first supported by Blender add-on scripts that allowed model importing and skeleton importing for the files first found in the 2020 Olympic game in Blender 2.82.<ref>https://github.com/Turk645/Hedgehog-Engine-2-Mesh-Blender-Importer</ref>

From Origins onward, animation data was identified to be compressed by ACL. An application called "FrontiersAnimDecompress.exe" was later created, which was used to dump decompressed track data (labeled as <code>.outanim</code> files) from these newly compressed formats.<ref>https://github.com/WistfulHopes/PXDAnimationTools/tree/c835209172b14468a07e5cae75d05fd4a595e35e</ref> Included with the app were supplemental Blender scripts for importing from the dumped track data (modified from Turk645's original scripts), as well as custom scripts for exporting custom skeletons and raw track data that could later be recompressed.

The application was eventually modified into a DLL, and supplemental scripts were rewritten as one packaged add-on, so standalone conversion was no longer necessary.<ref>https://github.com/AdelQue/FrontiersAnimDecompress/releases/tag/v2.0.0</ref> Notable additions included batch processing, corrected scaling, skeleton reorientation for mirror support, and root motion.

Handling of raw track data was recently found to be identical across all Hedgehog Engine titles. The method in this add-on to achieve correct scaling can be reused for other Hedgehog Engine games stored in Havok animation formats.

This page was last edited on 11 January

[[Category:Animation]]

Skeletal Animation Editing

2026-03-03T04:46:42Z

AdelQue: Added Video

This page is an introductory page that will describe how to edit skeletal animations from Hedgehog Engine 2 games that utilize the <code>.pxd</code> file formats.

== Video Tutorial ==

=== Getting Started + Basic Animation Import + Export ===
<youtube>https://youtu.be/sVKX8YvePZY</youtube>

== Written Tutorial ==
''NOTE: Work in progress!''

=== Required Tools ===

* [https://www.blender.org/ Blender]

* [https://github.com/WistfulHopes/FrontiersAnimDecompress/ PXD Animation Tools add-on for Blender]
* [https://hedge-dev.github.io/HedgehogEngineBlenderIO/index.html Hedgehog Engine I/O extension for Blender] (for having a model to animate with)

=== Installation ===

==== Blender ====

* Download and run the setup executable of the latest supported version of Blender (version 4.5 as of this wiki page) from either the [https://www.blender.org/download/ official site] or from the [https://store.steampowered.com/app/365670/Blender/ official Steam page] if you'd like to stay automatically updated.

==== PXD Animation Tools ====

* Download <code>PXDAnimationTools.zip</code> from the tool's [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ latest GitHub release page.]

* Run Blender.
* In the upper left corner, navigate to <code>Edit > Preferences...</code>
* On the left pane of the preferences window, select the <code>Add-ons</code> tab.
* In the upper-right side of the window, select the <code>v</code> shaped drop-down button, then select <code>Install from disk...</code>
* Navigate to and select the downloaded <code>PXDAnimationTools.zip</code> file, then click the <code>Install from Disk</code> button.
* You should now see an add-on entry for <code>Hedgehog Engine PXD Animation Tools</code> with a ticked checkbox to the left.
* The tool is now installed, and the preferences window may now be closed.

==== Hedgehog Engine I/O ====

* Please see the [https://hedge-dev.github.io/HedgehogEngineBlenderIO/getting_started/installation.html#installing-the-addon dedicated installation page for HEIO.]

{{DEFAULTSORT:PXD Animation Editing}}

PXD Animation Tools

2026-03-02T02:30:58Z

AdelQue: Updated Title

{{ToolInfobox|title=PXD Animation Tools|author=WistfulHopes, AdelQue, Turk645|website=https://github.com/WistfulHopes/FrontiersAnimDecompress|download=https://github.com/WistfulHopes/FrontiersAnimDecompress/releases/latest|image=FrontiersAnimDecompressPreview.gif}}

[https://github.com/WistfulHopes/PXDAnimationTools PXD Animations Tools] (formerly known as "FrontiersAnimDecompress" and "Frontiers Animation Tools") is a [https://www.blender.org/ Blender] add-on for importing and exporting animation ([[PXD|*.anm.pxd]]) and skeleton ([[PXD|*.skl.pxd]]) files from various Hedgehog Engine 2 games. The tool officially supports most Hedgehog Engine 2 titles including [[Mario & Sonic at the Tokyo 2020 Olympic Games]], [[Sonic Origins]], [[Sonic Frontiers]], and [[Shadow Generations]].

The add-on can currently perform compressed/uncompressed batch animation imports, compressed batch animation exports, skeleton reorientation, and officially supports Blender versions from 3.6 to 4.5 (as a legacy add-on in 4.2+). The add-on is Windows-only as it uses a DLL for [https://github.com/nfrechette/acl ACL] compression and decompression.

== Downloads ==
The latest version of the tool at any point can be found [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ here.] The add-on should be installed as a zip file without extraction.

== Usage ==

=== Video: ===
A video tutorial for basic usage of the add-on can be found [https://youtu.be/sVKX8YvePZY here.]

=== Text Overview: ===
A skeleton needs to be imported into the scene, and this skeleton must be selected in the viewport in order to import or export an animation. The add-on currently only reads bone indices from the animation file, so an animation can only be imported over the skeleton that it was originally made for. Batch functions can be found in the right ribbon of the viewport's sidebar, in the "PXD Animation" category under the "Animation" tab.

As long as all the bones' scale inheritance mode in your skeleton is set to "Aligned", and any targets for scale-modifying constraints follow the same inheritance mode, the skeleton should generally export exactly as you see in the viewport.

Per-animation settings (such as FPS and frame range) can be found in the "Action Editor" under the Dope Sheet editor. PXD specific settings may currently not show up for any animation that wasn't imported, or duplicated off of an imported animation.

When exporting custom skeletons, ensure that all bone names only contain alphanumeric characters. With the exception of underscores "_", any special characters (such as "." commonly auto-added to many duplicated resources in Blender) in bone names may cause a crash in-game upon loading.

In order to have a default game skeleton support mirroring in Blender, a skeleton must be imported using YX orientation (a togglable option in all import/export dialogues). If the skeleton is imported with this setting, all subsequent import/export operations from this add-on must enable YX orientation as well. If it is not properly called out, results in-game will not turn out as expected.

During batch operations, Blender may freeze and become unresponsive. The external Blender console window can (and should) be open so you may view a readout of the import progress instead of assuming the program is crashing. It is not recommended to batch imports hundreds of animations at a time. Depending on your hardware, you may want to play with a group of about 50 at a time or maybe up to 200 if you have a higher end system.

== History: ==
The PXD formats were first supported by Blender add-on scripts that allowed model importing and skeleton importing for the files first found in the 2020 Olympic game in Blender 2.82.<ref>https://github.com/Turk645/Hedgehog-Engine-2-Mesh-Blender-Importer</ref>

From Origins onward, animation data was identified to be compressed by ACL. An application called "FrontiersAnimDecompress.exe" was later created, which was used to dump decompressed track data (labeled as *.outanim files) from these newly compressed formats.<ref>https://github.com/WistfulHopes/PXDAnimationTools/tree/c835209172b14468a07e5cae75d05fd4a595e35e</ref> Included with the app were supplemental Blender scripts for importing from the dumped track data (modified from Turk645's original scripts), as well as custom scripts for exporting custom skeletons and raw track data that could later be recompressed.

The application was eventually modified into a DLL, and supplemental scripts were rewritten as one packaged add-on, so standalone conversion was no longer necessary.<ref>https://github.com/AdelQue/FrontiersAnimDecompress/releases/tag/v2.0.0</ref> Notable additions included batch processing, corrected scaling, skeleton reorientation for mirror support, and root motion.

Handling of raw track data was recently found to be identical across all Hedgehog Engine titles. The method in this add-on to achieve correct scaling can be reused for other Hedgehog Engine games stored in Havok animation formats.

This page was last edited on 11 January

[[Category:Animation]]

Frontiers Animation Tools

2026-03-02T02:30:02Z

AdelQue: AdelQue moved page Frontiers Animation Tools to PXD Animation Tools over redirect: Tool Name Changed

#REDIRECT [[PXD Animation Tools]]

PXD Animation Tools

2026-03-02T02:30:02Z

AdelQue: AdelQue moved page Frontiers Animation Tools to PXD Animation Tools over redirect: Tool Name Changed

{{DISPLAYTITLE:PXD Animation Tools}}

= PXD Animation Tools =
{{ToolInfobox|title=PXD Animation Tools|author=WistfulHopes, AdelQue, Turk645|website=https://github.com/WistfulHopes/FrontiersAnimDecompress|download=https://github.com/WistfulHopes/FrontiersAnimDecompress/releases/latest|image=FrontiersAnimDecompressPreview.gif}}

[https://github.com/WistfulHopes/PXDAnimationTools PXD Animations Tools] (formerly known as "FrontiersAnimDecompress" and "Frontiers Animation Tools") is a [https://www.blender.org/ Blender] add-on for importing and exporting animation ([[PXD|*.anm.pxd]]) and skeleton ([[PXD|*.skl.pxd]]) files from various Hedgehog Engine 2 games. The tool officially supports most Hedgehog Engine 2 titles including [[Mario & Sonic at the Tokyo 2020 Olympic Games]], [[Sonic Origins]], [[Sonic Frontiers]], and [[Shadow Generations]].

The add-on can currently perform compressed/uncompressed batch animation imports, compressed batch animation exports, skeleton reorientation, and officially supports Blender versions from 3.6 to 4.5 (as a legacy add-on in 4.2+). The add-on is Windows-only as it uses a DLL for [https://github.com/nfrechette/acl ACL] compression and decompression.

== Downloads ==
The latest version of the tool at any point can be found [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ here.] The add-on should be installed as a zip file without extraction.

== Usage ==

=== Video: ===
A video tutorial for basic usage of the add-on can be found [https://youtu.be/sVKX8YvePZY here.]

=== Text Overview: ===
A skeleton needs to be imported into the scene, and this skeleton must be selected in the viewport in order to import or export an animation. The add-on currently only reads bone indices from the animation file, so an animation can only be imported over the skeleton that it was originally made for. Batch functions can be found in the right ribbon of the viewport's sidebar, in the "PXD Animation" category under the "Animation" tab.

As long as all the bones' scale inheritance mode in your skeleton is set to "Aligned", and any targets for scale-modifying constraints follow the same inheritance mode, the skeleton should generally export exactly as you see in the viewport.

Per-animation settings (such as FPS and frame range) can be found in the "Action Editor" under the Dope Sheet editor. PXD specific settings may currently not show up for any animation that wasn't imported, or duplicated off of an imported animation.

When exporting custom skeletons, ensure that all bone names only contain alphanumeric characters. With the exception of underscores "_", any special characters (such as "." commonly auto-added to many duplicated resources in Blender) in bone names may cause a crash in-game upon loading.

In order to have a default game skeleton support mirroring in Blender, a skeleton must be imported using YX orientation (a togglable option in all import/export dialogues). If the skeleton is imported with this setting, all subsequent import/export operations from this add-on must enable YX orientation as well. If it is not properly called out, results in-game will not turn out as expected.

During batch operations, Blender may freeze and become unresponsive. The external Blender console window can (and should) be open so you may view a readout of the import progress instead of assuming the program is crashing. It is not recommended to batch imports hundreds of animations at a time. Depending on your hardware, you may want to play with a group of about 50 at a time or maybe up to 200 if you have a higher end system.

== History: ==
The PXD formats were first supported by Blender add-on scripts that allowed model importing and skeleton importing for the files first found in the 2020 Olympic game in Blender 2.82.<ref>https://github.com/Turk645/Hedgehog-Engine-2-Mesh-Blender-Importer</ref>

From Origins onward, animation data was identified to be compressed by ACL. An application called "FrontiersAnimDecompress.exe" was later created, which was used to dump decompressed track data (labeled as *.outanim files) from these newly compressed formats.<ref>https://github.com/WistfulHopes/PXDAnimationTools/tree/c835209172b14468a07e5cae75d05fd4a595e35e</ref> Included with the app were supplemental Blender scripts for importing from the dumped track data (modified from Turk645's original scripts), as well as custom scripts for exporting custom skeletons and raw track data that could later be recompressed.

The application was eventually modified into a DLL, and supplemental scripts were rewritten as one packaged add-on, so standalone conversion was no longer necessary.<ref>https://github.com/AdelQue/FrontiersAnimDecompress/releases/tag/v2.0.0</ref> Notable additions included batch processing, corrected scaling, skeleton reorientation for mirror support, and root motion.

Handling of raw track data was recently found to be identical across all Hedgehog Engine titles. The method in this add-on to achieve correct scaling can be reused for other Hedgehog Engine games stored in Havok animation formats.

This page was last edited on 11 January

[[Category:Animation]]

PXD Animation Tools

2026-03-02T02:21:57Z

AdelQue: Updated Page Title

PXD Animation Tools

2026-03-02T02:20:24Z

AdelQue: More stuff

= PXD Animation Tools =
{{ToolInfobox|title=PXD Animation Tools|author=WistfulHopes, AdelQue, Turk645|website=https://github.com/WistfulHopes/FrontiersAnimDecompress|download=https://github.com/WistfulHopes/FrontiersAnimDecompress/releases/latest|image=FrontiersAnimDecompressPreview.gif}}

[https://github.com/WistfulHopes/PXDAnimationTools PXD Animations Tools] (formerly known as "FrontiersAnimDecompress" and "Frontiers Animation Tools") is a [https://www.blender.org/ Blender] add-on for importing and exporting animation ([[PXD|*.anm.pxd]]) and skeleton ([[PXD|*.skl.pxd]]) files from various Hedgehog Engine 2 games. The tool officially supports most Hedgehog Engine 2 titles including [[Mario & Sonic at the Tokyo 2020 Olympic Games]], [[Sonic Origins]], [[Sonic Frontiers]], and [[Shadow Generations]].

The add-on can currently perform compressed/uncompressed batch animation imports, compressed batch animation exports, skeleton reorientation, and officially supports Blender versions from 3.6 to 4.5 (as a legacy add-on in 4.2+). The add-on is Windows-only as it uses a DLL for [https://github.com/nfrechette/acl ACL] compression and decompression.

== Downloads ==
The latest version of the tool at any point can be found [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ here.] The add-on should be installed as a zip file without extraction.

== Usage ==

=== Video: ===
A video tutorial for basic usage of the add-on can be found [https://youtu.be/sVKX8YvePZY here.]

=== Text Overview: ===
A skeleton needs to be imported into the scene, and this skeleton must be selected in the viewport in order to import or export an animation. The add-on currently only reads bone indices from the animation file, so an animation can only be imported over the skeleton that it was originally made for. Batch functions can be found in the right ribbon of the viewport's sidebar, in the "PXD Animation" category under the "Animation" tab.

As long as all the bones' scale inheritance mode in your skeleton is set to "Aligned", and any targets for scale-modifying constraints follow the same inheritance mode, the skeleton should generally export exactly as you see in the viewport.

Per-animation settings (such as FPS and frame range) can be found in the "Action Editor" under the Dope Sheet editor. PXD specific settings may currently not show up for any animation that wasn't imported, or duplicated off of an imported animation.

When exporting custom skeletons, ensure that all bone names only contain alphanumeric characters. With the exception of underscores "_", any special characters (such as "." commonly auto-added to many duplicated resources in Blender) in bone names may cause a crash in-game upon loading.

In order to have a default game skeleton support mirroring in Blender, a skeleton must be imported using YX orientation (a togglable option in all import/export dialogues). If the skeleton is imported with this setting, all subsequent import/export operations from this add-on must enable YX orientation as well. If it is not properly called out, results in-game will not turn out as expected.

During batch operations, Blender may freeze and become unresponsive. The external Blender console window can (and should) be open so you may view a readout of the import progress instead of assuming the program is crashing. It is not recommended to batch imports hundreds of animations at a time. Depending on your hardware, you may want to play with a group of about 50 at a time or maybe up to 200 if you have a higher end system.

== History: ==
The PXD formats were first supported by Blender add-on scripts that allowed model importing and skeleton importing for the files first found in the 2020 Olympic game in Blender 2.82.<ref>https://github.com/Turk645/Hedgehog-Engine-2-Mesh-Blender-Importer</ref>

From Origins onward, animation data was identified to be compressed by ACL. An application called "FrontiersAnimDecompress.exe" was later created, which was used to dump decompressed track data (labeled as *.outanim files) from these newly compressed formats.<ref>https://github.com/WistfulHopes/PXDAnimationTools/tree/c835209172b14468a07e5cae75d05fd4a595e35e</ref> Included with the app were supplemental Blender scripts for importing from the dumped track data (modified from Turk645's original scripts), as well as custom scripts for exporting custom skeletons and raw track data that could later be recompressed.

The application was eventually modified into a DLL, and supplemental scripts were rewritten as one packaged add-on, so standalone conversion was no longer necessary.<ref>https://github.com/AdelQue/FrontiersAnimDecompress/releases/tag/v2.0.0</ref> Notable additions included batch processing, corrected scaling, skeleton reorientation for mirror support, and root motion.

Handling of raw track data was recently found to be identical across all Hedgehog Engine titles. The method in this add-on to achieve correct scaling can be reused for other Hedgehog Engine games stored in Havok animation formats.

This page was last edited on 11 January

[[Category:Animation]]

Skeletal Animation Editing

2025-06-04T02:59:47Z

AdelQue:

This page is an introductory page that will describe how to edit skeletal animations from Hedgehog Engine 2 games that utilize the <code>.pxd</code> file formats.

=== Required Tools ===

* [https://www.blender.org/ Blender]

* [https://github.com/WistfulHopes/FrontiersAnimDecompress/ PXD Animation Tools add-on for Blender]
* [https://hedge-dev.github.io/HedgehogEngineBlenderIO/index.html Hedgehog Engine I/O extension for Blender] (for having a model to animate with)

=== Installation ===

==== Blender ====

* Download and run the setup executable of the latest supported version of Blender (version 4.4.x as of this wiki page) from either the [https://www.blender.org/download/ official site] or from the [https://store.steampowered.com/app/365670/Blender/ official Steam page] if you'd like to stay automatically updated.

==== PXD Animation Tools ====

* Download <code>PXDAnimationTools.zip</code> from the tool's [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ latest GitHub release page.]

* Run Blender.
* In the upper left corner, navigate to <code>Edit > Preferences...</code>
* On the left pane of the preferences window, select the <code>Add-ons</code> tab.
* In the upper-right side of the window, select the <code>v</code> shaped drop-down button, then select <code>Install from disk...</code>
* Navigate to and select the downloaded <code>PXDAnimationTools.zip</code> file, then click the <code>Install from Disk</code> button.
* You should now see an add-on entry for <code>Hedgehog Engine PXD Animation Tools</code> with a ticked checkbox to the left.
* The tool is now installed, and the preferences window may now be closed.

==== Hedgehog Engine I/O ====

* Please see the [https://hedge-dev.github.io/HedgehogEngineBlenderIO/getting_started/installation.html#installing-the-addon dedicated installation page for HEIO.]

{{DEFAULTSORT:PXD Animation Editing}}

Skeletal Animation Editing

2025-06-04T02:59:37Z

AdelQue:

This page is an introductory page that will describe how to edit skeletal animations from Hedgehog Engine 2 games that utilize the <code>.pxd</code> file formats.

=== Required Tools: ===

* [https://www.blender.org/ Blender]

* [https://github.com/WistfulHopes/FrontiersAnimDecompress/ PXD Animation Tools add-on for Blender]
* [https://hedge-dev.github.io/HedgehogEngineBlenderIO/index.html Hedgehog Engine I/O extension for Blender] (for having a model to animate with)

=== Installation ===

==== Blender ====

* Download and run the setup executable of the latest supported version of Blender (version 4.4.x as of this wiki page) from either the [https://www.blender.org/download/ official site] or from the [https://store.steampowered.com/app/365670/Blender/ official Steam page] if you'd like to stay automatically updated.

==== PXD Animation Tools ====

* Download <code>PXDAnimationTools.zip</code> from the tool's [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ latest GitHub release page.]

* Run Blender.
* In the upper left corner, navigate to <code>Edit > Preferences...</code>
* On the left pane of the preferences window, select the <code>Add-ons</code> tab.
* In the upper-right side of the window, select the <code>v</code> shaped drop-down button, then select <code>Install from disk...</code>
* Navigate to and select the downloaded <code>PXDAnimationTools.zip</code> file, then click the <code>Install from Disk</code> button.
* You should now see an add-on entry for <code>Hedgehog Engine PXD Animation Tools</code> with a ticked checkbox to the left.
* The tool is now installed, and the preferences window may now be closed.

==== Hedgehog Engine I/O ====

* Please see the [https://hedge-dev.github.io/HedgehogEngineBlenderIO/getting_started/installation.html#installing-the-addon dedicated installation page for HEIO.]

{{DEFAULTSORT:PXD Animation Editing}}

Skeletal Animation Editing

2025-06-04T02:59:13Z

AdelQue: Created page with "This page is an introductory page that will describe how to edit skeletal animations from Hedgehog Engine 2 games that utilize the <code>.pxd</code> file formats. === Required Tools: === * [https://www.blender.org/ Blender] * [https://github.com/WistfulHopes/FrontiersAnimDecompress/ PXD Animation Tools add-on for Blender] * [https://hedge-dev.github.io/HedgehogEngineBlenderIO/index.html Hedgehog Engine I/O extension for Blender] (for having a model to animate..."

This page is an introductory page that will describe how to edit skeletal animations from Hedgehog Engine 2 games that utilize the <code>.pxd</code> file formats.

=== Required Tools: ===

* [https://www.blender.org/ Blender]

* [https://github.com/WistfulHopes/FrontiersAnimDecompress/ PXD Animation Tools add-on for Blender]
* [https://hedge-dev.github.io/HedgehogEngineBlenderIO/index.html Hedgehog Engine I/O extension for Blender] (for having a model to animate with)

=== Installation: ===

==== Blender: ====

* Download and run the setup executable of the latest supported version of Blender (version 4.4.x as of this wiki page) from either the [https://www.blender.org/download/ official site] or from the [https://store.steampowered.com/app/365670/Blender/ official Steam page] if you'd like to stay automatically updated.

==== PXD Animation Tools: ====

* Download <code>PXDAnimationTools.zip</code> from the tool's [https://github.com/WistfulHopes/PXDAnimationTools/releases/latest/ latest GitHub release page.]

* Run Blender.
* In the upper left corner, navigate to <code>Edit > Preferences...</code>
* On the left pane of the preferences window, select the <code>Add-ons</code> tab.
* In the upper-right side of the window, select the <code>v</code> shaped drop-down button, then select <code>Install from disk...</code>
* Navigate to and select the downloaded <code>PXDAnimationTools.zip</code> file, then click the <code>Install from Disk</code> button.
* You should now see an add-on entry for <code>Hedgehog Engine PXD Animation Tools</code> with a ticked checkbox to the left.
* The tool is now installed, and the preferences window may now be closed.

==== Hedgehog Engine I/O: ====

* Please see the [https://hedge-dev.github.io/HedgehogEngineBlenderIO/getting_started/installation.html#installing-the-addon dedicated installation page for HEIO.]

{{DEFAULTSORT:PXD Animation Editing}}

Sonic Frontiers

2025-06-04T02:30:48Z

AdelQue:

== Tools ==

=== Animation ===
* [[Frontiers Animation Tools]]

== Guides ==

=== Animation ===

* [[Skeletal Animation Editing|Skeletal Animation Editing: Introduction]]

== Documentation ==

=== Game ===
* [[Sonic Frontiers DLCs|DLCs]]
* [[Sonic Frontiers Stage IDs|Stage IDs]]
* [[Sonic Frontiers Enemy Internal Names|Enemy Internal Names]]
* [[Sonic Frontiers Script Functions|Script Functions]]

=== File Formats ===
* [[Sonic Frontiers RFL|Reflection Data]] (.rfl)

=== Objects ===
* [[Sonic Frontiers Gismos|Gismos]]

== Discoveries ==
N/A

PXD

2025-04-16T23:55:48Z

AdelQue: Corrected Olympic game

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Tokyo 2020 Olympic Games|Tokyo 2020 Olympic Games]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S Tokyo 2020 Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component for translation and scale is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

==== Posing and Transform Inheritance: ====
Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

# Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind.
#* In Blender, a bone's scale inheritance mode can be changed from `Full` to `Aligned` to achieve this effect
# Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

'''Trivia''': ''The inheritance and relationships behavior for bone transform values have been found to be identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hka</code> functions.''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

== Thanks ==

* [https://github.com/Turk645 Turk645:] Original uncompressed PXD blender importer scripts
* [https://github.com/WistfulHopes WistfulHopes:] ACL tools, blender export scripts
* [https://github.com/ik-01 ik-01]: Format and game code research, filling in gaps for unknown values
* [https://github.com/AdelQue AdelQue:] Format research, math relations and bone inheritance behaviors
[[Category:File Formats]]

PBA

2025-04-12T07:54:06Z

AdelQue:

{{Notice|type=warn|content=WIP Page, just adding to start}}
[[File:PBA cloth demonstration.gif|alt=Depicted in Blender using built-in cloth simulation, and bones constrained to corresponding vertex group|thumb|<code>chr_sage.pba</code> contains a node for a cloth mesh made up of only vertices and edges, interconnected in such a way to maintain shape with internal springs|325x325px]]
Physics Based Animation ( <code>.pba</code> ) files are bone physics files first found in [[Sonic Frontiers]], and first regularly used in [[Shadow Generations|Shadow Generations.]] The system is capable of using bouncy bones/jiggle physics, rag-doll physics, and cloth simulation. The format is still relatively unknown and has only been brute forced through hex analysis more than code analysis, and there are unfortunately not many examples files to reference.

{| class="wikitable mw-collapsible"
|+List of known PBA file examples
!Game
!Filename
!Description
!Notes
|-
|rangers
|<code>chr_big.pba</code>
|Big's fishing line and lure
|Unused
|-
|rangers
|<code>chr_knucklesdrill.pba</code>
|Knuckles' drill tail
|Unused
|-
|rangers
|<code>chr_kodama01.pba</code>
|Plant toppers on Koco variants
|Unused
|-
|rangers
|<code>chr_sage.pba</code>
|Dress cloth physics and self collisions with legs
|Unused. This is the only known file with a cloth node, and unknown if self collisions were ever in a working state when ported to Shadow Generations
|-
|rangers
|<code>enm_wolf01.pba</code>
|Wolf tail
|Unused
|-
|rangers
|<code>mbo_tracker01.pba</code>
|Tracker's brain stem
|Only used PBA file in Frontiers
|-
|miller
|<code>bos_metaloverload.pba</code>
|Metal Overlord's pipes/tubes
|
|-
|miller
|<code>chr_big.pba</code>
|Big's fishing line, hook and lure
|Has collision and more bones than Frontiers version
|-
|miller
|<code>chr_shadow.pba</code>
|Shadow's head quills
|
|-
|miller
|<code>chr_shadow_dameba.pba</code>
|Ameba Doom Morph's tentacles and legs
|
|-
|miller
|<code>chr_shadow_dwing.pba</code>
|Doom Wings entirety
|
|-
|miller
|<code>chr_terios.pba</code>
|Terios's head quills
|
|}

== Binary Structure ==
TODO: Decipher, clean up, explain 0_0 might have lots of wrong info!<syntaxhighlight lang="c++">
//------------------------------------------------
//--- 010 Editor v12.0.1 Binary Template
//
// File:
// Authors: Ashrindy, AdelQ
// Version: 0.0.1
// Purpose: Shadow Gens PhysicalSkeleton
// Category:
// File Mask: *.pba
// ID Bytes:
// History:
//------------------------------------------------

#include "../include.h"

local uint64 dataPos;

typedef struct{
Vector4 rows[4];
}Matrix4x4<optimize=false>;

typedef struct{
byte UnkB1; // Always 2 or 1, unknown flag
byte UnkB2; // Always 0 or 1, unknown flag
byte UnkB3[2]; // Padding?
float Unk_f[4]; // Upper/Lower limits of something?
}LimitsStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
int unk; // if this is related to collision, this could be an enum for the collision shape
float unk2; // Physics dampening? Lower values make bones wobble for longer
Matrix4x4 mat; // Most likely not a matrix, has parameters that affect gravity, stretch, etc, and possibly capsule/collision bounds(?) but still working through
}CollisionStruct<optimize=false>; // Has params that affect physics intensity still, maybe general physics

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
byte Unk1[4]; // All known examples are 01 01 14 00. could be bitflags by the looks of it
int16 LocalParentBoneIndex; // FF FF if no bone parent
int16 LocalBoneIndex;
int16 RealParentBoneIndex; // Usually the parent of this bone on the real skeleton, but can be any bone in practice. Perhaps a reference for the offset transform?
int16 Unk3;
LimitsStruct Limits[6]; // Unknown what these limits line up to (Pos to Neg X, Pos to Neg Y, etc)
float Unk4<hidden=true>; // Align
Matrix4x4 mat; // Possibly bone offset matrix relative to RealParentBoneIndex? A: Two quaternions in row 2 and 4?
}
JiggleStruct<optimize=false>; // Handles bone chain relations for bendy/jiggle physics, as well as presumably transform limits

typedef struct{
// Starting point needs to align to 16 bytes
local uint64 CurPos = FTell();
local uint64 AlignCheck = CurPos % 0x10;
if (AlignCheck)
FSeek(CurPos + 0x10 - AlignCheck);
SetRandomBackColor();
StringOffset BoneName;
float unk0; // All known examples = 0.01
int16 unk1<hidden=true>; // Always FF FF
int16 if_pinned; // 1 if no parent present. Possibly this bone controls corresponding vertex if 1, versus vertex controls cooresponding bone if 0
int16 child_idx; // FF if no child
int16 parent_idx; // FF if no parent
int16 unk2[2]<hidden=true>; // Always FF FF
int16 left_idx;
int16 right_idx;
}cloth_node<optimize=false>; // Defines up to 4 neighboring bones in a cloth bone grid

typedef struct{
SetRandomBackColor();
int16 verts[2];
float edge_length;
float unk_factor; // Normalized, lateral direct connections = 0.5, lateral skip connections = 0.3, vertical direct connections = 1.0. Maybe a stretch/shrink factor?
}cloth_edges<optimize=false>; // Cloth sim edge mesh

typedef struct{
SetRandomBackColor();
StringOffset cloth_name;
float unk1[10];
int16 unk_count1[2];
int32 cloth_node_count;
int32 cloth_edge_count;
int32 unk3<hidden=true>; // Align
int64 cloth_node_ptr;
int64 cloth_edge_ptr;
local int64 prePos = FTell();
FSeek(cloth_node_ptr + dataPos);
cloth_node bones[cloth_node_count];
FSeek(cloth_edge_ptr + dataPos);
cloth_edges edges[cloth_edge_count];
FSeek(prePos);
}ClothStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
char signature[4]<name="Signature">;
int version <format=hex, name="Version">;
StringOffset SkeletonName;
uint32 CollisionCount;
uint32 JiggleCount;
uint64 CollisionOffset;
uint64 JiggleOffset;
uint32 ClothCount;
uint32 UnkCount;
uint64 ClothOffset;
uint64 UnkOffset;
FSeek(CollisionOffset + dataPos);
CollisionStruct CollisionStructs[CollisionCount];
FSeek(JiggleOffset + dataPos);
JiggleStruct JiggleStructs[JiggleCount];
FSeek(ClothOffset + dataPos);
ClothStruct ClothStructs[ClothCount];
}
ResPhysicalSkeleton<open=true>;

ResBinaryFile file("ResPhysicalSkeleton")<name=Str("%s", FileNameGetBase(GetFileName()))>;
</syntaxhighlight>

PBA

2025-04-12T07:53:31Z

AdelQue:

{{Notice|type=warn|content=WIP Page, just adding to start}}
[[File:PBA cloth demonstration.gif|alt=Depicted in Blender using built-in cloth simulation, and bones constrained to corresponding vertex group|thumb|<code>chr_sage.pba</code> contains a node for a cloth mesh made up of only vertices and edges, interconnected in such a way to maintain shape with internal springs|325x325px]]
Physics Based Animation ( <code>.pba</code> ) files are bone physics files first found in [[Sonic Frontiers]], and first regularly used in [[Shadow Generations|Shadow Generations.]] The system is capable of using bouncy bones/jiggle physics, rag-doll physics, and cloth simulation. The format is still relatively unknown and has only been brute forced through hex analysis more than code analysis, and there are unfortunately not many examples files to reference.

{| class="wikitable mw-collapsible mw-collapsed"
|+List of known PBA file examples
!Game
!Filename
!Description
!Notes
|-
|rangers
|<code>chr_big.pba</code>
|Big's fishing line and lure
|Unused
|-
|rangers
|<code>chr_knucklesdrill.pba</code>
|Knuckles' drill tail
|Unused
|-
|rangers
|<code>chr_kodama01.pba</code>
|Plant toppers on Koco variants
|Unused
|-
|rangers
|<code>chr_sage.pba</code>
|Dress cloth physics and self collisions with legs
|Unused. This is the only known file with a cloth node, and unknown if self collisions were ever in a working state when ported to Shadow Generations
|-
|rangers
|<code>enm_wolf01.pba</code>
|Wolf tail
|Unused
|-
|rangers
|<code>mbo_tracker01.pba</code>
|Tracker's brain stem
|Only used PBA file in Frontiers
|-
|miller
|<code>bos_metaloverload.pba</code>
|Metal Overlord's pipes/tubes
|
|-
|miller
|<code>chr_big.pba</code>
|Big's fishing line, hook and lure
|Has collision and more bones than Frontiers version
|-
|miller
|<code>chr_shadow.pba</code>
|Shadow's head quills
|
|-
|miller
|<code>chr_shadow_dameba.pba</code>
|Ameba Doom Morph's tentacles and legs
|
|-
|miller
|<code>chr_shadow_dwing.pba</code>
|Doom Wings entirety
|
|-
|miller
|<code>chr_terios.pba</code>
|Terios's head quills
|
|}

== Binary Structure ==
TODO: Decipher, clean up, explain 0_0 might have lots of wrong info!<syntaxhighlight lang="c++">
//------------------------------------------------
//--- 010 Editor v12.0.1 Binary Template
//
// File:
// Authors: Ashrindy, AdelQ
// Version: 0.0.1
// Purpose: Shadow Gens PhysicalSkeleton
// Category:
// File Mask: *.pba
// ID Bytes:
// History:
//------------------------------------------------

#include "../include.h"

local uint64 dataPos;

typedef struct{
Vector4 rows[4];
}Matrix4x4<optimize=false>;

typedef struct{
byte UnkB1; // Always 2 or 1, unknown flag
byte UnkB2; // Always 0 or 1, unknown flag
byte UnkB3[2]; // Padding?
float Unk_f[4]; // Upper/Lower limits of something?
}LimitsStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
int unk; // if this is related to collision, this could be an enum for the collision shape
float unk2; // Physics dampening? Lower values make bones wobble for longer
Matrix4x4 mat; // Most likely not a matrix, has parameters that affect gravity, stretch, etc, and possibly capsule/collision bounds(?) but still working through
}CollisionStruct<optimize=false>; // Has params that affect physics intensity still, maybe general physics

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
byte Unk1[4]; // All known examples are 01 01 14 00. could be bitflags by the looks of it
int16 LocalParentBoneIndex; // FF FF if no bone parent
int16 LocalBoneIndex;
int16 RealParentBoneIndex; // Usually the parent of this bone on the real skeleton, but can be any bone in practice. Perhaps a reference for the offset transform?
int16 Unk3;
LimitsStruct Limits[6]; // Unknown what these limits line up to (Pos to Neg X, Pos to Neg Y, etc)
float Unk4<hidden=true>; // Align
Matrix4x4 mat; // Possibly bone offset matrix relative to RealParentBoneIndex? A: Two quaternions in row 2 and 4?
}
JiggleStruct<optimize=false>; // Handles bone chain relations for bendy/jiggle physics, as well as presumably transform limits

typedef struct{
// Starting point needs to align to 16 bytes
local uint64 CurPos = FTell();
local uint64 AlignCheck = CurPos % 0x10;
if (AlignCheck)
FSeek(CurPos + 0x10 - AlignCheck);
SetRandomBackColor();
StringOffset BoneName;
float unk0; // All known examples = 0.01
int16 unk1<hidden=true>; // Always FF FF
int16 if_pinned; // 1 if no parent present. Possibly this bone controls corresponding vertex if 1, versus vertex controls cooresponding bone if 0
int16 child_idx; // FF if no child
int16 parent_idx; // FF if no parent
int16 unk2[2]<hidden=true>; // Always FF FF
int16 left_idx;
int16 right_idx;
}cloth_node<optimize=false>; // Defines up to 4 neighboring bones in a cloth bone grid

typedef struct{
SetRandomBackColor();
int16 verts[2];
float edge_length;
float unk_factor; // Normalized, lateral direct connections = 0.5, lateral skip connections = 0.3, vertical direct connections = 1.0. Maybe a stretch/shrink factor?
}cloth_edges<optimize=false>; // Cloth sim edge mesh

typedef struct{
SetRandomBackColor();
StringOffset cloth_name;
float unk1[10];
int16 unk_count1[2];
int32 cloth_node_count;
int32 cloth_edge_count;
int32 unk3<hidden=true>; // Align
int64 cloth_node_ptr;
int64 cloth_edge_ptr;
local int64 prePos = FTell();
FSeek(cloth_node_ptr + dataPos);
cloth_node bones[cloth_node_count];
FSeek(cloth_edge_ptr + dataPos);
cloth_edges edges[cloth_edge_count];
FSeek(prePos);
}ClothStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
char signature[4]<name="Signature">;
int version <format=hex, name="Version">;
StringOffset SkeletonName;
uint32 CollisionCount;
uint32 JiggleCount;
uint64 CollisionOffset;
uint64 JiggleOffset;
uint32 ClothCount;
uint32 UnkCount;
uint64 ClothOffset;
uint64 UnkOffset;
FSeek(CollisionOffset + dataPos);
CollisionStruct CollisionStructs[CollisionCount];
FSeek(JiggleOffset + dataPos);
JiggleStruct JiggleStructs[JiggleCount];
FSeek(ClothOffset + dataPos);
ClothStruct ClothStructs[ClothCount];
}
ResPhysicalSkeleton<open=true>;

ResBinaryFile file("ResPhysicalSkeleton")<name=Str("%s", FileNameGetBase(GetFileName()))>;
</syntaxhighlight>

PBA

2025-04-12T07:31:30Z

AdelQue:

{{Notice|type=warn|content=WIP Page, just adding to start}}
[[File:PBA cloth demonstration.gif|alt=Depicted in Blender using built-in cloth simulation, and bones constrained to corresponding vertex group|thumb|<code>chr_sage.pba</code> contains a node for a cloth mesh made up of only vertices and edges, interconnected in such a way to maintain shape with internal springs|325x325px]]
PBA files are bone physics files first found in [[Sonic Frontiers]], and first regularly used in [[Shadow Generations|Shadow Generations.]] The system is capable of using bouncy bones/jiggle physics, rag-doll physics, and cloth simulation. The format is still relatively unknown and has only been brute forced through hex analysis more than code analysis, and there are unfortunately not many examples files to reference. The below template has lots of unknowns and potentially wrong info.

== Binary Structure ==
TODO: Decipher, clean up, explain 0_0<syntaxhighlight lang="c++">
//------------------------------------------------
//--- 010 Editor v12.0.1 Binary Template
//
// File:
// Authors: Ashrindy, AdelQ
// Version: 0.0.1
// Purpose: Shadow Gens PhysicalSkeleton
// Category:
// File Mask: *.pba
// ID Bytes:
// History:
//------------------------------------------------

#include "../include.h"

local uint64 dataPos;

typedef struct{
Vector4 rows[4];
}Matrix4x4<optimize=false>;

typedef struct{
byte UnkB1; // Always 2 or 1, unknown flag
byte UnkB2; // Always 0 or 1, unknown flag
byte UnkB3[2]; // Padding?
float Unk_f[4]; // Upper/Lower limits of something?
}LimitsStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
int unk; // if this is related to collision, this could be an enum for the collision shape
float unk2; // Physics dampening? Lower values make bones wobble for longer
Matrix4x4 mat; // Most likely not a matrix, has parameters that affect gravity, stretch, etc, and possibly capsule/collision bounds(?) but still working through
}CollisionStruct<optimize=false>; // Has params that affect physics intensity still, maybe general physics

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
byte Unk1[4]; // All known examples are 01 01 14 00. could be bitflags by the looks of it
int16 LocalParentBoneIndex; // FF FF if no bone parent
int16 LocalBoneIndex;
int16 RealParentBoneIndex; // Usually the parent of this bone on the real skeleton, but can be any bone in practice. Perhaps a reference for the offset transform?
int16 Unk3;
LimitsStruct Limits[6]; // Unknown what these limits line up to (Pos to Neg X, Pos to Neg Y, etc)
float Unk4<hidden=true>; // Align
Matrix4x4 mat; // Possibly bone offset matrix relative to RealParentBoneIndex? A: Two quaternions in row 2 and 4?
}
JiggleStruct<optimize=false>; // Handles bone chain relations for bendy/jiggle physics, as well as presumably transform limits

typedef struct{
// Starting point needs to align to 16 bytes
local uint64 CurPos = FTell();
local uint64 AlignCheck = CurPos % 0x10;
if (AlignCheck)
FSeek(CurPos + 0x10 - AlignCheck);
SetRandomBackColor();
StringOffset BoneName;
float unk0; // All known examples = 0.01
int16 unk1<hidden=true>; // Always FF FF
int16 if_pinned; // 1 if no parent present. Possibly this bone controls corresponding vertex if 1, versus vertex controls cooresponding bone if 0
int16 child_idx; // FF if no child
int16 parent_idx; // FF if no parent
int16 unk2[2]<hidden=true>; // Always FF FF
int16 left_idx;
int16 right_idx;
}cloth_node<optimize=false>; // Defines up to 4 neighboring bones in a cloth bone grid

typedef struct{
SetRandomBackColor();
int16 verts[2];
float edge_length;
float unk_factor; // Normalized, lateral direct connections = 0.5, lateral skip connections = 0.3, vertical direct connections = 1.0. Maybe a stretch/shrink factor?
}cloth_edges<optimize=false>; // Cloth sim edge mesh

typedef struct{
SetRandomBackColor();
StringOffset cloth_name;
float unk1[10];
int16 unk_count1[2];
int32 cloth_node_count;
int32 cloth_edge_count;
int32 unk3<hidden=true>; // Align
int64 cloth_node_ptr;
int64 cloth_edge_ptr;
local int64 prePos = FTell();
FSeek(cloth_node_ptr + dataPos);
cloth_node bones[cloth_node_count];
FSeek(cloth_edge_ptr + dataPos);
cloth_edges edges[cloth_edge_count];
FSeek(prePos);
}ClothStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
char signature[4]<name="Signature">;
int version <format=hex, name="Version">;
StringOffset SkeletonName;
uint32 CollisionCount;
uint32 JiggleCount;
uint64 CollisionOffset;
uint64 JiggleOffset;
uint32 ClothCount;
uint32 UnkCount;
uint64 ClothOffset;
uint64 UnkOffset;
FSeek(CollisionOffset + dataPos);
CollisionStruct CollisionStructs[CollisionCount];
FSeek(JiggleOffset + dataPos);
JiggleStruct JiggleStructs[JiggleCount];
FSeek(ClothOffset + dataPos);
ClothStruct ClothStructs[ClothCount];
}
ResPhysicalSkeleton<open=true>;

ResBinaryFile file("ResPhysicalSkeleton")<name=Str("%s", FileNameGetBase(GetFileName()))>;
</syntaxhighlight>

PBA

2025-04-12T07:29:51Z

AdelQue:

{{Notice|type=warn|content=WIP Page, just adding to start}}
[[File:PBA cloth demonstration.gif|alt=Depicted in Blender using built-in cloth simulation, and bones constrained to corresponding vertex group|thumb|<code>chr_sage.pba</code> contains a node for a cloth mesh made up of only vertices and edges, interconnected in such a way to maintain shape with internal springs]]

PBA files are bone physics files first found in [[Sonic Frontiers]], and first regularly used in [[Shadow Generations|Shadow Generations.]] The system is capable of using bouncy bones/jiggle physics, rag-doll physics, and cloth simulation. The format is still relatively unknown and has only been brute forced through hex analysis more than code analysis, and there are unfortunately not many examples files to reference. The below template has lots of unknowns and potentially wrong info.

TODO: Cleanup:<syntaxhighlight lang="c++">
//------------------------------------------------
//--- 010 Editor v12.0.1 Binary Template
//
// File:
// Authors: Ashrindy, AdelQ
// Version: 0.0.1
// Purpose: Shadow Gens PhysicalSkeleton
// Category:
// File Mask: *.pba
// ID Bytes:
// History:
//------------------------------------------------

#include "../include.h"

local uint64 dataPos;

typedef struct{
Vector4 rows[4];
}Matrix4x4<optimize=false>;

typedef struct{
byte UnkB1; // Always 2 or 1, unknown flag
byte UnkB2; // Always 0 or 1, unknown flag
byte UnkB3[2]; // Padding?
float Unk_f[4]; // Upper/Lower limits of something?
}LimitsStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
int unk; // if this is related to collision, this could be an enum for the collision shape
float unk2; // Physics dampening? Lower values make bones wobble for longer
Matrix4x4 mat; // Most likely not a matrix, has parameters that affect gravity, stretch, etc, and possibly capsule/collision bounds(?) but still working through
}CollisionStruct<optimize=false>; // Has params that affect physics intensity still, maybe general physics

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
byte Unk1[4]; // All known examples are 01 01 14 00. could be bitflags by the looks of it
int16 LocalParentBoneIndex; // FF FF if no bone parent
int16 LocalBoneIndex;
int16 RealParentBoneIndex; // Usually the parent of this bone on the real skeleton, but can be any bone in practice. Perhaps a reference for the offset transform?
int16 Unk3;
LimitsStruct Limits[6]; // Unknown what these limits line up to (Pos to Neg X, Pos to Neg Y, etc)
float Unk4<hidden=true>; // Align
Matrix4x4 mat; // Possibly bone offset matrix relative to RealParentBoneIndex? A: Two quaternions in row 2 and 4?
}
JiggleStruct<optimize=false>; // Handles bone chain relations for bendy/jiggle physics, as well as presumably transform limits

typedef struct{
// Starting point needs to align to 16 bytes
local uint64 CurPos = FTell();
local uint64 AlignCheck = CurPos % 0x10;
if (AlignCheck)
FSeek(CurPos + 0x10 - AlignCheck);
SetRandomBackColor();
StringOffset BoneName;
float unk0; // All known examples = 0.01
int16 unk1<hidden=true>; // Always FF FF
int16 if_pinned; // 1 if no parent present. Possibly this bone controls corresponding vertex if 1, versus vertex controls cooresponding bone if 0
int16 child_idx; // FF if no child
int16 parent_idx; // FF if no parent
int16 unk2[2]<hidden=true>; // Always FF FF
int16 left_idx;
int16 right_idx;
}cloth_node<optimize=false>; // Defines up to 4 neighboring bones in a cloth bone grid

typedef struct{
SetRandomBackColor();
int16 verts[2];
float edge_length;
float unk_factor; // Normalized, lateral direct connections = 0.5, lateral skip connections = 0.3, vertical direct connections = 1.0. Maybe a stretch/shrink factor?
}cloth_edges<optimize=false>; // Cloth sim edge mesh

typedef struct{
SetRandomBackColor();
StringOffset cloth_name;
float unk1[10];
int16 unk_count1[2];
int32 cloth_node_count;
int32 cloth_edge_count;
int32 unk3<hidden=true>; // Align
int64 cloth_node_ptr;
int64 cloth_edge_ptr;
local int64 prePos = FTell();
FSeek(cloth_node_ptr + dataPos);
cloth_node bones[cloth_node_count];
FSeek(cloth_edge_ptr + dataPos);
cloth_edges edges[cloth_edge_count];
FSeek(prePos);
}ClothStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
char signature[4]<name="Signature">;
int version <format=hex, name="Version">;
StringOffset SkeletonName;
uint32 CollisionCount;
uint32 JiggleCount;
uint64 CollisionOffset;
uint64 JiggleOffset;
uint32 ClothCount;
uint32 UnkCount;
uint64 ClothOffset;
uint64 UnkOffset;
FSeek(CollisionOffset + dataPos);
CollisionStruct CollisionStructs[CollisionCount];
FSeek(JiggleOffset + dataPos);
JiggleStruct JiggleStructs[JiggleCount];
FSeek(ClothOffset + dataPos);
ClothStruct ClothStructs[ClothCount];
}
ResPhysicalSkeleton<open=true>;

ResBinaryFile file("ResPhysicalSkeleton")<name=Str("%s", FileNameGetBase(GetFileName()))>;
</syntaxhighlight>

File:PBA cloth demonstration.gif

2025-04-12T07:21:59Z

AdelQue:

chr_sage.pba applied to applicable chr_sage.skl.pxd bones for cloth physics

PXD

2025-04-08T09:14:01Z

AdelQue:

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Rio 2016 Olympic Games|Rio 2016 Olympics]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S 2016 Rio Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component for translation and scale is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

==== Posing and Transform Inheritance: ====
Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

# Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind.
#* In Blender, a bone's scale inheritance mode can be changed from `Full` to `Aligned` to achieve this effect
# Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

'''Trivia''': ''The inheritance and relationships behavior for bone transform values have been found to be identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hka</code> functions.''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

== Thanks ==

* [https://github.com/Turk645 Turk645:] Original uncompressed PXD blender importer scripts
* [https://github.com/WistfulHopes WistfulHopes:] ACL tools, blender export scripts
* [https://github.com/ik-01 ik-01]: Format and game code research, filling in gaps for unknown values
* [https://github.com/AdelQue AdelQue:] Format research, math relations and bone inheritance behaviors
[[Category:File Formats]]

PXD

2025-04-08T08:57:01Z

AdelQue:

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Rio 2016 Olympic Games|Rio 2016 Olympics]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S 2016 Rio Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

==== Posing and Transform Inheritance: ====
Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

# Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind.
#* In Blender, a bone's scale inheritance mode can be changed from `Full` to `Aligned` to achieve this effect
# Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

'''Trivia''': ''The inheritance and relationships behavior for bone transform values have been found to be identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hka</code> functions.''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

== Thanks ==

* [https://github.com/Turk645 Turk645:] Original uncompressed PXD blender importer scripts
* [https://github.com/WistfulHopes WistfulHopes:] ACL tools, blender export scripts
* [https://github.com/ik-01 ik-01]: Format and game code research, filling in gaps for unknown values
* [https://github.com/AdelQue AdelQue:] Format research, math relations and bone inheritance behaviors
[[Category:File Formats]]

PXD

2025-04-08T08:42:22Z

AdelQue:

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Rio 2016 Olympic Games|Rio 2016 Olympics]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S 2016 Rio Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

==== Posing and Transform Inheritance: ====
Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

# Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind.
#* In Blender, a bone's scale inheritance mode can be changed from `Full` to `Aligned` to achieve this effect
# Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

'''Trivia''': ''The inheritance and relationships behavior for bone transform values have been found to be identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hka</code> functions.''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

== Thanks ==

* [https://github.com/Turk645 Turk645:] Original uncompressed PXD blender importer scripts
* [https://github.com/WistfulHopes WistfulHopes:] ACL tools, blender export scripts
* [https://github.com/ik-01 ik-01]: Format and game code research, filling in gaps for unknown values
* [https://github.com/AdelQue AdelQue:] Format research, math relations and bone inheritance behaviors

PXD

2025-04-08T08:40:39Z

AdelQue: Add Thanks

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Rio 2016 Olympic Games|Rio 2016 Olympics]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S 2016 Rio Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

Posing and Transform Inheritance:

Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

# Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind.
#* In Blender, a bone's scale inheritance mode can be changed from `Full` to `Aligned` to achieve this effect
# Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

Trivia: The inheritance and relationships behavior for bone transform values are identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hkaPose</code>.

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

== Thanks ==

* [https://github.com/Turk645 Turk645:] Original uncompressed PXD blender importer scripts
* [https://github.com/WistfulHopes WistfulHopes:] ACL tools, blender export scripts
* [https://github.com/ik-01 ik-01]: Format and game code research, filling in gaps for unknown values
* [https://github.com/AdelQue AdelQue:] Format research, math relations and bone inheritance behaviors

PBA

2025-04-08T08:07:19Z

AdelQue: Created page with "{{Notice|type=warn|content=WIP Page, just adding to start}} PBA files are bone physics files first found in Sonic Frontiers, and first regularly used in Shadow Generations. The system is capable of using bouncy bones/jiggle physics, ragdolling, and cloth simulation. The format is still relatively unknown and has only been brute forced through hex analysis more than code analysis, and there are unfortunately not many examples files to reference..."

{{Notice|type=warn|content=WIP Page, just adding to start}}

PBA files are bone physics files first found in [[Sonic Frontiers]], and first regularly used in [[Shadow Generations|Shadow Generations.]] The system is capable of using bouncy bones/jiggle physics, ragdolling, and cloth simulation. The format is still relatively unknown and has only been brute forced through hex analysis more than code analysis, and there are unfortunately not many examples files to reference. The below template has lots of unknowns and potentially wrong info.

TODO: Cleanup:<syntaxhighlight lang="c++">
//------------------------------------------------
//--- 010 Editor v12.0.1 Binary Template
//
// File:
// Authors: Ashrindy, AdelQ
// Version: 0.0.1
// Purpose: Shadow Gens PhysicalSkeleton
// Category:
// File Mask: *.pba
// ID Bytes:
// History:
//------------------------------------------------

#include "../include.h"

local uint64 dataPos;

typedef struct{
Vector4 rows[4];
}Matrix4x4<optimize=false>;

typedef struct{
byte UnkB1; // Always 2 or 1, unknown flag
byte UnkB2; // Always 0 or 1, unknown flag
byte UnkB3[2]; // Padding?
float Unk_f[4]; // Upper/Lower limits of something?
}LimitsStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
int unk; // if this is related to collision, this could be an enum for the collision shape
float unk2; // Physics dampening? Lower values make bones wobble for longer
Matrix4x4 mat; // Most likely not a matrix, has parameters that affect gravity, stretch, etc, and possibly capsule/collision bounds(?) but still working through
}CollisionStruct<optimize=false>; // Has params that affect physics intensity still, maybe general physics

typedef struct{
SetRandomBackColor();
StringOffset BoneName;
byte Unk1[4]; // All known examples are 01 01 14 00. could be bitflags by the looks of it
int16 LocalParentBoneIndex; // FF FF if no bone parent
int16 LocalBoneIndex;
int16 RealParentBoneIndex; // Usually the parent of this bone on the real skeleton, but can be any bone in practice. Perhaps a reference for the offset transform?
int16 Unk3;
LimitsStruct Limits[6]; // Unknown what these limits line up to (Pos to Neg X, Pos to Neg Y, etc)
float Unk4<hidden=true>; // Align
Matrix4x4 mat; // Possibly bone offset matrix relative to RealParentBoneIndex? A: Two quaternions in row 2 and 4?
}
JiggleStruct<optimize=false>; // Handles bone chain relations for bendy/jiggle physics, as well as presumably transform limits

typedef struct{
// Starting point needs to align to 16 bytes
local uint64 CurPos = FTell();
local uint64 AlignCheck = CurPos % 0x10;
if (AlignCheck)
FSeek(CurPos + 0x10 - AlignCheck);
SetRandomBackColor();
StringOffset BoneName;
float unk0; // All known examples = 0.01
int16 unk1<hidden=true>; // Always FF FF
int16 if_pinned; // 1 if no parent present. Possibly this bone controls corresponding vertex if 1, versus vertex controls cooresponding bone if 0
int16 child_idx; // FF if no child
int16 parent_idx; // FF if no parent
int16 unk2[2]<hidden=true>; // Always FF FF
int16 left_idx;
int16 right_idx;
}cloth_node<optimize=false>; // Defines up to 4 neighboring bones in a cloth bone grid

typedef struct{
SetRandomBackColor();
int16 verts[2];
float edge_length;
float unk_factor; // Normalized, lateral direct connections = 0.5, lateral skip connections = 0.3, vertical direct connections = 1.0. Maybe a stretch/shrink factor?
}cloth_edges<optimize=false>; // Lagrangian cloth sim edge mesh

typedef struct{
SetRandomBackColor();
StringOffset cloth_name;
float unk1[10];
int16 unk_count1[2];
int32 cloth_node_count;
int32 cloth_edge_count;
int32 unk3<hidden=true>; // Align
int64 cloth_node_ptr;
int64 cloth_edge_ptr;
local int64 prePos = FTell();
FSeek(cloth_node_ptr + dataPos);
cloth_node bones[cloth_node_count];
FSeek(cloth_edge_ptr + dataPos);
cloth_edges edges[cloth_edge_count];
FSeek(prePos);
}ClothStruct<optimize=false>;

typedef struct{
SetRandomBackColor();
char signature[4]<name="Signature">;
int version <format=hex, name="Version">;
StringOffset SkeletonName;
uint32 CollisionCount;
uint32 JiggleCount;
uint64 CollisionOffset;
uint64 JiggleOffset;
uint32 ClothCount;
uint32 UnkCount;
uint64 ClothOffset;
uint64 UnkOffset;
FSeek(CollisionOffset + dataPos);
CollisionStruct CollisionStructs[CollisionCount];
FSeek(JiggleOffset + dataPos);
JiggleStruct JiggleStructs[JiggleCount];
FSeek(ClothOffset + dataPos);
ClothStruct ClothStructs[ClothCount];
}
ResPhysicalSkeleton<open=true>;

ResBinaryFile file("ResPhysicalSkeleton")<name=Str("%s", FileNameGetBase(GetFileName()))>;
</syntaxhighlight>

Documentation

2025-04-08T08:00:35Z

AdelQue:

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|
* <code>.xncp</code>
* <code>.yncp</code>
* <code>.gncp</code>
* <code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeleton and skeletal animation format in Hedgehog Engine 2 Games
|
* <code>.anm.pxd</code>
* <code>.skl.pxd</code>
|[[Frontiers Animation Tools]]
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Documentation

2025-04-08T08:00:15Z

AdelQue:

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|
* <code>.xncp</code>
* <code>.yncp</code>
* <code>.gncp</code>
* <code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeleton and skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code><code>.skl.pxd</code>
|[[Frontiers Animation Tools]]
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Documentation

2025-04-08T07:59:51Z

AdelQue:

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|<code>.xncp</code><code>.yncp</code><code>.gncp</code><code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeleton and skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code><code>.skl.pxd</code>
|[[Frontiers Animation Tools]]
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Documentation

2025-04-08T07:59:26Z

AdelQue:

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|<code>.xncp</code>
<code>.yncp</code>
<code>.gncp</code>
<code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeleton and skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code><code>.skl.pxd</code>
|[[Frontiers Animation Tools]]
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Documentation

2025-04-08T07:56:06Z

AdelQue:

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|
* <code>.xncp</code>
* <code>.yncp</code>
* <code>.gncp</code>
* <code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code>
| rowspan="2" |[[Frontiers Animation Tools]]
|-
|[[PXD|PXD Skeleton]]
|Skeleton format in Hedgehog Engine 2 Games
|<code>.skl.pxd</code>
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Documentation

2025-04-08T07:55:42Z

AdelQue:

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|
* <code>.xncp</code>
* <code>.yncp</code>
* <code>.gncp</code>
* <code>.sncp</code>

|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code>
| rowspan="2" |[[Frontiers Animation Tools]]
|-
|[[PXD|PXD Skeleton]]
|Skeleton format in Hedgehog Engine 2 Games
|<code>.skl.pxd</code>
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Documentation

2025-04-08T07:51:49Z

AdelQue: Add PBA

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|<code>.xncp</code>
<code>.yncp</code>

<code>.gncp</code>

<code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code>
| rowspan="2" |[[Frontiers Animation Tools]]
|-
|[[PXD|PXD Skeleton]]
|Skeleton format in Hedgehog Engine 2 Games
|<code>.skl.pxd</code>
|-
|[[PBA|PBA Skeleton]]
|Physics Based Animation Skeleton for Hedgehog Engine 2 Games
|<code>.pba</code>
|
|}

Sonic Frontiers

2025-04-08T07:49:44Z

AdelQue: Add Animation

== Tools ==

==== Animation ====

* [[Frontiers Animation Tools]]

== Guides ==
N/A

== Documentation ==

==== Game ====
* [[Sonic Frontiers DLCs|DLCs]]
* [[Sonic Frontiers Stage IDs|Stage IDs]]
* [[Sonic Frontiers Enemy Internal Names|Enemy Internal Names]]
* [[Sonic Frontiers Script Functions|Script Functions]]

==== File Formats ====

* [[Sonic Frontiers RFL|Reflection Data <code>.rfl</code>]]

==== Objects ====

* [[Sonic Frontiers Gismos|Gismos]]

== Discoveries ==
N/A

Shadow Generations

2025-04-08T07:49:32Z

AdelQue: Add Animation

== Tools ==

=== Animation ===

* [[Frontiers Animation Tools]]

== Guides ==
N/A

== Documentation ==

==== Game ====
* [[Shadow Generations Stage IDs|Stage IDs]]
* [[Shadow Generations Event IDs|Event IDs]]

== Discoveries ==
N/A

Guides

2025-04-08T07:41:33Z

AdelQue: It's not immediately obvious from the home page that the list of games go to lists of guides. Adding redirect in case a direct link becomes necessary

#REDIRECT [[Games]]

PXD

2025-04-08T07:37:46Z

AdelQue: Added uncompressed animation section, cleaned up

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from [[Mario & Sonic at the Rio 2016 Olympic Games|Rio 2016 Olympics]] to [[Shadow Generations]] contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code> identified as <code>PXAN</code>, possibly for "PXD Animation" or similar:

=== PXAN Header ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // Null alignment to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float duration; // Duration of the animation in seconds, calculated as ((frame_count - 1) / FPS)
uint32_t frame_count;
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed == 0x08)
char[8]; // Null alignment to 0x10 bytes for ACL data.
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0, first seen in [[Sonic Origins]], and unchanged in any implementation since then. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">struct ACLData {
uint32_t acl_chunk_size;
int32_t acl_hash;

uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any HE2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data
};</syntaxhighlight>At the end of an ACL chunk, if it is a skeletal animation chunk and root motion is present in the file, the chunk will be null padded to 16 bytes. If the ACL chunk is a root motion chunk or a skeletal animation with no associated root motion chunk in the file, the chunk will be null padded to 4 bytes. The last ACL chunk is immediately followed by the BINA offset table.

==== Raw/Decompressed Track List: ====
The index lookup for which transform set belongs to which bone can be found in the skeleton file [[PXD#.skl.pxd Structure|(see .skl.pxd Structure)]]. Each bone uses an [https://github.com/nfrechette/rtm RTM] [https://github.com/nfrechette/rtm/blob/7c9a61e32744ee9ff2978328d0e585635fd55615/includes/rtm/types.h#L393 qvvf] struct for transformation. Though the <code>W</code> element of each vector has no bearing on the final animation, the games usually store a value in there anyways and appears to have an effect on compression:<syntaxhighlight lang="c++">struct qvvf
{
quatf rotation; // XYZW Quaternion
vector4f translation; // XYZW Vector, W is undefined but appears to be bone length
vector4f scale; // XYZW Vector, W is undefined and always 1.0
};</syntaxhighlight>

=== Native Uncompressed Data: ===
{{Notice|type=note|content=This section could use a less confusing explanation.}}
Alternatively to compressed ACL track data, the PXAN structure can store individual components (rotation, translation, scale) of any given track at any frame, and linearly interpolate between them independently. This system was first seen in the [[Mario & Sonic at the Rio 2016 Olympic Games|M&S 2016 Rio Olympic Games]] as the exclusive method of storing animations. ACL compression may have an advantage in reducing the file size of many of these animations but—though rare—uncompressed animations have been observed in subsequent games for certain animations, presumably to combat any potential jitter during close up cutscenes or similar situations. Though the actual end data contained in this method is simple, the structure can end up like a spider's nest at first glance:

==== Track Offset Tables: ====
The first struct array found in the file is a track table for each bone. Within it, for each transform type (translation, rotation, scale), there is a keyframe count, offset pointing to a frame table, and offset pointing to an array of transforms. <syntaxhighlight lang="c++">struct TrackTableOffsets {
uint64_t pos_key_count; // Total number of translation keyframes for this bone
uint64_t pos_table_offset; // Offset for this bone's translation frame table
uint64_t pos_values_offset; // Starting offset for this bone's array of translation values

uint64_t rot_key_count; // Total number of rotation keyframes for this bone
uint64_t rot_table_offset; // Offset for this bone's rotation frame table
uint64_t rot_values_offset; // Starting offset for this bone's array of rotation values

uint64_t scale_key_count; // Total number of scale keyframes for this bone
uint64_t scale_table_offset; // Offset for this bone's scale frame table
uint64_t scale_values_offset; // Starting offset for this bone's array of scale values
};

TrackTableOffsets TrackTables[track_count]; // One for each bone, track_count from PXAN header</syntaxhighlight>

==== Frame Tables and Transforms: ====
Each transform type will get a frame table as <code>uint16_t[key_count] keys;</code> where each value is the frame that the keyframe will be inserted to, and transform array <code>vector4f[key_count] transforms; // XYZW floats</code> that will correspond to the frame with the matching array index. Unlike in ACL decompressed tracks, native uncompressed tracks' <code>W</code> component is always <code>0.0</code>. Both of these element arrays will be null aligned to 16 bytes.

=== Posing and Transform Inheritance: ===
Each bone's transformation is stored as an object space (AKA 'Pose Space' or 'Model Space') transform relative to its parent bone's final transformation. That means, regardless of what the reset pose or bone orientations are in the model's skeleton, the stored values of any given frame will completely overwrite any pose previously present.

However, there are two quirks that are unlike most interchange formats for 3D animations:

1.) Scale inheritance is a simple local space copy of the parent's local space scale. There is no shearing or skewing of any kind. 

2.) Calculating the position and rotation of any given bone is to be done independent of any scale values.

When reading in-game, though scales from recursive parents are inherited and multiplied, translation is completely unaffected in any capacity, unintuitively. Therefore, before applying any object space transformation in a setting where parent scale is assumed to affect the child bone's location, each bone's final scale must be calculated and applied by multiplying its and each recursive parent's scales together.

Trivia: The inheritance and relationships behavior for bone transform values are identical to all previous HE games that used Havok, possibly indicating that Sonic Team's custom implementation of animation playback and posing is loosely based on Havok's <code>hkaPose</code>.

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

Games

2025-04-08T05:30:10Z

AdelQue: Added dead link for consistency from another page

This section lists Sonic games by their engine, alongside their internal name. In this page, you're also able to access the game's own HedgeDocs page, which contains game specific guides, tools, and documentation.

== Hedgehog Engine ==
{| class="wikitable"
!Game Name
!Internal Name
|-
|[[Sonic Unleashed|Sonic Unleashed (Sonic World Adventure)]]
|SWA
|-
|[[Sonic Colors]]
|sonic2010
|-
|[[Sonic Generations]]
|BlueBlur
|-
|[[Sonic Lost World]]
|sonic2013
|-
|Sonic Colors: Ultimate*
|Rainbow
|-
|Sonic Generations (SONIC X SHADOW GENERATIONS)
|miller_g
|}
''* Sonic Colors: Ultimate also makes use of a forked version of Godot 3.''

== Hedgehog Engine 2 ==
{| class="wikitable"
!Game Name
!Internal Name
|-
|[[Mario & Sonic at the Rio 2016 Olympic Games]]
|unison
|-
|[[Sonic Forces]]
|wars
|-
|Olympic Games Tokyo 2020 - The Official Video Game
|musashi
|-
|Mario & Sonic at the Tokyo 2020 Olympic Games
|rings
|-
|(New) Sakura Wars
|arukas
|-
|Puyo Puyo Tetris 2
|tenpex
|-
|Sonic Origins*
|hite
|-
|[[Sonic Frontiers]]
|rangers
|-
|Sonic Frontiers: Digital Art Book with Mini Digital Soundtrack
|rangers_artbook
|-
|Sonic Origins Plus*
|hiteplus
|-
|Sonic Superstars - Digital Artbook and mini-OST
|orion_artbook
|-
|[[Shadow Generations]] / SONIC X SHADOW GENERATIONS
|miller
|-
|SONIC X SHADOW GENERATIONS: Art Book with Mini Soundtrack
|miller_das
|}
''* Sonic Origins (Plus) also makes use of Retro Engine v5U.''

== SEGA NN ==
{| class="wikitable"
!Game Name
!Internal Name
|-
|[[Sonic the Hedgehog (2006)|SONIC THE HEDGEHOG]]
|SonicNext / marathon
|}

Documentation

2025-04-06T01:32:43Z

AdelQue: Added PXD Links, code blocked extensions to be better readable

This section lists documentation pages for resources you'll find in Sonic games. You'll find information about certain file formats and other general game resources.

== Set-Data ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[HSON Format|HSON]] (Hedgehog Set Object Notation)
|Universal object placement representation format.
|<code>.hson</code>
|
|}

== User Interface ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[NCP File Format|NCP]] (Ninja CellSpriteDraw Project)
|Describes a user interface in most Hedgehog Engine games.
|<code>.xncp</code>
<code>.yncp</code>
<code>.gncp</code>
<code>.sncp</code>
|
* [[Kunai]]
* [[Shuriken]]
|}

== Archives ==
{| class="wikitable"
!Name
!Description
!Extension
!Tools
|-
|[[NN Chunk Format|NN Chunk]]
|Generic container format.
|
|
|}

== Animation ==
{| class="wikitable"
|+
!Name
!Description
!Extension
!Tools
|-
|[[PXD|PXD Animation]]
|Skeletal animation format in Hedgehog Engine 2 Games
|<code>.anm.pxd</code>
| rowspan="2" |[[Frontiers Animation Tools]]
|-
|[[PXD|PXD Skeleton]]
|Skeleton format in Hedgehog Engine 2 Games
|<code>.skl.pxd</code>
|}

PXD

2025-04-06T01:26:55Z

AdelQue: Added unfinished warning

{{Notice|type=warn|content=This page is unfinished.}}

== PXD Files ==
Hedgehog Engine 2 games from 2016 Olympics to Shadow Generations contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

=== Header: ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // 0x00 align to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float32 duration; // Duration of the animation in seconds, calculated as ((frame_count-1) / FPS)
uint32_t frame_count; // Frame count
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed)
char[8]; // Likely alignment to 16 bytes for ACL data. Always 0x00 if compressed
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">uint32_t acl_chunk_size; // Total size of chunk
int32_t acl_hash; // Hash
uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any Hedgehog Engine 2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any Hedgehog Engine 2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data</syntaxhighlight>

==== Raw/Decompressed Track List: ====
''TODO...''

=== Uncompressed Animation Data: ===
''TODO...''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

PXD

2025-04-06T01:24:59Z

AdelQue: Started PXD Documentation

== PXD Files ==
Hedgehog Engine 2 games from 2016 Olympics to Shadow Generations contain skeleton and skeletal animation files with the file extensions <code>.skl.pxd</code> and <code>.anm.pxd</code> respectively, stored in a [[BINA]] container. Skeletons contain pose data that usually result in a T-Pose, bone and parent indices, and bone names. Animations contain playback metadata such as frame rate and frame count, track count, and either compressed animation pose data using [https://github.com/nfrechette/acl ACL compression,] or raw uncompressed pose data that use bone and frame indices to specify keyframed transforms, with linear interpolation between keyframes. For both skeletons and animations, position and rotation data for each bone is an absolute transform relative to the parent position, whereas scales are inherited from their respective parents locally, and have no effect on their positions.

== <code>.anm.pxd</code> Structure ==
Animation files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

=== Header: ===
<syntaxhighlight lang="c++">struct Header {
char[4] magic; // 'NAXP'
uint32_t version; // Always 0x200
uint8_t additive; // 0x01 if additive, else 0x00
uint8_t compressed; // 0x08 if ACL compressed, 0x00 if uncompressed
char[6]; // 0x00 align to 8 bytes
uint64_t metadata_offset; // Offset to metadata, always 0x18
float32 duration; // Duration of the animation in seconds, calculated as ((frame_count-1) / FPS)
uint32_t frame_count; // Frame count
uint32_t track_count; // Bone count
uint64_t skel_anim_offset; // Offset for character's skeletal animation, always 0x40 if compressed, 0x38 if uncompressed
uint64_t root_anim_offset; // Offset for root motion animation, 0x00 if no root motion is present, aligned to 16 bytes
if (compressed)
char[8]; // Likely alignment to 16 bytes for ACL data. Always 0x00 if compressed
};</syntaxhighlight>

=== ACL Data: ===
All Hedgehog Engine 2 games that utilize the ACL library appear to use v2.0.0. [https://github.com/nfrechette/acl/tree/a54c5c2781be9f14b840a60f8dd8ec6c5065885d/docs See the ACL docs for more info.] If <code>compressed == 0x08</code>, skeletal animations and root motion animations are compressed.

==== Compressed Data: ====
Below is a high level overview of the stored ACL chunk data:<syntaxhighlight lang="c++">uint32_t acl_chunk_size; // Total size of chunk
int32_t acl_hash; // Hash
uint32_t acl_tag; // Identifies ACL buffer type, always 0xAC11AC11 to mark compressed_tracks
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/buffer_tag.h#L49

uint16_t acl_version; // ACL Version Enum Identifier. 0x07 indicates v2.0.0, the only version observed in any Hedgehog Engine 2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/compressed_tracks_version.h#L71

char acl_padding; // always 0x00
uint8_t acl_track_type; // ACL Track Type Enum. 0x0C indicates qvvf, the only track type observed in any Hedgehog Engine 2 game.
// https://github.com/nfrechette/acl/blob/976ff051048477f2281c7d3609fddf0b3cba2c2d/includes/acl/core/track_types.h#L68

uint32_t track_count; // Bone count if skeletal animation, 0x01 if root motion. Should match header track_count if skeletal.
uint32_t sample_count; // Frame count, should match header frame_count.
float32 sample_rate; // Playback FPS of animation, should equal header ((frame_count - 1) / duration)
char[acl_chunk_size - 0x1C] acl_data; // String of compressed ACL data</syntaxhighlight>

==== Raw/Decompressed Track List: ====
''TODO...''

=== Uncompressed Animation Data: ===
''TODO...''

== <code>.skl.pxd</code> Structure ==
Skeleton files are stored in a [[BINA]] container. Below is the contents stored within the <code>DATA</code> node beginning at file offset <code>0x40</code>:

''TODO...''

FrontiersAnimDecompress

2025-04-05T23:50:48Z

AdelQue: Created Redirect

#REDIRECT [[Frontiers Animation Tools]]

Tools

2025-04-05T23:49:46Z

AdelQue: Added FrontiersAnimDecompress

This section contains tools that aren't specific to any Sonic game. Below you can see the tools divided by the engine they target and their purpose.

== Various Engines ==

=== Audio ===

* [[SonicAudioTools]]

=== Animations ===

* [[KwasTools (Hedgehog Engine)|io_kwastools]] (.cam-anim, .uv-anim)

== Hedgehog Engine ==

=== Animations ===

* [[Frontiers Animation Tools]]

=== Archives ===

* [[PackCpk]] (.cpk)
* [[YACpkTool]] (.cpk)

* [[HedgeArchiveEditor]] (.ar, .pfd, .pac)
* [[HedgeArcPack]] (.ar, .pfd, .pac)
* [[ar0pack-ar0unpack]] (.ar, .pfd)

=== Collision ===
* [[Havok Converter]] (*.hkx)

=== Lighting ===
* [[HedgeGI]]
* [[SonicLightTools]]

=== Models ===

* [[terrain2fbx]] (.terrain-model)
* [[terrain2fbx-png]] (.terrain-model)

=== Text ===
* [[Converse]] (.fco / .fte)
=== UI ===
* [[Shuriken]] (.xncp / .yncp)
* [[Kunai]] (.xncp / .yncp / .gncp / .sncp)

PXD Animation Tools

2025-04-05T23:49:24Z

AdelQue: Created page

{{ToolInfobox|title=Frontiers Animation Tools|author=WistfulHopes, AdelQue, Turk645|website=https://github.com/WistfulHopes/FrontiersAnimDecompress|download=https://github.com/WistfulHopes/FrontiersAnimDecompress/releases/latest|image=FrontiersAnimDecompressPreview.gif}}

Frontiers Animation Tools (or FrontiersAnimDecompress) is a Blender add-on that allows the editing of Hedgehog Engine 2 skeletal animations.

File:FrontiersAnimDecompressPreview.gif

2025-04-05T23:48:30Z

AdelQue: Preview of Frontiers Animation Tools animation playback in Blender

== Summary ==
Preview of Frontiers Animation Tools animation playback in Blender