NCP File Format

Info

This page is written as a guide on how to go through an NCP file using 010 Editor with the 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:

• XNCP - Used on PC / Xbox
• YNCP - Used on PlayStation 3
• GNCP - Used on GameCube / Wii
• SNCP - 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 010 Editor. This program is used for hex editing, and in our case, to modify XNCP files. You'll also need to download the 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:

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.

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