Assembles a deterministic Nintendo DS Image from typed Programs, metadata, Banner, logo, and NitroFS tree. More...

Public Member Functions
	NdsImageBuilder ()
	Establishes deterministic identity defaults and an explicit empty NitroFS root for a new Image.
NdsImageBuilder	AddOverlay (NdsOverlayDefinition overlay)
	Adds an Overlay whose private Allocation receives a File ID after all named NitroFS files.
NdsImageBuilder	SetNintendoLogo (ReadOnlySpan< byte > data)
	Copies the 156-byte encoded cartridge logo block without embedding or sourcing proprietary assets.
ValueTask< NdsImageBuildResult >	WriteAsync (Stream destination, NdsImageBuildOptions? options=null, CancellationToken cancellationToken=default)
	Writes the complete recipe to a caller-owned random-access stream and optionally verifies it by reopening.
async ValueTask< NdsImageBuildResult >	WriteAsync (string path, NdsImageBuildOptions? options=null, CancellationToken cancellationToken=default)
	Builds beside a host destination and moves the verified temporary image into place only after success.
async ValueTask< byte[]>	BuildAsync (NdsImageBuildOptions? options=null, CancellationToken cancellationToken=default)
	Materializes a complete deterministic image for tests, small tools, or APIs that require one contiguous buffer.

Static Public Member Functions
static ValueTask< NdsImageBuilder >	FromImageAsync (NdsImage image, CancellationToken cancellationToken=default)
	Copies a parsed DS or DSi Image into a detached Build Recipe suitable for structural filesystem changes.

Properties
NdsImageKind	Kind = NdsImageKind.NintendoDs `[get, set]`
	Selects DS, DSi-enhanced, or DSi-exclusive header and execution semantics for the complete recipe.
string	Title = string.Empty `[get, set]`
	Controls the padded 12-byte printable-ASCII label written at the beginning of the header.
string	GameCode = "####" `[get, set]`
	Controls the exact four-character printable-ASCII product code required by the cartridge header.
string	MakerCode = "00" `[get, set]`
	Controls the exact two-character printable-ASCII publisher identifier.
byte	Version `[get, set]`
	Controls the publisher-defined software revision byte, independently from format versions.
byte	EncryptionSeedSelect `[get, set]`
	Preserves the raw cartridge encryption seed-selection byte used by secure-area protocols.
byte	RegionCode `[get, set]`
	Controls the hardware-dependent region byte without interpreting reserved bits.
byte	AutoStart `[get, set]`
	Controls the complete boot-policy byte at header offset `0x1F`.
uint	NormalCardControl `[get, set]`
	Preserves ROM-control timing and flags used for ordinary cartridge transfers.
uint	SecureCardControl `[get, set]`
	Preserves ROM-control timing and flags used during secure cartridge transfers.
ushort	SecureTransferTimeout `[get, set]`
	Preserves the timeout applied to secure-area transfers.
uint	Arm9AutoLoad `[get, set]`
	Preserves the ARM9 SDK autoload-list address used during runtime initialization.
uint	Arm7AutoLoad `[get, set]`
	Preserves the ARM7 SDK autoload-list address used during runtime initialization.
ulong	SecureDisable `[get, set]`
	Preserves the raw 64-bit secure-area disable token across structural rebuilds.
NdsProgramDefinition?	Arm9 `[get, set]`
	Supplies the required primary processor payload and its runtime addresses.
NdsProgramDefinition?	Arm7 `[get, set]`
	Supplies the required secondary processor payload and its runtime addresses.
NdsProgramDefinition?	Arm9i `[get, set]`
	Supplies the required ARM9i payload for a DSi recipe; its single header address serves as load and entry.
NdsProgramDefinition?	Arm7i `[get, set]`
	Supplies the required ARM7i payload for a DSi recipe; its single header address serves as load and entry.
NdsDsiBuildMetadata?	DsiMetadata `[get, set]`
	Supplies DSi service, title, storage, memory-bank, modcrypt, and integrity policy. It must be present exactly when Kind selects an extended image.
