> For the complete documentation index, see [llms.txt](https://docs.marioded.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marioded.com/advanced-integrations/adapters.md). # Protocol adapters Understand the advanced adapter contracts exposed by the public API. **Advanced API reference** ยท Most integrations do not need these contracts This page explains the adapter contracts available in the public API. Most game plugins need only [recording](/api-how-to-guides/recording.md), [playback](/api-how-to-guides/playback.md), and [custom recordables](/advanced-integrations/recordables.md). {% hint style="info" %} An adapter translates between Minecraft's protocol and Reverse's shared data. It is not the entry point for an ordinary Watch button or minigame recording hook. {% endhint %} ## Why there are two adapters `ReverseRecorderAdapter` turns platform/protocol observations into portable capture data. `ReversePlayerAdapter` turns portable replay data into client-visible playback. They live in separate role APIs because recording and viewing run independently. Keep custom recordables in terms of the shared API data types. They should not require a particular packet library to decode their saved payload. ## Recorder adapter responsibilities A capture adapter: * Installs entity metadata and game profile providers during initialization. * Subscribes to wire events and routes observations to `RecorderService`. * Converts Bukkit items, block states, entity types, and chunk snapshots into shared payloads. * Reports protocol capabilities needed by compatibility-sensitive listeners. * Coordinates player/world routing identity so network-thread capture does not query unsafe Bukkit state. * Unsubscribes safely on shutdown, including partial-initialization paths. Block naming must preserve complete state properties, not just a material name. An unresolved state can return null; do not replace it with an arbitrary valid block and silently corrupt the replay. ## Entity metadata provider `EntityMetadataProvider.snapshot(entity, entityTypeName)` captures a protocol-neutral list of typed metadata entries on the main server thread. The metadata service holds the installed provider and rejects retrieval before installation. Metadata entries represent typed fields, not a complete Bukkit entity serialization. Packet metadata often carries only changed fields; the durable state layer merges those partial updates. A backend must not interpret one partial packet as replacement for the entire entity metadata set. ## Game profile provider `GameProfileProvider` extracts the shared profile model from a Bukkit player for recorded player entities. `ProfileProviderService` holds that selected provider and throws if queried before one is installed. Player profiles are captured data, not live Bukkit `Player` references suitable for persistence. Keep profile properties with the recorded model rather than fetching an unrelated current player at playback time. ## Player adapter responsibilities A playback adapter registers its renderer implementations, sends/unloads chunks, sends action-bar components, and updates the client experience display. The renderer service dispatches by recordable type; the `PlaybackContext` supplies session-specific entity mappings and viewers. The experience progress shown by the replay is packet-driven display. It should not become the viewer's actual saved experience state. Clearing temporary HUD output on session end matters because clients retain the last value they received. An adapter does not authorize catalog selections or own match lifecycle. Those decisions stay in the application/services above it. ## Capability handling The SPI exposes a protocol version and named capability helpers such as swap-hand support and, on capture, block-data support. Use those helpers rather than depending on a packet library's version enums. Legacy support needs more than a number comparison: loading a listener whose parameter class does not exist can fail before any handler runs. Keep modern-only listener registration behind the appropriate capability path, and isolate references to newer Bukkit APIs. ## Installing another backend Implementing an adapter interface does not automatically install or hot-swap it. The public entry points do not provide an adapter-replacement method. If you need a different protocol backend, check the capabilities offered by your release and contact support about the required integration. Likewise, the public `ReverseRecorder` facade does not expose the metadata/profile service holders as general runtime mutation points. Do not use reflection to swap a provider mid-recording and treat it as an ordinary supported integration path. ## Validation checklist Verify the supported server floor, missing optional APIs, entity ID remapping, partial metadata/equipment, movement units, block properties, chunk vertical bounds, callback threading, startup failure cleanup, and a save/load/play cycle between independent machines. Compiling against a new Bukkit API alone is not evidence that an older runtime contains those methods. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.marioded.com/advanced-integrations/adapters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.