HimDSL v6.5 发布说明 / Release Notes

发布日期 / Release Date: 2026-10-24

---

概述 / Overview

HimDSL v6.5 聚焦于 Java 互操作能力 与 类解析体系 的完善。 HimDSL v6.5 focuses on improving Java interoperability and the class resolution system.

本版本补齐了实例方法调用、字段访问、import 语句（含通配符），并允许关键字作为成员名。 This release adds instance method invocation, field access, import statements (with wildcards), and allows keywords as member names.

此外，编译目标统一调整为 Java 17，与主流服务端运行时对齐。 Additionally, the compilation target is unified to Java 17 to align with mainstream server runtimes.

---

✨ 新增功能 / New Features

1. 实例方法调用 / Instance Method Invocation

• Class<?> 对象上的方法调用现在会先尝试静态方法，失败后回退到 Class 自身的实例方法。

• Method calls on a Class<?> object now first try static methods and fall back to the Class object's own instance methods on failure.

• 支持 getName()、getMethods()、getDeclaredFields()、isInterface()、isEnum()、getSuperclass() 等所有 Class 实例方法。

• Supports all Class instance methods such as getName(), getMethods(), getDeclaredFields(), isInterface(), isEnum(), and getSuperclass().

• 修复 Bukkit.getWorld("world").getHandle().getClass().getMethods() 在最后一环被错误解析为静态方法的问题。

• Fixes the issue where Bukkit.getWorld("world").getHandle().getClass().getMethods() was incorrectly resolved as a static method call at the final step.

2. import 语句 / import Statement

• 新增 import com.example.MyClass; 语法，显式导入类。

• Adds import com.example.MyClass; syntax for explicit class imports.

• 新增 import com.example.*; 通配符导入，按声明顺序查找。

• Adds import com.example.*; wildcard imports, resolved in declaration order.

• 新增 ImportRegistry，作为独立于 EnumRegistry 的导入表，脚本重载时单独清理。

• Introduces ImportRegistry, an import table independent of EnumRegistry, cleared separately on script reload.

• 类解析优先级：变量 > 显式 import > 通配 import > 全路径 > 默认包扫描。

• Class resolution priority: variable > explicit import > wildcard import > FQCN > default package scan.

• import 显式声明不受负缓存影响，可恢复此前失败的解析。

• Explicit imports bypass the negative cache, allowing recovery of previously failed resolutions.

3. 普通 Java 对象字段访问 / Plain Java Object Field Access

• 对非 RefLike / StructInstance / Class 的对象，obj.field 现在会尝试读取 public 字段，再回退到 getXxx() / isXxx() getter。

• For objects that are not RefLike / StructInstance / Class, obj.field now attempts to read a public field, then falls back to a getXxx() / isXxx() getter.

• 常见于第三方插件 API 对象，例如 ctx.player、ctx.dungeon.dungeonName。

• Common in third-party plugin API objects, such as ctx.player and ctx.dungeon.dungeonName.

4. 关键字可作为成员名 / Keywords as Member Names

• 新增 memberName 语法规则，允许 player、type、name、world、enum 等关键字充当字段名或方法名。

• Introduces the memberName grammar rule, allowing keywords such as player, type, name, world, and enum to serve as field or method names.

• 覆盖 postfix 与 lvalue 的成员访问路径。

• Covers member access paths in both postfix and lvalue.

• 修复 ctx.player 报 mismatched input 'player' expecting IDENTIFIER 的错误。

• Fixes the mismatched input 'player' expecting IDENTIFIER error when using ctx.player.

---

🔧 变更 / Changes

5. 编译目标调整为 Java 17 / Compilation Target Changed to Java 17

• Maven maven-compiler-plugin 的 source / target 从 Java 25 调整为 Java 17。

• The source / target of maven-compiler-plugin has been changed from Java 25 to Java 17.

• 与 Paper、Purpur、Spigot 等主流服务端运行时版本对齐，兼容性更广。

• Aligns with mainstream server runtimes such as Paper, Purpur, and Spigot, improving compatibility.

• 避免高版本字节码在 Java 17 服务端触发 UnsupportedClassVersionError。

• Avoids UnsupportedClassVersionError on Java 17 servers caused by higher-version bytecode.

6. 类解析逻辑重构 / Class Resolution Refactor

• EnumRegistry.resolveClass 拆分为 resolveClass（调度）与 resolveFqcn（加载）。

• EnumRegistry.resolveClass is split into resolveClass (dispatch) and resolveFqcn (load).

• 移除重复的 invokeStaticMethod，统一到 invokeClassMethod + findStaticMethod。

