t1k:unity:dots-core:memorypack
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | high |
| Tools | — |
Keywords: binary, memorypack, serialization, zero-allocation
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:memorypackMemoryPack: 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:
| 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 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 foundRoot 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 Hard rules
Section titled “Critical Hard rules”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
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
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) |