NdsFileSystemBuilder	FileSystem `[get]`
	Provides structural NitroFS operations whose stable snapshot becomes the generated FNT and FAT.
NdsBanner?	Banner `[get, set]`
	Supplies optional pre-checksummed menu metadata; static and animated supported versions remain lossless.
IReadOnlyList< NdsOverlayDefinition >	Arm9Overlays `[get]`
	Exposes ARM9 Overlay definitions in the exact order used by the generated table.
IReadOnlyList< NdsOverlayDefinition >	Arm7Overlays `[get]`
	Exposes ARM7 Overlay definitions in the exact order used by the generated table.

Detailed Description

Assembles a deterministic Nintendo DS Image from typed Programs, metadata, Banner, logo, and NitroFS tree.

This builder describes a new image rather than editing an existing one. Every byte-bearing setter copies caller data, and repeated writes from unchanged state use identical ordering, offsets, padding, and checksums. DSi recipes require both DSi-mode Programs and explicit extended metadata so a unit-code change can never silently emit a partially configured image. Their integrity policy distinguishes homebrew compatibility hashes from absent retail authentication.

Definition at line 13 of file NdsImageBuilder.cs.

Constructor & Destructor Documentation

◆ NdsImageBuilder()

NdsForge.NdsImageBuilder.NdsImageBuilder ( )

inline

Establishes deterministic identity defaults and an explicit empty NitroFS root for a new Image.

Definition at line 25 of file NdsImageBuilder.cs.

Member Function Documentation

◆ AddOverlay()

NdsImageBuilder NdsForge.NdsImageBuilder.AddOverlay ( NdsOverlayDefinition overlay )

inline

Adds an Overlay whose private Allocation receives a File ID after all named NitroFS files.

Parameters

overlay Immutable definition whose payload is already independent from caller buffers.

Returns: The same builder for fluent recipe construction.

Definition at line 105 of file NdsImageBuilder.cs.

◆ BuildAsync()

async ValueTask< byte[]> NdsForge.NdsImageBuilder.BuildAsync	(	NdsImageBuildOptions?	options = null,
		CancellationToken	cancellationToken = default )

inline

Materializes a complete deterministic image for tests, small tools, or APIs that require one contiguous buffer.

Parameters

options	Deterministic Layout settings, or `null` for defaults.
cancellationToken	Cancels writing or reopen verification.

Returns: Every generated Image byte including alignment padding.

Definition at line 205 of file NdsImageBuilder.cs.

◆ FromImageAsync()

ValueTask< NdsImageBuilder > NdsForge.NdsImageBuilder.FromImageAsync	(	NdsImage	image,
		CancellationToken	cancellationToken = default )

inlinestatic

Copies a parsed DS or DSi Image into a detached Build Recipe suitable for structural filesystem changes.

All Programs, files, private Overlay payloads, and footer bytes are materialized. The returned builder no longer depends on the source Image and remains usable after that Image is disposed.

Parameters

image	Live Image whose logical components and relationships are imported.
cancellationToken	Cancels potentially large payload reads before a partial recipe is returned.

Returns: A deterministic builder initialized from source semantics rather than source physical Layout.

Definition at line 120 of file NdsImageBuilder.cs.

◆ SetNintendoLogo()

NdsImageBuilder NdsForge.NdsImageBuilder.SetNintendoLogo ( ReadOnlySpan< byte > data )

inline

Copies the 156-byte encoded cartridge logo block without embedding or sourcing proprietary assets.

Parameters

data	Exactly the native bytes stored at header offsets `0xC0`-`0x15B`.

Returns: The same builder for fluent recipe construction.

Exceptions

ArgumentException The encoded logo is not exactly 156 bytes.

Definition at line 129 of file NdsImageBuilder.cs.

◆ WriteAsync() [1/2]