• Removed the duplicated invokeStaticMethod, unified into invokeClassMethod + findStaticMethod.

• 枚举静态方法（values() / valueOf()）逻辑并入 invokeClassMethod。

• Enum static methods (values() / valueOf()) are merged into invokeClassMethod.

---

🐛 修复 / Bug Fixes

• 修复 Class<?> 对象调用方法时误走静态通道，导致 getMethods()、getName() 等失败的问题。

• Fixes Class<?> objects incorrectly routing method calls through the static channel, causing getMethods(), getName(), etc. to fail.

• 修复关键字字段名导致的语法错误（player、type、name 等）。

• Fixes syntax errors caused by keyword field names (player, type, name, etc.).

• 修复普通 Java 对象 .field 一律返回 null 的问题。

• Fixes .field access on plain Java objects always returning null.

• 修复 import 显式声明被负缓存误伤，导致首次失败后无法恢复的问题。

• Fixes explicit import declarations being incorrectly blocked by the negative cache after an initial failure.

---

⚠️ 兼容性说明 / Compatibility Notes

• Java 17 及以上 是运行时的最低要求。

• Java 17 or higher is now the minimum runtime requirement.

• 已有脚本无需修改即可运行。

• Existing scripts run without modification.

• import 语法为新增功能，旧脚本不受影响。

• import is a new feature and does not affect existing scripts.

• 关键字作变量名仍不被允许（如 var player = ... 会报错）；仅允许作成员名。

• Keywords remain disallowed as variable names (e.g. var player = ... still errors); they are only allowed as member names.

---

📋 示例 / Example

以下脚本在 v6.5 中可正常执行： The following script now runs correctly in v6.5:

import com.him.dungeons.*;

int main() {
    DungeonHookRegistry hooks = HimDungeons.getInstance().getHookRegistry();
    var plugin = Bukkit.getPluginManager().getPlugin("HimDSL");

    hooks.onAfterEnter(ctx -> {
        var p = ctx.player;
        p.sendMessage("§a你进入了地牢 " + ctx.dungeon.dungeonName);
        p.playSound(p.getLocation(), Sound.ENTITY_ENDER_DRAGON_GROWL, toFloat(0.5), toFloat(1.2));

        Bukkit.getScheduler().runTaskLater(plugin, () -> {
            if (!p.isOnline()) return;
            p.sendTitle("§c§l" + ctx.dungeon.dungeonName, "§7活下去", 10, 60, 20);
        }, toLong(20));
    });
}

关键点 / Key points:

• import com.him.dungeons.*; 通配导入 / wildcard import
• ctx.player 字段访问（getter 回退）/ field access (getter fallback)
• Bukkit.getPluginManager() 静态方法调用 / static method call
• p.sendMessage(...) 实例方法调用 / instance method call
• Sound.ENTITY_ENDER_DRAGON_GROWL 枚举常量 / enum constant

---

🔒 安全提示 / Security Notes

• getClass()、getMethods() 等反射类方法仍在默认的 blacklist-methods 中。

• Reflective methods such as getClass() and getMethods() remain in the default blacklist-methods.

• 若脚本需调用这些方法，请将脚本目录配置为 trusted 级别，或在 config.yml 中显式移除。

• If a script needs to call these methods, set the script's directory to the trusted level, or explicitly remove them from config.yml.

• import 只是注册名称，不会触发类加载与安全检查；类加载发生在实际使用时。

• import only registers names and does not trigger class loading or security checks; loading happens at actual use.

---

📦 升级指南 / Upgrade Guide

1. 备份 plugins/HimDSL/ 目录。

2. Back up the plugins/HimDSL/ directory.

3. 替换新的 HimDSL-6.5.jar。

4. Replace with the new HimDSL-6.5.jar.

5. 确认服务端 JVM 为 Java 17 或以上。

6. Ensure the server JVM is Java 17 or higher.

7. 启动服务端，检查 config.yml 是否自动迁移。

8. Start the server and check whether config.yml has been migrated automatically.

9. 如有自定义脚本使用 getClass() 等反射入口，请确认 config.yml 中的 blacklist-methods 配置。

10. If custom scripts use reflection entries like getClass(), verify the blacklist-methods config in config.yml.

---

🙏 致谢 / Credits

感谢所有反馈实例方法调用、import 需求和关键字字段名报错的用户。 Thanks to everyone who reported instance method calls, import requirements, and keyword field name errors.

你的每一条报错日志，都让 HimDSL 更接近一个真正可用的 DSL 运行时。 Every error log you submit brings HimDSL closer to a truly usable DSL runtime.

---