From a1ce560c05b1deb1474ad840525454bfea1194d5 Mon Sep 17 00:00:00 2001
From: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
Date: Sat, 26 Sep 2026 06:53:30 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=B8=B2=E6=9F=93=E8=81=94?=
 =?UTF-8?q?=E6=B5=8B=E7=9A=84=E4=B8=A4=E4=B8=AA=E9=98=BB=E6=96=AD=E7=BC=BA?=
 =?UTF-8?q?=E9=99=B7=EF=BC=88=E4=B9=8B=E5=89=8D=205/7=20=E2=86=92=20?=
 =?UTF-8?q?=E7=8E=B0=207/7=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## ① natives 必须平铺，不能保留包路径

natives-linux jar 里的路径是 `linux/x64/org/lwjgl/<module>/lib*.so`，
而 LWJGL 经 java.library.path / LD_LIBRARY_PATH 按**文件名**找库 ——
嵌套一层的目录它找不到。实测：

  UnsatisfiedLinkError: Failed to locate library: liblwjgl.so
    at RenderSystem.<clinit> → Tesselator.<clinit>

build.sh 原来直接 `unzip -d $OUT/natives`（保留包路径）⇒ 产物不可用。
改为解到临时目录再 `find -name '*.so' -exec cp` 平铺。
（已用新逻辑重铺 store/vanilla-1.20.1/.mcfold/natives，7 个 .so 在根下。）

## ② api_notes 应为 staticmethod

35534b1 把世代分派改成类级调用后，`api_notes` 仍是实例方法，
测试里 `Gen_1_20.api_notes()` 直接 TypeError。它不读 self ⇒ 一律 staticmethod。
这也是它能"不启动后端就做世代对照"的前提。

## ③ classpath.txt 的语义写进注释

它**只含第三方 libraries**；client-named.jar 与 classes/ 由使用方拼接
（build.sh:88 自己拼，测试/后端从各自路径取）。
在 build.sh 里注明，避免下一个人以为它是"完整运行 classpath"。

## 验证

  ./run_tests.sh                    → 62 项全绿
  .mcfold classpath + 平铺 natives  → 渲染联测 **7/7 全绿**
    （injected=49 chunks=31 colors=11714 / placed=1003716 chunks=25 colors=4540）
---
 mcfold/backends/base.py     |  9 +++++++--
 mcfold/backends/gen_1_20.py |  3 ++-
 mcfold/backends/gen_1_21.py |  3 ++-
 scaffold/build.sh           | 16 ++++++++++++++--
 4 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/mcfold/backends/base.py b/mcfold/backends/base.py
index be84791..5339ba1 100644
--- a/mcfold/backends/base.py
+++ b/mcfold/backends/base.py
@@ -426,8 +426,13 @@ class RenderBackend:
 
     # ---------------- 元信息 ----------------
 
-    def api_notes(self) -> dict:
-        """本世代的 API 特征（子类覆写）。"""
+    @staticmethod
+    def api_notes() -> dict:
+        """本世代的 API 特征（子类覆写）。
+
+        ★ 静态信息（不依赖实例）⇒ 定义成 staticmethod，
+          这样才能在**不启动后端**的前提下做世代对照（测试用）。
+        """
         return {}
 
     def describe(self) -> str:
diff --git a/mcfold/backends/gen_1_20.py b/mcfold/backends/gen_1_20.py
index 4cfd320..2f57f60 100644
--- a/mcfold/backends/gen_1_20.py
+++ b/mcfold/backends/gen_1_20.py
@@ -28,7 +28,8 @@ class Gen_1_20(RenderBackend):
     # 判据类（用于自动识别）
     markers: tuple[str, ...] = ()
 
-    def api_notes(self) -> dict:
+    @staticmethod
+    def api_notes() -> dict:
         return {
             "setLevel": "Minecraft.setLevel(ClientLevel)",
             "render": "GameRenderer.render(float, long, boolean)",
diff --git a/mcfold/backends/gen_1_21.py b/mcfold/backends/gen_1_21.py
index 3a20631..dfc1ba9 100644
--- a/mcfold/backends/gen_1_21.py
+++ b/mcfold/backends/gen_1_21.py
@@ -26,7 +26,8 @@ class Gen_1_21(RenderBackend):
     java_dir = "java/gen_1_21"
     markers = ("net/minecraft/client/DeltaTracker.class",)
 
-    def api_notes(self) -> dict:
+    @staticmethod
+    def api_notes() -> dict:
         return {
             "setLevel": "Minecraft.setLevel(ClientLevel, ReceivingLevelScreen$Reason)",
             "render": "GameRenderer.render(DeltaTracker, boolean)",
diff --git a/scaffold/build.sh b/scaffold/build.sh
index a797544..33bacc3 100755
--- a/scaffold/build.sh
+++ b/scaffold/build.sh
@@ -74,12 +74,24 @@ else
 fi
 
 # ── 4. classpath（去 asm 重复，Fabric 需要） + natives ────────
+# classpath.txt **只含第三方 libraries** —— client-named.jar 与 classes/ 由使用方拼接
+# （build.sh 自己在下面拼，测试/后端则从各自路径取）。
+# ★ 别在这里把 named/classes 也写进去：那会让「libraries 清单」与「运行 classpath」
+#   两个概念混成一列，而 Fabric 路线需要把 asm 从 libraries 里剔掉后**另行**拼 8 个库。
 find "$STORE/libraries" -name "*.jar" ! -name "*-sources.jar" ! -name "*natives*" 2>/dev/null \
   | grep -vE "minecraftforge|neoforge" > "$OUT/classpath.txt"
 NATLIST=$(find "$STORE/libraries" -name "*natives-linux*.jar" 2>/dev/null)
 if [ -n "$NATLIST" ]; then
-  rm -rf "$OUT/natives/linux"; mkdir -p "$OUT/natives"
-  while read -r j; do [ -f "$j" ] && unzip -o -q "$j" -d "$OUT/natives" 2>/dev/null || true; done <<< "$NATLIST"
+  rm -rf "$OUT/natives"; mkdir -p "$OUT/natives"
+  # ★ 必须**平铺**。natives jar 里的路径是 linux/x64/org/lwjgl/<module>/lib*.so，
+  #   而 LWJGL 是经 java.library.path/LD_LIBRARY_PATH 按**文件名**找库的 ——
+  #   嵌套一层的目录它**找不到**（实测 UnsatisfiedLinkError: Failed to locate library: liblwjgl.so）。
+  while read -r j; do
+    [ -f "$j" ] || continue
+    unzip -o -q "$j" -d "$OUT/natives.tmp" 2>/dev/null || true
+  done <<< "$NATLIST"
+  find "$OUT/natives.tmp" -name '*.so' -exec cp {} "$OUT/natives/" \; 2>/dev/null
+  rm -rf "$OUT/natives.tmp"
 fi
 echo "[4/5] 库 $(wc -l < "$OUT/classpath.txt") 个, natives $(find "$OUT/natives" -name '*.so' | wc -l) 个"