Custom JSON Converter Performance¶

A custom JsonConverter<T> can reduce repeated member lookup for a frequently serialized model. It also makes you responsible for the model's JSON contract, including missing fields, unknown properties, nulls, enums and nested values. Start with the package's normal JSON options, profile the actual save or message path, and add a converter only where the benefit justifies that work.

The package does not currently ship a general-purpose JSON source generator. The measurements below compare a hand-written converter with the reflection path; they are not measurements of a shipped generated-converter feature.

Register a converter¶

Create options once, add your converter before first use, then reuse those options for the same contract. Serializer.CreateNormalJsonOptions() returns an options instance you can customize. Insert your converter first when it must take precedence over an existing converter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

using System.Text.Json;
using System.Text.Json.Serialization;
using WallstopStudios.UnityHelpers.Core.Serialization;

public static class JsonSaveSettings
{
    public static JsonSerializerOptions Create<T>(JsonConverter<T> converter)
    {
        JsonSerializerOptions options = Serializer.CreateNormalJsonOptions();
        if (converter != null)
        {
            options.Converters.Insert(0, converter);
        }
        return options;
    }
}

Pass the returned options to the package's JSON operations, such as Serializer.JsonSerialize(value, options). Configure the options before the first serialization or deserialization; do not modify an options instance already in use. Keep the cached instance with the code that owns the contract.

Before adopting a converter, test both read directions with retained data: the new reader must load old JSON, and any older reader you still support must load new output. A converter that is faster because it drops fields or changes defaults is a format change.

Historical comparison¶

These measurements were taken on Unity 6000.4.6f1, Editor Mono, 2026-08-29. The model had ten members: integers, a float, a bool, a string, an enum, a Vector3, a list and a nested object. The small and large cases used lists of 4 and 256 integers respectively.

The reference used the package's normal or fast JSON options. The custom converter used cached UTF-8 property names and explicit member reads and writes. Both paths produced identical bytes and read each other's payloads into equal values before timing. Timings alternated the two paths and retained repeated samples. A ratio above one favors the custom converter.

The three recorded runs were:

Most workloads exceeded the measurement's 3% within-run spread limit in at least one run. The similar ratios across runs do not remove that instability. The following four rows met that limit in the third run:

These are historical observations for one model and environment. They do not establish a lower bound, an upper bound, or a guaranteed speedup for another converter, model or backend. There is no current IL2CPP or WebGL result on this page.

Decide what to change¶

• Occasional saves: prefer the standard options unless profiling shows a visible delay. Maintaining a converter may cost more than it saves.
• Frequent messages or replay frames: measure serialization and deserialization separately. Model size and shape can move the benefit substantially.
• Options: choose normal or fast settings for their supported behavior. Fast settings change parsing and member policies; they are not a substitute for a custom converter.
• Allocation: reuse the options and measure the complete call. These timing ratios do not establish allocation or retained-memory savings.
• Players: verify converter registration, stripping and round trips in each target backend. A working Editor converter does not establish AOT availability.

See JSON options for package presets and reading performance measurements for comparison limits.