Difference between revisions of "NKit/UserGuide"

Revision as of 14:19, 11 September 2019

Welcome to the NKit user guide

This guide aims to cover NKit's features and options from a user point of view. Please refer to the Glossary and FAQ if something isn't clear. Feel free to ask anything else in the GBA Temp NKit App thread. Thanks for reading.

Key Uses

There are two key used of NKit:

Recovery: Rebuild and repair images to match Redump verified images. This is aided by use of Recovery files that can be extracted from good sources. Recovery uses these files to rebuild the iso and repair modified disc headers, unscrub blocks, reinsert missing Wii partitions, move and reorder GameCube filesystems
Convert: Converts anything to the NKit Format and preserves the data so that it can be restored back to the source iso

NKit Apps

There are 2 types of apps, command line and GUI. All apps use the NKit.dll.

Note for Devs: The NKit.dll contains all the processing logic. Reference it to add NKit processing to any apps. The apps below all contain very little code and are simple examples how to use it.

Command Line Apps

ConvertToISO.exe - converts a source file to iso. This can be wbfs (scrubbing is preserved), iso.dec (junk is recreated) or NKit [iso/gcz] (source data is restored back to iso)
ConvertToNKit.exe - preserves the source image data as nkit [iso/gcz]. This can also be used to preserve scrubbed, hacked or bad dumps etc. For WBFS and iso.dec when restoring back to iso with ConvertToIso.exe the iso will contain all data that was in the original WBFS / iso.dec.
RecoverToISO.exe - attempts to recover GameCube and Wii images to .iso
RecoverToNKit.exe - attempts to recover GameCube and Wii images and convert to nkit.iso or nkit.gcz
RecoveryExtract.exe - saves recovery files from images. CRC's in The NKit.dll.config are used to save extracted files in to a 'Redump' or 'Other' folder.

GUI Apps

NKitExtractionApp.exe - extract recovery files or extract files from the image filesystems
NKitProcessingApp.exe - recover and convert files to iso / nkit [iso/gcz]. It has a drop down of option that performs the tasks of the first 4 commandline apps above

This user guide refers to conversions throughout which are the names of the command line apps - ConvertToISO, ConvertToNKit, RecoverToISO and RecoverToNKit.

Feature Overview

The features in this section are used across the conversions in NKit. They are described here along with the configuration items that they use. The configuration items are listed in the section below.

Recovery Files

The concept of recovery files is that by saving the bare minimum of information from Redump good images. NKit can recover many modified images.

GameCube other tools that modify these images scrub and move (sometimes reorder) the files in the filesystem. NKit recovery files are the appldr.bin (a handful are used across all images) and fst.bin (unique per image, NKit stores some header info in these files also).
Wii - other tools remove unused blocks or scrub them by wiping unused blocks with 00 or FF bytes. It is common for Non-Data Partitions are also removed to save space. NKit recovery files consist of the channel and update partitions.

Brute Force Recovery

Dat Files

CRC Matching

Mask Renaming

Conversions

NKit can convert to and from various formats. To simplify recovering and converting to and from the formats a multi pass system will process the image through the various stages.

Configuration

The NKit.dll uses a configuration file name NKit.dll.config. This file contains base configuration. There are multiple sections or which the first 3 contain items the user will be most interested in editing:-

<appSettings> - General settings
<gamecube> - GameCube Redump and recovery settings. Including some lookup data
<wii> - Wii Redump and recovery settings. Including some lookup data

AppSettings

Item	Description
SearchSubfolders	Search sub folders when finding images to process
WaitForKeyAfterProcessing	Wait for newline entry before exiting a commandline app
Path	All paths are relative to the working folder - global substitutions %exe=exe path, %pth=Path value. A base path that can be used in other paths with %pth, paths can be absolute or relative to the working folder - not supported by apps above
TempPath	Temp working folder, absolute or relative to current working directory - best to be the same drive as the output
SummaryLog	Summary log path, a log of all conversions with image details - check this file before deleting source files etc
EnableSummaryLog	Turn the SummaryLog on or off
FullVerify	Verify the output file by converting it back to iso in memory to ensure the CRC is valid
CalculateHashes	Calculates additional MD5 and SHA1 hashes. This is required to output them in to the summary log or use them in the rename file masks
NkitFormat	Save NKit as iso or gcz
NkitReencode	Force a full reencode when converting nkit to nkit. If false when converting nkit.iso to nkit.gcz, only the gcz coversion is performed
MaskRename	Rename output images to the masks in the gamecube and wii config sections, else use the source path and filename
TestMode	Convert images, but delete them when complete - View SummaryLog for results
RecoveryMatchFailDelete	Recovery Only - delete failed matches, false will rename them to the FailMatchRenameToMask - they may be corrupt
DeleteSource	Delete the source file if FullVerify returns VerifySuccess (FullVerify setting must be true) TestMode=true cancels this setting
OutputLevel	Logging level when processing 0=Silent, 1=Info, 2=Detailed
DatPathNameGameTdbMask	Path and mask to GameTDB file - latest file is used

GameCube / Wii

GameCube and Wii share a log of the same settings. Depending on which image is being processed the corresponding section is referenced.

Item	Description
DatPathRedumpMask	Path and mask to redump dat file - latest file is used
DatPathCustomMask	Path and mask to custom dat file - latest file is used
RedumpMatchRenameToMask	Used when an output file's CRC matches and entry in the Redump dat. Move and Rename the file to this mask.
CustomMatchRenameToMask	Used when an output file's CRC matches and entry in the Custom dat. Move and Rename the file to this mask.
MatchFailRenameToMask	Used when an output file's CRC fails to match any dat. Move and Rename the file to this mask.
RecoveryFilesPath	Path to Redump recovery files. Recovery extracted files are stored here if the file's CRC is known.
OtherRecoveryFilesPath	Path to Other recovery files. Recovery extracted files are stored here if the file's CRC is not known.
NkitUpdatePartitionRemoval*	Remove the update partition when converting to nkit, the CRC of the removed partition is stored in the NKit header for restoration.
NkitRecoveryFilesPath*	Path to Wii NKit extracted update partition when extracted by ConvertToNKit with NkitUpdatePartitionRemoval set to true

* Wii section only

@@ Line 28: / Line 28: @@
 ===Feature Overview===
+The features in this section are used across the conversions in NKit. They are described here along with the configuration items that they use. The configuration items are listed in the section below.
 ====Recovery Files====
+The concept of recovery files is that by saving the bare minimum of information from Redump good images. NKit can recover many modified images.
+* '''GameCube''' other tools that modify these images scrub and move (sometimes reorder) the files in the filesystem. NKit recovery files are the appldr.bin (a handful are used across all images) and fst.bin (unique per image, NKit stores some header info in these files also).
+* '''Wii''' - other tools remove unused blocks or scrub them by wiping unused blocks with 00 or FF bytes. It is common for Non-Data Partitions are also removed to save space. NKit recovery files consist of the channel and update partitions.
 ====Brute Force Recovery====
 ====Dat Files====
 ====CRC Matching====
 ====Mask Renaming====
 ===Conversions===