# Nino

> Nino is a general-purpose, high-performance binary serializer for C# and .NET. A Roslyn source generator writes the serialization code for every [NinoType] at compile time, so there is no reflection and no runtime code generation, and serializing into a reused buffer allocates nothing. Use it wherever .NET code turns objects into bytes and back: RPC and network protocols, microservices, message queues and event streams, caches, files and other storage, inter-process communication and data pipelines. The runtime targets netstandard2.0, netstandard2.1, net8.0 and net10.0, and Nino also supports Unity 2022.3+ (Mono, IL2CPP, HybridCLR), Godot 4 (.NET), ASP.NET Core (Nino.AspNetCore), browsers and Node through generated TypeScript or .NET WebAssembly, and Go and Rust through generated code (Nino.Codegen); every platform writes the same bytes. MIT licensed.

- Install: `dotnet add package Nino --prerelease` (NuGet: https://www.nuget.org/packages/Nino); Unity: `openupm add com.jasonxudeveloper.nino`
- Optional packages: `Nino.Immutable` (System.Collections.Immutable types), `Nino.AspNetCore` (ASP.NET Core MVC formatters and Minimal API bodies for `application/x-nino`) and `Nino.Codegen` (TypeScript, Go and Rust types and codecs, generated after each build; the same as the `nino-gen` tool, `Nino.Codegen.Tool`)
- v4 is still a prerelease on NuGet: without `--prerelease`, NuGet installs the stable 3.9.x, a test build of v4 features that is not compatible with v4.
- Usage: mark a class, struct, record or interface with `[NinoType]`, then call `NinoSerializer.Serialize(value)` and `NinoDeserializer.Deserialize<T>(bytes)`
- Performance: up to 6.83× faster serialization than MemoryPack in the same benchmark run; see [Nino vs MemoryPack](https://nino.xgamedev.net/en/docs/v4/vs-memorypack)
- Source code and issues: https://github.com/JasonXuDeveloper/Nino (MIT license)
- These docs describe Nino v4, the current version. Its binary format is not compatible with v3.
- Full text of the v4 docs: [llms-full.txt](https://nino.xgamedev.net/llms-full.txt); Chinese: [llms.zh.txt](https://nino.xgamedev.net/llms.zh.txt)
- Each page below is also served as HTML at the same URL without `.md`.

## Overview

- [Introduction](https://nino.xgamedev.net/en/docs/v4.md): Nino is a general-purpose, high-performance binary serializer for C# and .NET: source-generated and zero-GC, for services, messaging, caching and storage, plus Unity.
- [What's New in v4](https://nino.xgamedev.net/en/docs/v4/whats-new.md): Everything Nino v4 adds over v3: a rewritten runtime and incremental generator, keyed and version-tolerant types, reference tracking, pooling, safe reads of untrusted data, many more built-in types, the same bytes on every platform, ASP.NET Core formatters and generated TypeScript.
- [Changelog](https://nino.xgamedev.net/en/docs/v4/changelog.md): What changed in each Nino v4 release: new APIs, fixes, and every change to the bytes Nino writes, newest first.
- [Nino vs MemoryPack](https://nino.xgamedev.net/en/docs/v4/vs-memorypack.md): An honest comparison with the fastest C# binary serializer we know: where Nino v4 is ahead, and where MemoryPack still is.
- [v3 vs v4](https://nino.xgamedev.net/en/docs/v4/v3-vs-v4.md): Nino v3 and v4 side by side: features, build time, generated code size and runtime performance, measured on the same machine.
- [FAQ](https://nino.xgamedev.net/en/docs/v4/faq.md): Short answers about Nino: what it is, how to install it, which platforms it supports, how fast it is, when to use something else, and how to fix the errors people run into most.

## Getting Started

- [Quick Start](https://nino.xgamedev.net/en/docs/v4/start.md): Install Nino v4 in a .NET, Unity or Godot project and serialize your first type.
- [Serialize and Deserialize](https://nino.xgamedev.net/en/docs/v4/basic.md): Serialize and deserialize with NinoSerializer and NinoDeserializer, reuse buffers and instances, and handle runtime types.
- [Migrating from v3](https://nino.xgamedev.net/en/docs/v4/migration.md): Upgrade a Nino v3 project to v4 step by step: package changes, renamed attributes and APIs, before/after code, and converting data written by v3.

## Defining Types

- [Defining Types](https://nino.xgamedev.net/en/docs/v4/defining-types.md): Mark classes, structs, records and interfaces with [NinoType], and choose which members are serialized and in what order.
- [Custom Constructors](https://nino.xgamedev.net/en/docs/v4/constructors.md): How Nino creates instances when deserializing: parameterless and [NinoConstructor] constructors, [NinoFactory] methods, records, init-only and required members, and structs.
- [Supported Types](https://nino.xgamedev.net/en/docs/v4/types.md): Every type Nino can serialize: primitives, strings, tuples, BCL types such as BigInteger and Uri, collections, immutable collections and your own collection types.
- [Polymorphism](https://nino.xgamedev.net/en/docs/v4/polymorphism.md): Base classes, interfaces and abstract classes: values are read back as their runtime type.

## Features

- [Evolving Your Data](https://nino.xgamedev.net/en/docs/v4/evolving-data.md): Positional, version-tolerant and keyed formats: what each one lets you change after data has been written.
- [Reference Tracking](https://nino.xgamedev.net/en/docs/v4/reference-tracking.md): Serialize object graphs with shared references and cycles: opt in per type; types that don't opt in pay nothing.
- [Reuse Deserialization and Pooling](https://nino.xgamedev.net/en/docs/v4/pooling.md): Reuse deserialization in Nino: fill existing objects, lists and dictionaries in place, rent from [NinoPooled] pools and recycle dropped instances, with zero allocations.
- [Custom Formatters](https://nino.xgamedev.net/en/docs/v4/custom-formatters.md): Write a Nino formatter for a member ([NinoCustomFormatter]) or a type Nino does not support ([assembly: NinoFormatter], including generic types), using the Writer and Reader APIs.
- [Untrusted Data](https://nino.xgamedev.net/en/docs/v4/security.md): What Nino checks when it reads data from a network peer or a user's file: one NinoDataException for invalid input, the bytes it rejects, the depth, length and hash-collision limits in NinoSettings, and NinoSettings.Untrusted.

## Guides

- [Best Practices](https://nino.xgamedev.net/en/docs/v4/best-practices.md): Handling messages without allocating, then the choices to make before Nino data ships: the format of each type, sealed classes and common bases, buffers and reuse, stored data, untrusted input and project setup.
- [Performance Guide](https://nino.xgamedev.net/en/docs/v4/performance.md): How Nino v4 gets its speed, and what you can do to keep it: interceptors, raw structs, buffer reuse, threading.
- [Advanced Guides](https://nino.xgamedev.net/en/docs/v4/advanced.md): Guides for using Nino in real systems: hot paths, networking and RPC, ASP.NET Core, TypeScript, Go, Rust and browser clients, message queues, caching, persistence and storage, plus Unity, HybridCLR and Godot.

## Hot Paths and I/O

- [High-Performance Serialization](https://nino.xgamedev.net/en/docs/v4/advanced/high-performance.md): Every lever for Nino's speed, when to use it and what it costs: buffer writers, exact-size arrays, Writer and Reader, reuse deserialization, pools, raw and fixed-size structs, formats, sealed and polymorphic types, collections, strings, custom formatters, startup and measuring.
- [Zero-Allocation Patterns](https://nino.xgamedev.net/en/docs/v4/advanced/zero-allocation.md): Copy-paste recipes for a 0 B steady state: per-owner and caller-provided buffers, batches, receive loops, reused instances, framed streams, memory-mapped records, an allocation test and the checklist.
- [Streams, Async, Callbacks and Compression](https://nino.xgamedev.net/en/docs/v4/advanced/streams.md): Short helpers over Nino's buffer and span APIs: length-prefixed frames on a Stream, async reads and writes, ReadOnlySequence input, before/after hooks, and Brotli or GZip compression.

## Use Cases

- [Network Layer](https://nino.xgamedev.net/en/docs/v4/advanced/networking.md): Build a message protocol on Nino: framing, polymorphic messages, System.IO.Pipelines, pooling per connection, rolling upgrades.
- [ASP.NET Core](https://nino.xgamedev.net/en/docs/v4/advanced/aspnetcore.md): Nino.AspNetCore reads and writes application/x-nino bodies in ASP.NET Core: MVC input and output formatters, NinoBody<T> parameters and NinoResults for Minimal APIs, straight from the request and response pipes.
- [Browser and JavaScript Clients](https://nino.xgamedev.net/en/docs/v4/advanced/browser.md): Use Nino from browser JavaScript or TypeScript: compile your [NinoType] types into a .NET browser-wasm module, call it through [JSExport], and exchange byte-identical data with a .NET server.
- [Message Queues and Event Streams](https://nino.xgamedev.net/en/docs/v4/advanced/message-queues.md): Nino payloads on Kafka and other brokers: polymorphic event types, serializers, batching, telemetry and tick streams, and topics that outlive a deployment.
- [Caching](https://nino.xgamedev.net/en/docs/v4/advanced/caching.md): Nino as the value format of a cache: Redis and other distributed caches, IDistributedCache and HybridCache, in-process caches of serialized blobs, and schema changes across deployments.
- [Persistence and Storage](https://nino.xgamedev.net/en/docs/v4/advanced/persistence.md): Store Nino data in files, databases and other storage so it survives updates: keyed and version-tolerant types, object graphs with shared references, headers and safe writes.
- [Unity and HybridCLR](https://nino.xgamedev.net/en/docs/v4/advanced/unity.md): Set up Nino in Unity, speed it up with optional Burst-compiled SIMD kernels, serialize AnimationCurve, Gradient and RectOffset, use it with assembly definitions, IL2CPP and HybridCLR hot update, and keep frames free of GC.
- [Godot](https://nino.xgamedev.net/en/docs/v4/advanced/godot.md): Set up Nino in a Godot 4 .NET project, copy Godot's math structs as raw memory, store ids instead of nodes, write save games under user://, send messages through Godot's multiplayer API, and rebuild in the editor.

## Other Languages

- [TypeScript, Go and Rust](https://nino.xgamedev.net/en/docs/v4/advanced/codegen.md): Nino.Codegen writes your [NinoType]s as TypeScript, Go or Rust types with codecs after each build (or from a built assembly with the nino-gen tool), so browsers, Node, Go services and Rust programs read and write exactly the bytes Nino writes in .NET.

## Reference

- [Analyzer Diagnostics](https://nino.xgamedev.net/en/docs/v4/analyzers.md): Every diagnostic Nino reports while you type, NINO001 to NINO027, what it means and how to fix it.
- [Platforms and Binary Format](https://nino.xgamedev.net/en/docs/v4/platforms.md): Where Nino runs, why every platform writes the same bytes, and what the format looks like.
- [Wire Format](https://nino.xgamedev.net/en/docs/v4/wire-format.md): An overview of the bytes Nino v4 writes: little-endian values with no envelope, the two string encodings, raw structs in a canonical layout, collections, object headers and type ids, the three formats, deferred bodies and the checks every reader makes. The byte-by-byte specification is in Nino's repository.
- [SIMD on Every Platform](https://nino.xgamedev.net/en/docs/v4/simd.md): Which vector instructions Nino uses on each platform (.NET's AVX-512, AVX2, SSSE3, Arm64 and WebAssembly paths, Unity's Burst kernels, Go's and Rust's string transcoding, TypeScript's WebAssembly text module), how each is detected, what falls back to portable code, and where each is benchmarked.
- [Benchmarks](https://nino.xgamedev.net/en/docs/v4/perf.md): Build-time and runtime benchmarks of Nino v4 against v3 (3.3.13), MemoryPack 1.21.4, MessagePack 3.1.12 and protobuf-net 3.4.30, with the setup to reproduce them.
- [Benchmarks in Other Languages](https://nino.xgamedev.net/en/docs/v4/perf-runtimes.md): Nino's Go, Rust and TypeScript runtimes against Protocol Buffers, MessagePack and each language's usual serializers: what each benchmark measures, why strings cost more in Go and Rust, and the results of the newest v4 release.
- [Unity Benchmark](https://nino.xgamedev.net/en/docs/v4/perf-unity.md): Nino in a Unity IL2CPP player on GitHub's Linux x64 runner, each case timed without and with the optional Burst-compiled kernels, for every release and each Unity version tested.
- [Limitations](https://nino.xgamedev.net/en/docs/v4/limit.md): What to know before choosing Nino v4: it needs its source generator, cannot read v3 data, is positional by default, leaves out System.Type on purpose, and its generated TypeScript does not cover every type.
- [Versioning](https://nino.xgamedev.net/en/docs/v4/versioning.md): Which Nino versions changed the binary format, and how to read data written by an older one.

## Optional

- [Nino v3](https://nino.xgamedev.net/en/docs/v3.md): Archived docs for projects still on Nino v3; the API and binary format differ from v4.
- [Nino v2](https://nino.xgamedev.net/en/docs/v2.md): Archived docs for projects still on Nino v2; the API and binary format differ from v4.