From 8e071e1515c3ee81a371d7fdab20e5a5cfb6a9d1 Mon Sep 17 00:00:00 2001
From: Procyonae <45432782+Procyonae@users.noreply.github.com>
Date: Wed, 12 Jun 2024 21:12:17 +0100
Subject: [PATCH] Add field type migration to docs

---
 doc/OBSOLETION_AND_MIGRATION.md | 34 +++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/OBSOLETION_AND_MIGRATION.md b/doc/OBSOLETION_AND_MIGRATION.md
index 1ae23564e50ca..12b4a2ecb0463 100644
--- a/doc/OBSOLETION_AND_MIGRATION.md
+++ b/doc/OBSOLETION_AND_MIGRATION.md
@@ -160,6 +160,40 @@ Move multiple ids that don't need to be unique any more to a single id
   }
 ```
 
+# Field migration
+
+Field migration replaces the provided id as submaps are loaded. You can use `fd_null` with `to_field` to remove furniture entirely without creating errors.
+
+```json
+{
+    "type": "field_type_migration",   // Mandatory. String. Must be "field_type_migration"
+    "from_field": "t_old_field",        // Mandatory. String. Id of the field to replace.
+    "to_field": "f_new_field",      // Mandatory. String. Id of the new field to place.
+},
+```
+
+## Example
+
+Migrate an id
+
+```json
+  {
+    "type": "field_type_migration",
+    "from_field": "fd_being_migrated_id",
+    "to_field": "fd_new_id"
+  }
+```
+
+Errorlessly obsolete an id
+
+```json
+  {
+    "type": "field_type_migration",
+    "from_field": "fd_being_obsoleted_id",
+    "to_field": "fd_null"
+  }
+```
+
 # Overmap terrain migration
 
 Overmap terrain migration replaces the location, if it's not generated, and replaces the entry shown on your map even if it's already generated. If you need the map to be removed without alternative, use `omt_obsolete`