NCP File Format - Revision history

Hyper at 21:17, 1 May 2026

2026-05-01T21:17:07Z

← Older revision		Revision as of 21:17, 1 May 2026
Line 130:		Line 130:
	''PS: there’s also AnimationData2List but...''		''PS: there’s also AnimationData2List but...''
	[[File:XNCP Animation Data 2 List.png\|center\|thumb\|629x629px]]		[[File:XNCP Animation Data 2 List.png\|center\|thumb\|629x629px]]
			[[Category:File Formats]]

PTKay at 09:25, 26 March 2025

2025-03-26T09:25:23Z

← Older revision		Revision as of 09:25, 26 March 2025
Line 35:		Line 35:
	* '''SubImages''', these are essentially textures that have been cut in specific portions to be used by 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.		* '''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~~		* '''AnimationKeyFrameDataList''', '''AnimationDictionary''', '''AnimationFrameDataList''', '''AnimationData2List''', all of these control animations. You can read more about them later on in this page.

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

PTKay at 09:21, 25 March 2025

2025-03-25T09:21:19Z

← Older revision		Revision as of 09:21, 25 March 2025
Line 1:		Line 1:
	{{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]}}		{{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''' is a file format used to specify user interfaces in most Hedgehog Engine games. In this ~~guide~~, ~~I'll explain the general things~~ you ~~need~~ in ~~order to explore~~ this file ~~using 010 Editor~~.		'''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:

			* '''<u>X</u>'''NCP - Used on PC / Xbox
			* '''<u>Y</u>'''NCP - Used on PlayStation 3
			* '''<u>G</u>'''NCP - Used on GameCube / Wii
			* '''<u>S</u>'''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 ==		== Requirements ==

PTKay at 09:14, 25 March 2025

2025-03-25T09:14:55Z

← Older revision		Revision as of 09:14, 25 March 2025
Line 1:		Line 1:
	{{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]}}		{{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]}}

	'''~~XNCP~~''' is ~~the~~ file format ~~of Sonic Generations's UI~~. In this guide, I'll explain the general things you need to ~~get started~~.		'''NCP''' is a file format used to specify user interfaces in most Hedgehog Engine games. In this guide, I'll explain the general things you need in order to explore this file using 010 Editor.

	== Requirements ==		== Requirements ==

PTKay at 09:49, 13 March 2025

2025-03-13T09:49:23Z

← Older revision		Revision as of 09:49, 13 March 2025
Line 10:		Line 10:

	Open the 010 Editor and click on '''File > Open File...''', and open the file that you need to edit.		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.		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'''.		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.		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.		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!		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!

Line 61:		Line 61:

	* '''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.		* '''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 ==
	XNCP animations for a specific scene are listed in '''AnimationDictionary''', which behaves the same way as the CastDictionary:		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:		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:		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.		'''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:		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:

Line 78:		Line 79:

	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)...		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:		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.		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.		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.		Scary right? I don’t understand much of what’s going on here, but here we go.

Line 100:		Line 109:

	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:		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!		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!		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 ==		== Additional Notes ==
Line 112:		Line 122:

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

PTKay: Created page with "{{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]}} '''XNCP''' is the file format of Sonic Generations's UI. In this guide, I'll explain the general things you need to get started. == Requirements == First of all, you will need to download the [https://www.sweetscape.com/010editor/ 010 Editor]..."

2025-03-13T09:21:40Z

Created page with "{{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]}} '''XNCP''' is the file format of Sonic Generations's UI. In this guide, I'll explain the general things you need to get started. == Requirements == First of all, you will need to download the [https://www.sweetscape.com/010editor/ 010 Editor]..."

New page

{{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]}}

'''XNCP''' is the file format of Sonic Generations's UI. In this guide, I'll explain the general things you need to get started.

== 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.

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.

Now, you need to go to '''Templates > Open Template...''', and open the file that we downloaded before. It's called '''sonic_xncp_yncp.bt'''.

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.

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.

== XNCP Animations ==
XNCP animations for a specific scene are listed in '''AnimationDictionary''', which behaves the same way as the CastDictionary:

In '''AnimationFrameDataList''', it’s possible to control the amount of keyframes that a specific animation has:

To control the speed of these animations, we have a single field in the scene that controls the frame rate:

'''AnimationKeyFrameDataList''' contains the information for all the keyframes in the animation, as well as the casts that belong in that animation.

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)...

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:

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.

And there we go. This entry is what stores the actual '''KeyFrames'''. Let’s open one up to see how it is.

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:

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!

== 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...''