View source for How to use Kunai

This guide will explain most features of [[Kunai]], and how you can use it to edit CSD Project files and make custom UIs as well.

== Explanation of CSD files ==
CSD files are complex, but they are made of 5 primary types, which are: '''Scene Nodes''' ''(they'll be referred to as '''Nodes''' from now on)'', '''Scenes''', '''Casts''', '''Animations''' and '''Crops'''. '''Nodes''' are like sub-folders for the file, they contain collections of '''Scenes''' and they can contain sub-nodes. '''Scenes''' on the other hand contain '''Casts''' and '''Animations'''.

=== Casts ===
Casts are the actual UI elements that the games displays to the player, and they can be of 3 types: 

* Null ''(or No Draw)''
* Sprite
* Font

<code>Null Casts</code> are casts that have no visual information attached to them, and because of that they are fully transparent, these are used primarily as ways to move, scale or tint collections of other casts. 

<code>Sprite Casts</code> are casts that can display a Crop, which is Sega's term for a cropped sprite, these can contain multiple crops at once that can be switched through by animations or from code, which are called Patterns. Most files can only contain 32 patterns per cast, but games like Sonic Colors Ultimate can hold up to 256. 

<code>Font Casts</code> are casts that can display multiple crops at once in the form of a makeshift font, they can hold onto text, and the individual characters can be spaced out ''(Kunai cannot edit these at the moment, but there will be a window to edit them soon)''.

'''All Casts''' share some key properties, they can be hidden, toggled on or off, they can be tinted from the 4 corners of a cast as well as tinted in its entirety, they can be moved, scaled, rotated, they can be animated, and they can inherit values from parent casts through the use of the inheritance flags.

=== Animations ===
Animations are used by the game to manipulate the scene's Casts, each animation in a scene can edit any casts inside of it, and they can manipulate some of the casts' values, such as:

* Visibility
* Horizontal Position
* Vertical Position
* Rotation
* Horizontal Scale
* Vertical Scale
* Color
* Vertex Colors (casts can be tinted on all 4 corners in addition to tinting it all)
* Pattern

== How to use the interface ==
Kunai is made up of 4 main windows with some extra windows that can be used by enabling them through the View menu ( View > Windows ).

=== Hierarchy ===
The Hierarchy displays the contents of the currently loaded file, Nodes will have a folder icon, Scenes will have a film icon, and Casts will have different icons based on their type. Note that the checkboxes on the left side of all these controls only change the visibility '''in the program''', '''not''' in the file itself.
[[File:Kunai hierarchywindowexample.png|center|thumb|An example of the Hierarchy window's icons.]]

=== Inspector ===
The Inspector window allows you to modify the values of Scenes and Casts, the properties of the casts may change depending on the type (e.g. a Sprite cast will not have a Text section, a Null cast wont have a material section). Scenes contain the framerate and the target aspect ratio of the scene.<gallery mode="packed" widths="120" heights="240">
File:Kunai inspectorwindow example1.png|Casts inspector
File:Kunai inspectorwindow example2.png|Scenes inspector
</gallery>

=== Viewport ===
The Viewport window displays what the entire CSD Project file is rendering at that time, you can zoom in and out of it and you can change it's aspect ratio from 16:9 to 4:3, as some older files are made for use with 4:3 only and don't stretch. If a Cast is on-screen, you can edit it by clicking on it in the viewport window.
[[File:Kunai viewportwindow example.png|center|thumb|An example of the Viewport window.]]

=== Animator ===
The Animator window lets you modify the selected scene's animations, these can also be turned on or off ''(just like for the Hierarchy window, this only changes the visibility in the program)''. This window also allows you to view the 4 corners of every cast currently displayed, which can be useful to see where a cast is if it is off-screen, and it allows you to take a screenshot of the current state of the viewport window ''(although, due to an issue with the renderer, it'll always save the background too but it'll be fixed in the future).''
[[File:Kunai animatorwindow example.png|center|thumb|An example of the Animator window.]]

=== Other windows ===
Kunai will have other tools available as windows in the future, an example of a tool window is the Crop Editor window, which allows you to edit the crops in a file.

== Actions ==
In this section, some basic actions that can be done will be explained.

=== Register File Extensions ===
If you click on ( Edit > Associate file extensions ), a program will open to register xncp, yncp, gncp and sncp as filetypes for Kunai, and will give them distinct icons.

=== Changing a Sprite Cast's patterns ===
[[File:Kunai patternchange example.png|thumb|150x150px]]
To change the patterns used by a cast, you have to open it in the '''Inspector''', go to the '''Material''' section, change the '''Selected Sprite''' field to the pattern index you want, and then click on '''"Edit current pattern"''', this will enable a list view that lets you change the current pattern in that slot. Once you've selected the crop you want, you can click on '''"Stop editing pattern"''' to close the menu.


=== Adding new Scenes and Casts and removing them ===
[[File:Kunai rightclickmenu scene.png|thumb|150x150px]]
While creating new Scenes and Casts is supported, it is quite buggy and isn't guaranteed to work in all games. To add '''new Scenes''', you have to right click on a Node, and select the '''"New Scene"''' option. To add a '''new cast''', right click on a Scene or another Cast, and open the '''"New Cast..."''' menu, from there you can make a cast of any of the 3 types. You can '''delete''' Scenes and Casts by right clicking on them, and pressing '''"Delete".'''