t1k:unity:dots-core:memorypack

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	dots-core
Version	2.3.2
Effort	high
Tools	—

Keywords: binary, memorypack, serialization, zero-allocation

How to invoke

/t1k:unity:dots-core:memorypack

---

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: zlinq · zstring · unity-save-system · dots-ecs

---

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

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:

Path	Steps	When 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.4	Modern, 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 gotcha — 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).

Required NuGet packages

When wiring NuGetForUnity install, you need these three:

NuGet package	Purpose	Goes to
MemoryPack.Core	Runtime DLL — MemoryPackSerializer, formatters, attributes	Assets/Packages/MemoryPack.Core.X.Y.Z/lib/netstandard2.1/
MemoryPack.Generator	Roslyn source generator that emits [MemoryPackable] partial method bodies	Assets/Packages/MemoryPack.Generator.X.Y.Z/analyzers/dotnet/cs/ (must have RoslynAnalyzer label on .meta)
System.Collections.Immutable 6.0.0	Transitive dep of MemoryPack.Core for netstandard2.1	Assets/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.

Smoke test after install

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).

---

Core API

[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.

---

DOTS: Wrapper Bridge Pattern

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())

---

Version-Tolerant Schema Evolution

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

---

When to Use

Use MemoryPack	Avoid
Save/load game state	Direct IComponentData (use wrapper)
Network RPC commands	Bandwidth-critical (MessagePack smaller for integers)
Config persistence	Cross-language RPC (use Protobuf)
Replay / entity snapshots	Evolving 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).

---

Critical Gotchas

1. Union formatters need manual registration in Unity — [ModuleInitializer] not supported. → See references/gotchas-core.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>. Use File.WriteAllBytes().

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.

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

---

Reference Files

File	Contents
gotchas-core.md	Gotchas 1-5 with code fixes (union registration, schema, StructLayout, Stream, readonly)
gotchas-extended.md	Gotchas 6-10 (csproj, union runtime, circular refs, NativeArray conversion)
save-load-patterns.md	Entity snapshot, incremental save, versioned save patterns
network-serialization-patterns.md	Command, batch, RPC, delta update patterns
union-serialization-guide.md	Polymorphic serialization, tag numbering, abstract classes
version-tolerant-schema-evolution.md	Migration patterns (add/remove/reorder fields)

---