t1k:unity:dots-core:google-protobuf

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

Keywords: networking, protobuf, protocol buffers, serialization

How to invoke

/t1k:unity:dots-core:google-protobuf

Protocol Buffers (Protobuf) for Unity

Two C# approaches: Google.Protobuf (official, .proto files + protoc) and protobuf-net (attribute-based, no toolchain).

Related skills: memorypack (faster for C#-only, no cross-language) · zstring (zero-alloc string formatting) · dots-ecs (ECS patterns)

When This Skill Triggers

Using [ProtoContract], [ProtoMember] attributes (protobuf-net)
Using Google.Protobuf, MessageParser, .proto files
Cross-language serialization (C# ↔ TypeScript/Go/Python)
Network RPC/command serialization requiring schema contracts
Comparing Protobuf vs MemoryPack vs MessagePack vs JSON

Option A: protobuf-net (Recommended for Unity)

Why: No .proto files, no protoc toolchain, C# attributes only, Stream-based API.

Installation

# Via NuGetForUnity (recommended)
Window → NuGet → Search "protobuf-net" → Install

Package: protobuf-net (full) or protobuf-net.Core (AOT-only, no reflection — better for IL2CPP).

Core API

using ProtoBuf;
using System.IO;

[ProtoContract]
public class GameSave
{
    [ProtoMember(1)] public int Level { get; set; }
    [ProtoMember(2)] public string PlayerName { get; set; }
    [ProtoMember(3)] public float PlayTime { get; set; }
    [ProtoMember(4)] public List<ItemData> Inventory { get; set; }
}

// Serialize
using var stream = File.Create("save.bin");
Serializer.Serialize(stream, data);

// Deserialize
using var stream = File.OpenRead("save.bin");
var loaded = Serializer.Deserialize<GameSave>(stream);

Key Rules

[ProtoMember(N)] — N must be unique positive integer per type
Never reuse or change member numbers after release (breaks compatibility)
Add new fields with new numbers — old data ignores unknown fields
Use [ProtoContract(SkipConstructor = true)] for types without parameterless ctor

Option B: Google.Protobuf (Official)

Why: Cross-language (C# ↔ Go/Python/TS), .proto schema contracts, gRPC support.

Installation

# NuGet packages: Google.Protobuf + Google.Protobuf.Tools (contains protoc)
protoc --csharp_out=Assets/Generated/ --proto_path=Proto/ Proto/game.proto

Proto File Example

syntax = "proto3";
message UnitState {
  int32 entity_id = 1;
  float health = 2;
  float pos_x = 3;
  float pos_z = 4;
}

C# Usage (Generated Code)

byte[] bytes = unit.ToByteArray();
var loaded = UnitState.Parser.ParseFrom(bytes);

Decision Matrix

→ See decision-matrix-guide.md for full comparison table and DOTS integration pattern.

Quick rule: MemoryPack for C#-only speed, Protobuf for cross-language or bandwidth constraints.

Critical Gotchas

→ See gotchas-guide.md for full details with code fixes.

IL2CPP code stripping — Add link.xml to preserve protobuf types.
protobuf-net reflection mode fails on IL2CPP — Use protobuf-net.Core or source generator.
Proto field number reuse — Breaks backward compat silently. Never reuse/change numbers.
Default values not serialized — Proto3: 0, "", false are not written to wire.
DateTime/TimeSpan — Not natively supported. Use Timestamp/Duration or long ticks.

Reference Files

File	Contents
gotchas-guide.md	IL2CPP stripping, reflection, field numbers, default values, DateTime, thread safety
decision-matrix-guide.md	Protobuf vs MemoryPack comparison, DOTS integration pattern, batch serialization