CCISharp 1.0.1

CCISharp

CCISharp is a pure-managed C# library for reading and writing CCI ("CCIM", Cerbios Compressed Image) original-Xbox disc images. It is an independent MIT implementation of the format specified by Team-Resurgent/libCCI (FORMAT.md).

CCI is the compressed disc-image format used by the Cerbios BIOS and created by Repackinator/XboxToolkit. Each 2048-byte sector is either stored raw or compressed as a single LZ4 block, with a random-access index.

Features

• Read and write single-part .cci containers.
• Split sets (name.1.cci … name.9.cci) with transparent stitching.
• Random access to any sector, plus a seekable read-only Stream.
• One-call extraction to a raw ISO with progress, cancellation and preallocation.
• Validation of headers, indexes and (optionally) every sector.
• Pure managed, no native dependencies, trimmable and AOT-compatible.
• Targets net8.0, net9.0 and net10.0.

Requirements

Installation

dotnet add package CCISharp

Quick start

Read a CCI image

using CCISharp;

CciError error = CciFile.Open(@"C:\games\game.cci", out CciFile? cci);
if (error != CciError.None || cci is null)
{
    Console.Error.WriteLine(error);
    return;
}

using (cci)
{
    Console.WriteLine($"{cci.TotalSectors} sectors, {cci.Length} bytes");
    Console.WriteLine($"{cci.Slices.Count} part(s)");

    byte[] sector = new byte[CciFormat.SectorSize];
    cci.ReadSector(0, sector);
}

Extract to ISO

using CciFile cci = CciFile.OpenOrThrow(@"C:\games\game.cci");
CciError error = cci.ExtractToIso(@"C:\games\game.iso", new CciExtractOptions
{
    Overwrite = false,
    Progress = new Progress<CciProgress>(p =>
        Console.WriteLine($"{p.SectorsDone}/{p.TotalSectors} sectors")),
});

Stream and seek

using CciFile cci = CciFile.OpenOrThrow(@"C:\games\game.1.cci");
using Stream stream = cci.OpenStream();

stream.Seek(0x10000, SeekOrigin.Begin);
byte[] buffer = new byte[8192];
int read = stream.Read(buffer);

Create a CCI

CciError error = CciWriter.Compress(
    @"C:\games\game.iso",
    @"C:\games\game.cci",
    new CciWriteOptions
    {
        Level = 9,                 // 0 = store, 1..9 = speed/ratio presets
        SplitBytes = CciFormat.DefaultSplitBytes,
        Overwrite = false,
    });

With SplitBytes > 0, output parts are written as game.1.cci, game.2.cci, …; a single-part image is written as game.cci.

Validate

using CciFile cci = CciFile.OpenOrThrow(@"C:\games\game.cci");
CciError error = cci.Validate(deep: true, out CciValidationReport? report);
if (error != CciError.None)
{
    foreach (CciValidationIssue issue in report!.Issues)
        Console.Error.WriteLine($"{issue.PartIndex}:{issue.Sector}: {issue.Reason}");
}

Split sets

A split image is a sequence of independent CCI containers, each covering a contiguous range of sectors. Open the first part (game.1.cci) and the library discovers the remaining parts (game.2.cci … game.9.cci), exactly like the reference implementation.

• game.cci is treated as a single-part image.
• game.1.cci triggers split discovery.
• Parts are concatenated by sector range, not by file size.

Format notes

The on-disk format is documented in FORMAT.md. Key facts:

• 32-byte little-endian header, magic CCIM (0x4D494343).
• 2048-byte logical sectors.
• Index of sectors + 1 uint32 entries at the end of each part.
• Bit 31 of an index entry marks LZ4; the rest is offset >> 2.
• Compressed block layout: [pad][LZ4 block][zero padding].
• Version 1, index alignment 2.

CCISharp's encoder is compatible with the format but is not byte-identical to libCCI/Repackinator output (different LZ4 encoders). Any conforming LZ4 block is accepted by readers.

A part's index is capped at 64 MiB (~34 GiB of sectors). Valid parts split at ~4 GiB and need at most ~8 MiB, so the cap only rejects corrupt or hostile headers; oversized indexes return CciError.InvalidIndex without allocating.

Error handling

Public APIs return CciError. CciError.None means success. Argument errors (null paths, negative sizes) throw standard .NET argument exceptions. CciFile.OpenOrThrow is a convenience wrapper that throws CciException with the error code and message.

Building

dotnet build CCISharp.sln -c Release
dotnet test CCISharp.Tests/CCISharp.Tests.csproj -c Release

The repository uses MinVer; release tags are v1.0.0, v1.0.1, ….

Interoperability

Both directions are verified for every push by the Windows CI job, using the unmodified reference libCCI binaries checked in under CCISharp.Tests/references/libCCI (the tests fail rather than skip when the tools are missing):

cci_encode game.iso game        # -> game.cci
cci_extract game.cci out.iso    # -> raw ISO
cci_info game.cci               # -> sector count / size

The References/libCCI-0.1.0-1b0087e copy used during development is for testing only and is not part of this package.

License

MIT. See LICENSE and THIRD-PARTY-NOTICES.md. The CCI format specification comes from Team-Resurgent/libCCI (GPL-2.0-or-later); no libCCI code is included in this MIT package.