HedgeDocs is a MediaWiki powered webpage that contains several guides, tools and documentation pages meant to help users creating modifications for Sonic the Hedgehog games.

2025-03-25T09:40:46Z

PTKay:

This section contains documentation that isn't specific to any game. You'll find information about certain file formats and other general game elements.

== File Formats ==

* [[HSON Format]]
* [[NCP File Format]]
* [[NN Chunk Format]]

NCP File Format

2025-03-25T09:21:19Z

PTKay:

{{Notice|type=info|content=This page is written as a guide on how to go through an NCP file using 010 Editor with the [https://github.com/tge-was-taken/010-Editor-Templates/blob/master/templates/sonic_xncp_yncp.bt XNCP Template]}}

'''NCP''' (Ninja CellSpriteDraw Project) is a file format used to specify user interfaces in most Hedgehog Engine games. There are several variants of this file format, each with it's own target platform:

* '''X'''NCP - Used on PC / Xbox
* '''Y'''NCP - Used on PlayStation 3
* '''G'''NCP - Used on GameCube / Wii
* '''S'''NCP - Used on PlayStation 2

In this page, you will read about how to open an NCP file in 010 editor and how this file is structured.

== Requirements ==
First of all, you will need to download the [https://www.sweetscape.com/010editor/ 010 Editor]. This program is used for hex editing, and in our case, to modify XNCP files. You'll also need to download the [https://github.com/tge-was-taken/010-Editor-Templates/blob/master/templates/sonic_xncp_yncp.bthttps://github.com/tge-was-taken/010-Editor-Templates/blob/master/templates/sonic_xncp_yncp.bt XNCP Template]. Essentially, this file will make it so that you can read and understand the XNCP file's contents, otherwise you'd only see hex numbers, and that's not exactly readable.

== Opening an XNCP file ==
After installing the 010 Editor, and downloaded the XNCP Template, it's time to open a file.

Open the 010 Editor and click on '''File > Open File...''', and open the file that you need to edit.
[[File:010 Editor open file.png|center|thumb|397x397px]]
After opening the file, you'll see a bunch of numbers. Don't get freaked out, this is normal. These are the contents of the XNCP file.
[[File:010 editor xncp hex.png|center|thumb|702x702px]]
Now, you need to go to '''Templates > Open Template...''', and open the file that we downloaded before. It's called '''sonic_xncp_yncp.bt'''.
[[File:010 Editor open template.png|center|thumb|343x343px]]
After opening the file, a window should pop up with the template's code. You can just ignore this window and hide it wherever you'd like, you won't need to modify this.

Now, go back to '''Templates''' and click on '''Run Template'''. This should now make the numbers have colorful backgrounds, and a new window will appear below the hex view.
[[File:010 Editor xncp template executed.png|center|thumb|944x944px]]
This new window that has appeared will be your workspace. This'll be the way in which you edit all aspects of a UI file. Click on the '''struct TFAPC File''' dropdown, then '''struct TFAPCEmbeddedRes Resources[0]''', then '''struct TNNNCPJChunk CsdmProject''', and then on '''struct TCSDNode Root'''. Now you'll have a few variables here; I'll explain what some of them mean!

== The structure of an XNCP file (Resource 0) ==
'''Scenes''' are essentially the containers for a specific group of UI elements, think of it like a folder inside a folder, and you'll need '''SceneIDTable''' to understand which Scene is what. This table contains the name and index of each Scene (e.g: Scene "gauge" in ui_gameplay.xncp is the "folder" that contains all elements of the boost bar in the HUD). Scenes also have a few variables that may be of interest, like:

* '''ZIndex''', this is essentially the layer in which the UI elements (known as '''Casts''') will render
* '''Groups''', are exactly what they are called, they are groups of '''Casts'''
* '''SubImages''', these are essentially textures that have been cut in specific portions to be used by Casts
* '''CastDictionary''', this will be one of the most useful variables when editing XNCP files, these contain all the names, indexes, and group indexes needed to find a specific Cast in the scene.
* '''AnimationKeyFrameDataList''', '''AnimationDictionary''', '''AnimationFrameDataList''', '''AnimationData2List''', all of these control animations. You can read more about them here

'''And the most important one of all:'''

* '''Casts''', these are the UI elements of XNCP files, these contain the necessary data to display text, move other elements, or display an image.

== The structure of a Cast ==
The Cast has several variables that you can change:

* '''Field04''' controls the type of the cast, these types can be:

0 - No Draw (invisible)
1 - Sprite
2 - Font

* '''IsEnabled''' will enable and disable a cast. 0 for disabled and 1 for enabled
** '''NOTE''': If you're disabling a cast, make sure that it does not have children, or it might make the UI look weird!

* '''Field0C''', '''Field14''', '''Field1C''', '''Field24''' change the positions of the corners of the cast, Top Left, Bottom Left, Top Right, Bottom Right respectively. These only really affect casts that render sprites
* '''Offset''' changes the position of the element relative to its parent. This is useful for moving elements around, although it's not used much.
* '''Field30Data''' contains most of the fun things that you can edit in a Cast, like:

Translation
Rotation
Scale
Color - where the variable "Color" will change the main color of the image, and GradientTopLeft,BottomLeft,TopRight,BottomRight will change the colors of the corners of the image

* '''Field40Data''' contains data about a cast's subimages. If the cast is a nodraw or font type, this will be all set to -1 most of the time. Each of these variables is a holder for a specific index of a subimage. However, only the first one is used all the time, all of the other ones are for animations.

== The structure of an XNCP file (Resource 1) ==
Before, I wrote that you needed to go into Resource 0. This is because Resource 0 has most of the cool stuff that you can edit, while Resource 1 contains data about image file locations.

* '''TextureList''', this is a list of all the textures used by the UI... this is pretty much it. Each texture will have a name, and it's index will be the number specified next to the "Textures" name.
[[File:010 Editor xncp texture list.png|center|thumb|813x813px]]

== XNCP Animations ==
XNCP animations for a specific scene are listed in '''AnimationDictionary''', which behaves the same way as the CastDictionary:
[[File:XNCP Animation Dictionary.png|center|thumb|658x658px]]
In '''AnimationFrameDataList''', it’s possible to control the amount of keyframes that a specific animation has:
[[File:XNCP Animation Frame Data List.png|center|thumb|503x503px]]
To control the speed of these animations, we have a single field in the scene that controls the frame rate:
[[File:XNCP Animation Framerate.png|center|thumb|694x694px]]
'''AnimationKeyFrameDataList''' contains the information for all the keyframes in the animation, as well as the casts that belong in that animation.
[[File:XNCP Animation Key Frame Data List.png|center|thumb|628x628px]]
In the screenshot above, we’re seeing the data referring to Animation 0 ('''Intro_Anim''' when following the dictionary). XNCPs usually follow this naming scheme for animations:

* '''Intro_Anim''' - Animation that plays when the scene appears
* '''Usual_Anim''' - Normally a looping animation, is used during the scenes visible state
* '''Outro_Anim''' - Played before the scene disappears They can obviously store other animations, and those have their own names.

So, in Intro_Anim, we have several '''CastAnimationData'''. These control what happens to each cast in this animation. Let’s see what happens to Cast 0 (position, which usually is the parent of all casts in a scene and controls their position)...
[[File:XNCP Cast Animation Data.png|center|thumb|511x511px]]
Seems like we have flags! It’s a bitfield, and it controls what actually animates in this cast. Here’s the meaning of each bit:
0000 0000(0) - Nothing
0000 0001(1) - Hide Flag
0000 0010(2) - X Position
0000 0100(4) - Y Position
0000 1000(8) - Rotation
0001 0000(16) - X Scale
0010 0000(32) - Y Scale
0100 0000(64) - SubImage
1000 0000(128) - Colour Mask
So, with this info, we now know what animates in the position cast: It is its X Position. The '''CastAnimationDataSubData1List''' is what stores the actual animation data. The amount of entries in this list depends on the number of bits signaled in the '''Flags''' field. The first entry in the list is referring to the first bit signaled from right to left. So by that logic, the list only has one entry.
[[File:XNCP Cast Animation Data Sub Data 1 List.png|center|thumb|500x500px]]
And there we go. This entry is what stores the actual '''KeyFrames'''. Let’s open one up to see how it is.
[[File:XNCP Key Frame.png|center|thumb|410x410px]]
Scary right? I don’t understand much of what’s going on here, but here we go.

'''Frame''' defines which global frame this keyframe is in. Remember '''AnimationFrameDataList'''? Yeah, this animation has a total of 10 frames, and is played at 60 FPS. For each frame, you define the global frame that it refers to. So, since this cast controls the position of the entire scene, and this is the intro animation, maybe the other keyframe has the frame field set to 10? We’ll see about that shortly.

'''Data''' store the data of this keyframe. The meaning of data changes depending on the flags. Data can be:

* A position
* An angle (for rotation)
* A size (for X and Y scale)
* An index (for SubImage)
* A colour (for ColorMask)

According to the flags of this specific cast, these keyframes are supposed to control the X Position, which means that “Data” actually represents the X Position of the cast in this frame.

The '''Offset''' and '''Offset2''' fields control the casts' Offset position value, where "Offset" is X, while "Offset2" is Y. For example, the buttons in the title screen of Sonic Generations use these values to stay in place when they're clicked since they get scaled up and down. Let’s look at the second keyframe:
[[File:XNCP Key Frame 2.png|center|thumb|356x356px]]
As we suspected, the '''Frame''' field is now set to 10, meaning this is referring to the last frame in the animation. The value in '''Data''' has increased, so this means that '''this cast slides from left to right''' in this animation!

Looking at the remaining '''CastAnimationData''' entries, we can see that none of them animate, since their '''Flags''' field is set to 0. So we can conclude that '''Intro_Anim''' makes the '''position''' cast slide from '''left to right''', and since “position” controls the entire scene, every single cast from this scene slides from left to right in this animation!
[[File:XNCP Cast Animation Data No Anim.png|center|thumb|571x571px]]

== Additional Notes ==
An animation can only be looped using code, so that can't be controlled via the XNCP. However, '''Field00''' in '''CastAnimationDataSubData''' does seem to control how fast a loop occurs, where the value '''1''' seems to loop it with a delay, while '''2''' makes it loop smoother.

== Conclusion ==
Hope I explained XNCP animations well enough. Have fun!

''PS: there’s also AnimationData2List but...''
[[File:XNCP Animation Data 2 List.png|center|thumb|629x629px]]