Skip to content

t1k:unity:dots-core:memorypack

FieldValue
Moduledots-core
Version3.56.1
Efforthigh
Tools—

Keywords: binary, memorypack, serialization, zero-allocation

/t1k:unity:dots-core:memorypack

MemoryPack: Zero-Encoding Binary Serializer

Section titled “MemoryPack: Zero-Encoding Binary Serializer”

Zero-encoding binary serializer. 10x faster than MessagePack for standard objects, 50-200x for struct arrays. Version: 1.21.4+ | Min Unity: 2022.3.12f1 | License: MIT | Reflection-free source-generation (IL2CPP-safe), fixed-size encoding, AOT-compatible.

Related skills: t1k-unity-dots-core-zlinq · t1k-unity-dots-core-zstring · t1k-unity-base-save-system · t1k-unity-dots-core-ecs


Triggers: [MemoryPackable], save/load, network RPC, MemoryPackSerializer.Serialize/Deserialize, entity snapshots, DOTS persistence

Section titled “Triggers: [MemoryPackable], save/load, network RPC, MemoryPackSerializer.Serialize/Deserialize, entity snapshots, DOTS persistence”

Installation — Read This Before Choosing a Path

Section titled “Installation — Read This Before Choosing a Path”

TL;DR: MemoryPack on Unity needs two layers: the OpenUPM Unity-formatters wrapper AND the core .dll (which the wrapper does NOT ship). Pick ONE row:

PathStepsWhen to use
OpenUPM + NuGetForUnity (recommended for new projects)(1) Add OpenUPM scoped registry with scopes com.cysharp and com.github-glitchenzo (2) UPM-install com.cysharp.memorypack (3) UPM-install com.github-glitchenzo.nugetforunity (4) Window → NuGet → Manage NuGet Packages → install MemoryPack 1.21.4Modern, version-tracked, source-gen analyzer auto-wired
OpenUPM + manual DLL (escape hatch — slow Unity / blocked menus)(1) Add OpenUPM scoped registry (2) UPM-install com.cysharp.memorypack (3) Curl MemoryPack.Core.X.Y.Z.nupkg, MemoryPack.Generator.X.Y.Z.nupkg, System.Collections.Immutable.6.0.0.nupkg from https://api.nuget.org/v3-flatcontainer/ (4) Place DLLs at Assets/Packages/MemoryPack.Core.X.Y.Z/lib/netstandard2.1/, Assets/Packages/MemoryPack.Generator.X.Y.Z/analyzers/dotnet/cs/, Assets/Packages/System.Collections.Immutable.6.0.0/lib/netstandard2.0/When NuGet menu fails or you need offline install
UPM Git URL"com.cysharp.memorypack": "https://github.com/Cysharp/MemoryPack.git?path=src/MemoryPack.Unity/Assets/MemoryPack.Unity#1.21.4"UNCERTAIN — upstream Unity asmdef path may itself reference MemoryPack.Core.dll that’s not in the git path; smoke-test before committing

CRITICAL hard rule — OpenUPM-only install is BROKEN

Section titled “CRITICAL hard rule — OpenUPM-only install is BROKEN”

Symptom: After installing only com.cysharp.memorypack from OpenUPM, you get compile errors like:

Library/PackageCache/com.cysharp.memorypack@.../Runtime/UnityFormatters.cs(3,18): error CS0234:
The type or namespace name 'Internal' does not exist in the namespace 'MemoryPack'
Library/PackageCache/com.cysharp.memorypack@.../Runtime/UnityFormatters.cs(9,53): error CS0246:
The type or namespace name 'MemoryPackFormatter<>' could not be found

Root cause: com.cysharp.memorypack on OpenUPM is a wrapper-only package — package.json has "dependencies": {} (empty) and the asmdef has precompiledReferences: ["MemoryPack.Core.dll"] but ships NO core DLL. It expects NuGetForUnity to bring in the MemoryPack.Core.dll separately.

Fix: Use one of the install paths above — never just OpenUPM-alone. NuGetForUnity provides the missing MemoryPack.Core.dll (and source-generator + transitive System.Collections.Immutable).

When wiring NuGetForUnity install, you need these three:

NuGet packagePurposeGoes to
MemoryPack.CoreRuntime DLL — MemoryPackSerializer, formatters, attributesAssets/Packages/MemoryPack.Core.X.Y.Z/lib/netstandard2.1/
MemoryPack.GeneratorRoslyn source generator that emits [MemoryPackable] partial method bodiesAssets/Packages/MemoryPack.Generator.X.Y.Z/analyzers/dotnet/cs/ (must have RoslynAnalyzer label on .meta)
System.Collections.Immutable 6.0.0Transitive dep of MemoryPack.Core for netstandard2.1Assets/Packages/System.Collections.Immutable.6.0.0/lib/netstandard2.0/

Without MemoryPack.Generator set up as a Roslyn analyzer (label RoslynAnalyzer on the .meta + Plugin Importer validateReferences=1, exclude all platforms), the source-generator does NOT run → [MemoryPackable] partial classes will not have generated Serialize/Deserialize methods → CS errors.

NuGetForUnity sets these labels automatically when installing via Manage NuGet Packages window. Manual DLL placement requires manually editing .meta files to add the label.

using MemoryPack;
[MemoryPackable] public partial class _MemoryPackSmokeTest { public int X; }
// In Editor or at runtime:
var bytes = MemoryPackSerializer.Serialize(new _MemoryPackSmokeTest { X = 42 });
var loaded = MemoryPackSerializer.Deserialize<_MemoryPackSmokeTest>(bytes);
UnityEngine.Debug.Assert(loaded.X == 42);

