From 81521df92b99e20beef2b6daa8214d5246704e60 Mon Sep 17 00:00:00 2001
From: Ap_Tx <3045929398@qq.com>
Date: Sat, 3 Oct 2026 15:42:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=20README=20=E5=B9=B6?=
 =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E4=BB=93=E5=BA=93=E9=93=BE=E6=8E=A5=E4=B8=BA?=
 =?UTF-8?q?=20Mr-dayhappy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README 从两行扩写为完整说明：问题背景、实现原理、覆盖范围、构建方式、已知未验证点。fabric.mod.json 的 homepage/sources 链接从 ApTx2012 改为实际远端 Mr-dayhappy。
---
 README.md                          | 66 +++++++++++++++++++++++++++++-
 src/main/resources/fabric.mod.json |  6 +--
 2 files changed, 68 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7229a25..eb4e865 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,66 @@
 # Minecraft-place-mod
-A mod which promotes the /place
+
+一个补全原版 `/place` 命令的 Fabric mod，让 `/place structure` 生成的结构**和自然生成的完全一样**。
+
+## 它解决什么问题
+
+原版的 `/place structure` 本质上只是个「建筑粘贴工具」。执行时它会：
+
+1. 用 `Structure.generate(...)` 生成一个 `StructureStart`；
+2. 调 `StructureStart.placeInChunk(...)` 把方块摆到世界里；
+3. 生成结构内的实体（如村庄的村民）。
+
+但它**跳过了自然生成时最关键的一步——结构注册**：
+
+- 不调 `StructureManager.setStartForStructure(...)`，结构不进 `StructureManager`；
+- 不写区块的 `structureReferences`，区块 NBT 里不记录这个结构。
+
+后果：
+
+- 游戏不认这块区域是「村庄 / 海底神殿」，**结构专属的刷怪规则永不激活**；
+- 区块存档不记录该结构，**重启后结构在逻辑上「消失」**，只剩一堆方块。
+
+## 这个 mod 干了什么
+
+用一个 Mixin 挂在 `PlaceCommand.placeStructure` 的返回处，在命令执行完后补做自然生成的注册步骤：
+
+1. **`setStartForStructure`** —— 把 `StructureStart` 存进它所在区块的 `StructureAccess`；
+2. **`createReferences`** —— 调 `ChunkGenerator.createReferences`（自然生成用的同一个方法），扫描 17×17 邻居区块，把引用写入区块；
+3. **`markUnsaved`** —— 标记涉及的区块未保存，强制持久化。
+
+全程 `try-catch` 兜底：补注册失败不会影响命令本身的成功返回。
+
+## 覆盖范围
+
+- ✅ `/place structure`
+- ❌ `/place jigsaw`、`/place template`、`/place feature`（语义不同，暂不处理）
+
+## 构建
+
+需要 JDK 25（Minecraft 26.1+ 要求）。
+
+```bash
+./gradlew build
+```
+
+产物在 `build/libs/`。
+
+## 环境
+
+- Minecraft 26.1.2
+- Fabric Loader ≥ 0.19.5
+- Fabric API
+- Loom 1.18-SNAPSHOT / Gradle 9.7.1 / Java 25 / official 映射
+
+## 已知未验证点
+
+- Mixin 用 `LocalCapture.CAPTURE_FAILHARD` 捕获 `placeStructure` 的局部变量（`ServerLevel` / `Structure` / `ChunkGenerator` / `StructureStart`）。局部表顺序已按 26.1.2 字节码核对，但仍需实机编译验证。
+- `createReferences` 对包围盒覆盖的每个区块各调一次（每次内部扫 17×17）。`addReferenceForStructure` 写的是 `LongSet`，天然幂等，不会重复写脏数据，但存在多余开销。
+
+## 链接
+
+- GitHub: https://github.com/Mr-dayhappy/Minecraft-place-mod
+
+## License
+
+MIT
\ No newline at end of file
diff --git a/src/main/resources/fabric.mod.json b/src/main/resources/fabric.mod.json
index 1e58afe..8ef5aea 100644
--- a/src/main/resources/fabric.mod.json
+++ b/src/main/resources/fabric.mod.json
@@ -5,11 +5,11 @@
 	"name": "Minecraft Place Mod",
 	"description": "A mod which promotes the /place command — makes /place structure-generated structures behave exactly like naturally generated ones (registered into StructureManager, persisted to chunk NBT).",
 	"authors": [
-		"ApTx2012"
+		"Mr-dayhappy"
 	],
 	"contact": {
-		"homepage": "https://github.com/ApTx2012/Minecraft-place-mod",
-		"sources": "https://github.com/ApTx2012/Minecraft-place-mod"
+		"homepage": "https://github.com/Mr-dayhappy/Minecraft-place-mod",
+		"sources": "https://github.com/Mr-dayhappy/Minecraft-place-mod"
 	},
 	"license": "MIT",
 	"icon": "assets/minecraft-place-mod/icon.png",