KevInc.UbiArt.FileSystem 0.3.2

KevInc.UbiArt

KevInc.UbiArt is a set of .NET 10 libraries for reading, writing, resolving, and rendering game-neutral UbiArt resources. The packages cover IPK archives, layered filesystems, legacy serialization, scene graphs and cinematics, RAKI audio, and TEX textures.

Packages

Install only the packages needed by your application:

dotnet add package KevInc.UbiArt.Ipk
dotnet add package KevInc.UbiArt.FileSystem
dotnet add package KevInc.UbiArt.Serialization
dotnet add package KevInc.UbiArt.Cinematics
dotnet add package KevInc.UbiArt.Raki
dotnet add package KevInc.UbiArt.Texture

Architecture

The generic scene pipeline is intentionally one-way:

caller-selected root and game extensions
                    |
                    v
       document and resource loading
                    |
                    v
       runtime and tape evaluation
                    |
          +---------+---------+
          |                   |
          v                   v
 semantic analysis      CPU/Vulkan rendering

KevInc.UbiArt.Cinematics is currently the compatibility package for the scene-graph, IO, runtime, and rendering APIs. Those responsibilities are separated internally and do not depend on a particular game, edition layout, output format, or filename policy.

Resource access goes through IUbiArtResourceSource. LayeredUbiArtResourceSource adapts UbiArtLayeredFileSystem, while custom sources can provide resources from another store. Scene readers additionally use IUbiArtSceneReadContext, which separates the caller's semantic engine version from the raw binary serialization revision.

Examples

Extract an IPK archive

using KevInc.UbiArt.Ipk;

UbiArtIpkParser parser = new("bundle.ipk", "bundle");
parser.Parse();

Resolve a resource from layered UbiArt content

using KevInc.UbiArt.FileSystem;

UbiArtLayeredFileSystem fileSystem = new(new UbiArtLayeredFileSystemOptions
{
    InputPath = "bundle_nx.ipk",
    Platform = UbiArtPlatform.NX
});
fileSystem.Initialize();

IUbiArtResourceSource resources = new LayeredUbiArtResourceSource(fileSystem);
if (resources.TryResolve("world/maps/song/songdesc.tpl", out CookedFile? songDesc))
{
    using Stream stream = resources.Open(songDesc);
    // Parse the resource required by your application.
}

The layered filesystem owns lookup order. Callers ask for the authored path instead of recursively scanning archives or guessing cooked-cache filenames.

Load a caller-selected scene

using KevInc.UbiArt.Cinematics.Core;
using KevInc.UbiArt.Cinematics.Scene;
using KevInc.UbiArt.Cinematics.Serialization;
using KevInc.UbiArt.FileSystem;
using Microsoft.Extensions.Logging.Abstractions;

public sealed class SceneReadContext(
    IUbiArtResourceSource resources,
    int engineVersion,
    int serializationVersion) : IUbiArtSceneReadContext
{
    public int EngineVersion { get; } = engineVersion;
    public int SerializationVersion { get; } = serializationVersion;

    public bool TryResolve(string path, out CookedFile? resource) =>
        resources.TryResolve(path, out resource);

    public Stream Open(CookedFile resource) => resources.Open(resource);

    public IReadOnlyList<CookedFile> Enumerate(string folder, string pattern = "*") =>
        resources.Enumerate(folder, pattern);
}

Using the resources source from the previous example:

SceneReadContext context = new(resources, engineVersion: 2020, serializationVersion: 18);
CinematicScene scene = CinematicSceneDocumentReader.Read(
    context,
    "world/maps/song/song_main_scene.isc",
    NullLogger.Instance);

The root path and version values are application decisions. The reader resolves binary or XML scene data and referenced resources without knowing the caller's game layout.

Serialize a legacy binary model

using KevInc.UbiArt.Serialization.Legacy;

byte[] bytes = LegacyBinarySerializer.Serialize(model);
MyModel decoded = LegacyBinarySerializer.Deserialize<MyModel>(
    bytes,
    new LegacyBinarySerializerContext(2017));

Models can use the serializer's type-ID, condition, switch, byte-count, and padding attributes to describe revisioned layouts.

Read RAKI audio metadata

using KevInc.UbiArt.Raki;

await using FileStream input = File.OpenRead("audio.wav.ckd");
RakiAudioHeader header = RakiAudioReader.ReadHeader(input);

Decode a TEX texture with ImageSharp

using KevInc.UbiArt.Texture;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

UbiArtTextureImageSharpConfiguration.RegisterTextureFormat();
using Image<Bgra32> image = Image.Load<Bgra32>("texture.tga.ckd");

Rendering behavior

The cinematic pipeline shares scene, tape, transform, material, camera, and draw-order evaluation between its CPU and Vulkan paths. It supports graph-rendered Pleo video, including authored crop/scale transforms and material-defined stacked-alpha layouts.

For simple single-video graphs, semantic analysis can prove that a direct, native-crop, or scale/crop path is equivalent to rendering. The analyzer returns authored geometry; the consuming application remains responsible for choosing codecs, dimensions, commands, and output names. Parse failures or unsupported visual behavior do not silently authorize copying a source video.

Build and test

./run.ps1

Create local NuGet packages:

./run.ps1 -Configuration Release -Pack

Packages are written to artifacts/packages.

The tests cover archive round-tripping and layer priority, legacy serializer revisions, scene and tape parsing, resource resolution, materials and atlases, runtime transforms, particles and Pleo composition, semantic video analysis, and CPU/Vulkan rendering behavior.

Versioning

The repository uses Nerdbank.GitVersioning. Package versions come from version.json and Git metadata.

License

This repository is licensed under GPL-3.0-only unless a package explicitly states otherwise.