ValueTask< NdsImageBuildResult > NdsForge.NdsImageBuilder.WriteAsync	(	Stream	destination,
		NdsImageBuildOptions?	options = null,
		CancellationToken	cancellationToken = default )

inline

Writes the complete recipe to a caller-owned random-access stream and optionally verifies it by reopening.

Parameters

destination	Readable, writable, seekable stream truncated to the generated image and left open.
options	Deterministic Layout settings, or `null` for defaults.
cancellationToken	Cancels component writes or verification before a successful result is returned.

Returns: Final Regions, sizes, and File ID count.

Definition at line 145 of file NdsImageBuilder.cs.

◆ WriteAsync() [2/2]

async ValueTask< NdsImageBuildResult > NdsForge.NdsImageBuilder.WriteAsync	(	string	path,
		NdsImageBuildOptions?	options = null,
		CancellationToken	cancellationToken = default )

inline

Builds beside a host destination and moves the verified temporary image into place only after success.

Parameters

path	Output path normalized once before any directory or temporary-file operation.
options	Layout, verification, and explicit existing-destination policy.
cancellationToken	Cancels writing or verification while leaving an existing destination untouched.

Returns: Final Regions, sizes, and File ID count.

Definition at line 156 of file NdsImageBuilder.cs.

Property Documentation

◆ Arm7

NdsProgramDefinition? NdsForge.NdsImageBuilder.Arm7

getset

Supplies the required secondary processor payload and its runtime addresses.

Definition at line 76 of file NdsImageBuilder.cs.

◆ Arm7AutoLoad

uint NdsForge.NdsImageBuilder.Arm7AutoLoad

getset

Preserves the ARM7 SDK autoload-list address used during runtime initialization.

Definition at line 67 of file NdsImageBuilder.cs.

◆ Arm7i

NdsProgramDefinition? NdsForge.NdsImageBuilder.Arm7i

getset

Supplies the required ARM7i payload for a DSi recipe; its single header address serves as load and entry.

Definition at line 82 of file NdsImageBuilder.cs.

◆ Arm7Overlays

IReadOnlyList<NdsOverlayDefinition> NdsForge.NdsImageBuilder.Arm7Overlays

get

Exposes ARM7 Overlay definitions in the exact order used by the generated table.

Definition at line 100 of file NdsImageBuilder.cs.

◆ Arm9

NdsProgramDefinition? NdsForge.NdsImageBuilder.Arm9

getset

Supplies the required primary processor payload and its runtime addresses.

Definition at line 73 of file NdsImageBuilder.cs.

◆ Arm9AutoLoad

uint NdsForge.NdsImageBuilder.Arm9AutoLoad

getset

Preserves the ARM9 SDK autoload-list address used during runtime initialization.

Definition at line 64 of file NdsImageBuilder.cs.

◆ Arm9i

NdsProgramDefinition? NdsForge.NdsImageBuilder.Arm9i

getset

Supplies the required ARM9i payload for a DSi recipe; its single header address serves as load and entry.

Definition at line 79 of file NdsImageBuilder.cs.

◆ Arm9Overlays

IReadOnlyList<NdsOverlayDefinition> NdsForge.NdsImageBuilder.Arm9Overlays

get

Exposes ARM9 Overlay definitions in the exact order used by the generated table.

Definition at line 97 of file NdsImageBuilder.cs.

◆ AutoStart

byte NdsForge.NdsImageBuilder.AutoStart

getset

Controls the complete boot-policy byte at header offset 0x1F.

Definition at line 52 of file NdsImageBuilder.cs.

◆ Banner

NdsBanner? NdsForge.NdsImageBuilder.Banner

getset

Supplies optional pre-checksummed menu metadata; static and animated supported versions remain lossless.

Definition at line 94 of file NdsImageBuilder.cs.

◆ DsiMetadata

NdsDsiBuildMetadata? NdsForge.NdsImageBuilder.DsiMetadata

getset

Supplies DSi service, title, storage, memory-bank, modcrypt, and integrity policy. It must be present exactly when Kind selects an extended image.

