Skip to main content
Blueprints does not know what a “job spawn” or a “zone” or a “shop” is. An adapter is the piece that teaches it one domain, and this is the documentation for writing one. An adapter lives in your own addon. You do not modify Blueprints, you do not read its internals, and you do not need to understand snapshots, diffs, migrations or restore to write one.

Quickstart

A registered, capturable adapter in one file. Read this first.

​
The question this answers

I have an addon with objects Blueprints does not currently understand. How do I make Blueprints manage them safely?
You describe your domain as plain data, declare which operations you can honour for every object you produce, and implement those. Blueprints composes its workflows out of what you declared.

​
What an adapter is responsible for

1

Registering

From one hook, once, after the map loads. Load order between your addon and Blueprints does not matter. See Registry.
2

Describing your domain

Collect returns every object in your domain, on this map, as plain data. All of them or none. See Records.
3

Giving each object a stable identity

The single most consequential decision you will make. See Identity.
4

Declaring capabilities truthfully

Each capability is a promise about every record you emit, not about most of them. See Capabilities.
5

Implementing the world operations you declared

Move, rebuild, conform, destroy. Each has a phase that answers and a phase that writes.

​
What Blueprints is responsible for

  • Planning. Migration, restore and deployment are workflows composed from your primitives. You never declare “restore”.
  • Persistence, diffing, grouping, previewing, verification and rollback.
  • Refusing to act where your declarations do not support it, and saying so in a sentence.
  • Never dropping your historical records, even on a server where your adapter is not installed.

​
The adapter lifecycle

​
The five capabilities

There is no create, update, delete, migrate or restore. Those words describe operations that are either unbounded or composed, and the SDK deliberately does not offer them.

​
Realm

Adapters are server-side. Put your registration in lua/autorun/server/, or in a file whose name begins sv_.
Entities, the world and your addon’s data live on the server, and a captured record is server state. Nothing in the adapter contract runs on a client, and no part of your adapter’s logic is ever sent to one, including previews, which cross the wire as declarative data rather than as code.

​
Official adapters get no privileges

Adapters shipped by Vetra are marked official in the product’s Adapters screen. That records who maintains it and nothing else: official adapters register through the same hook, use the same functions, and have no privilege you do not have. The built-in props adapter registers through exactly the hook your addon uses, on purpose, so the built-in contract cannot quietly diverge from the public one.

​
Where to go next

Quickstart

Registration through capture, minimal.

Adapter anatomy

Every field and function, required, optional or capability-dependent.

Identity

Read this before you choose how to generate ids.

Compatibility checklist

Read this before you ship.