If the smoke test fails to compile, the source generator is not wired (check Assets/Packages/MemoryPack.Generator.*/analyzers/dotnet/cs/MemoryPack.Generator.dll.meta has RoslynAnalyzer label).


[MemoryPackable]
public partial class GameData
{
public int Level { get; set; }
public string PlayerName { get; set; }
public float[] Scores { get; set; }
}
byte[] bytes = MemoryPackSerializer.Serialize(data);
var loaded = MemoryPackSerializer.Deserialize<GameData>(bytes);

Rules: Must be partial. Public properties auto-discovered. Field control: [MemoryPackIgnore] to exclude, [MemoryPackInclude] to include private.

Unity types supported: Vector2/3/4, Quaternion, Color, Color32, Bounds, Rect, Matrix4x4, LayerMask, RangeInt, Keyframe, AnimationCurve, Gradient, RectOffset.

Gotcha: If version conflicts occur, disable Player Settings → Other → Assembly Version Validation. MemoryPack is 3-10x faster than JsonUtility in Unity.


Cannot serialize IComponentData directly — unmanaged structs have no properties. Use a managed wrapper:

public readonly struct Health : IComponentData { public readonly float HP; }
[MemoryPackable]
public partial class HealthSnapshot
{
public float HP { get; set; }
public static HealthSnapshot From(in Health h) => new() { HP = h.HP };
public Health ToComponent() => new() { HP = HP };
}
// Serialize: MemoryPackSerializer.Serialize(HealthSnapshot.From(health))
// Deserialize: em.SetComponentData(entity, loaded.ToComponent())

Default mode: adding fields OK, removing/reordering breaks. Use VersionTolerant for evolving schemas (~5% slower):

[MemoryPackable(GenerateType.VersionTolerant)]
public partial class ConfigV2
{
[MemoryPackOrder(0)] public string Name { get; set; }
[MemoryPackOrder(1)] public float Health { get; set; } = 100f;
}

→ See references/version-tolerant-schema-evolution.md


Use MemoryPackAvoid
Save/load game stateDirect IComponentData (use wrapper)
Network RPC commandsBandwidth-critical (MessagePack smaller for integers)
Config persistenceCross-language RPC (use Protobuf)
Replay / entity snapshotsEvolving schemas without VersionTolerant

Performance vs alternatives: 10x faster than MessagePack, 200x for struct arrays, ~20-30% larger payload for integers (50% smaller for Vector3 arrays).


1. Union formatters need manual registration in Unity — [ModuleInitializer] not supported. → See references/hard-rules-core.md

1b. Cross-assembly union registration lives on {FormatterName}Initializer, namespaced to the union interface — not {InterfaceName}Formatter, and RuntimeHelpers.RunClassConstructor does NOT register it. → See references/union-formatter-registration-unity.md

2. Default mode breaks on field removal/reorder — Use GenerateType.VersionTolerant for evolving schemas.

3. StructLayout(Auto) differs between Mono and IL2CPP — Use LayoutKind.Sequential for cross-platform structs.

4. No Stream support — API only accepts ReadOnlySpan<byte> or IBufferWriter<byte>, so the bytes reach disk via File.WriteAllBytes(). ⚠️ Write them to a .tmp and publish with File.Replace, never straight to the destination — WriteAllBytes truncates before it fills, so a failed write destroys the previous good save and leaves a 0-byte stub that File.Exists still reports as present. → references/save-load-patterns.md § “Why not the obvious File.WriteAllBytes + File.Exists pair”

5. Readonly properties fail — MemoryPack requires { get; set; }, not { get; }.

6. OpenUPM-only install is BROKEN — com.cysharp.memorypack on OpenUPM is wrapper-only and does NOT ship MemoryPack.Core.dll. You MUST also install via NuGetForUnity (or place the DLLs manually). See “Installation” section above for the 3-path table and smoke test.

7. MEMPACK042 on a [MemoryPackable] type nested in a non-partial container — move the type to namespace scope, do NOT make the container partial (that just relocates the trap to the next nested type). → references/hard-rules-extended.md § Gotcha 11

8. DOTSCore.GameFlow is a separate assembly, not a sub-namespace of DOTSCore — CS0234 names the namespace, never the missing asmdef reference. → references/hard-rules-extended.md § Gotcha 12

→ Full gotchas list: references/hard-rules-core.md | Extended (gotchas 6-12): references/hard-rules-extended.md


FileContents
hard-rules-core.md (references/hard-rules-core.md)Gotchas 1-5 with code fixes (union registration, schema, StructLayout, Stream, readonly)
hard-rules-extended.md (references/hard-rules-extended.md)Gotchas 6-12 (csproj, union runtime, circular refs, NativeArray conversion, MEMPACK042 partial-container, DOTSCore.GameFlow asmdef)
save-load-patterns.md (references/save-load-patterns.md)Entity snapshot, incremental save, versioned save patterns
network-serialization-patterns.md (references/network-serialization-patterns.md)Command, batch, RPC, delta update patterns
union-serialization-guide.md (references/union-serialization-guide.md)Polymorphic serialization, tag numbering, abstract classes
union-formatter-registration-unity.md (references/union-formatter-registration-unity.md)Cross-assembly *Initializer registration naming gotcha
version-tolerant-schema-evolution.md (references/version-tolerant-schema-evolution.md)Migration patterns (add/remove/reorder fields)