Definition at line 88 of file NdsImageBuilder.cs.

◆ EncryptionSeedSelect

byte NdsForge.NdsImageBuilder.EncryptionSeedSelect

getset

Preserves the raw cartridge encryption seed-selection byte used by secure-area protocols.

Definition at line 46 of file NdsImageBuilder.cs.

◆ FileSystem

NdsFileSystemBuilder NdsForge.NdsImageBuilder.FileSystem

get

Provides structural NitroFS operations whose stable snapshot becomes the generated FNT and FAT.

Definition at line 91 of file NdsImageBuilder.cs.

◆ GameCode

string NdsForge.NdsImageBuilder.GameCode = "####"

getset

Controls the exact four-character printable-ASCII product code required by the cartridge header.

Definition at line 37 of file NdsImageBuilder.cs.

◆ Kind

NdsImageKind NdsForge.NdsImageBuilder.Kind = NdsImageKind.NintendoDs

getset

Selects DS, DSi-enhanced, or DSi-exclusive header and execution semantics for the complete recipe.

Definition at line 31 of file NdsImageBuilder.cs.

◆ MakerCode

string NdsForge.NdsImageBuilder.MakerCode = "00"

getset

Controls the exact two-character printable-ASCII publisher identifier.

Definition at line 40 of file NdsImageBuilder.cs.

◆ NormalCardControl

uint NdsForge.NdsImageBuilder.NormalCardControl

getset

Preserves ROM-control timing and flags used for ordinary cartridge transfers.

Definition at line 55 of file NdsImageBuilder.cs.

◆ RegionCode

byte NdsForge.NdsImageBuilder.RegionCode

getset

Controls the hardware-dependent region byte without interpreting reserved bits.

Definition at line 49 of file NdsImageBuilder.cs.

◆ SecureCardControl

uint NdsForge.NdsImageBuilder.SecureCardControl

getset

Preserves ROM-control timing and flags used during secure cartridge transfers.

Definition at line 58 of file NdsImageBuilder.cs.

◆ SecureDisable

ulong NdsForge.NdsImageBuilder.SecureDisable

getset

Preserves the raw 64-bit secure-area disable token across structural rebuilds.

Definition at line 70 of file NdsImageBuilder.cs.

◆ SecureTransferTimeout

ushort NdsForge.NdsImageBuilder.SecureTransferTimeout

getset

Preserves the timeout applied to secure-area transfers.

Definition at line 61 of file NdsImageBuilder.cs.

◆ Title

string NdsForge.NdsImageBuilder.Title = string.Empty

getset

Controls the padded 12-byte printable-ASCII label written at the beginning of the header.

Definition at line 34 of file NdsImageBuilder.cs.

◆ Version

byte NdsForge.NdsImageBuilder.Version

getset

Controls the publisher-defined software revision byte, independently from format versions.

Definition at line 43 of file NdsImageBuilder.cs.

The documentation for this class was generated from the following file:

src/NdsForge/Building/NdsImageBuilder.cs

NdsForge.NET 1.0.1 Read, validate, edit, compare, and build Nintendo DS and DSi images from .NET

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ NdsImageBuilder()

Member Function Documentation

◆ AddOverlay()

◆ BuildAsync()

◆ FromImageAsync()

◆ SetNintendoLogo()

◆ WriteAsync() [1/2]

◆ WriteAsync() [2/2]

Property Documentation

◆ Arm7

◆ Arm7AutoLoad

◆ Arm7i

◆ Arm7Overlays

◆ Arm9

◆ Arm9AutoLoad

◆ Arm9i

◆ Arm9Overlays

◆ AutoStart

◆ Banner

◆ DsiMetadata

◆ EncryptionSeedSelect

◆ FileSystem

◆ GameCode

◆ Kind

◆ MakerCode

◆ NormalCardControl

◆ RegionCode

◆ SecureCardControl

◆ SecureDisable

◆ SecureTransferTimeout

◆ Title

◆ Version