Home

首页 / Home

HimDSL 是什么 / What is HimDSL

HimDSL 是一个面向 Minecraft Java 版服务端的领域特定语言（Domain-Specific Language，DSL）插件。它构建在 ANTLR4 语法分析器之上，运行于 Bukkit / Spigot / Paper 插件环境，让服务器管理员和地图作者可以用接近 Java 的简洁语法，编写事件监听、定时任务、GUI 界面、数值计算、状态机等逻辑，而无需编写和编译 Java 插件。脚本文件使用 .himdsl 后缀，存放在插件数据目录下，通过 /himdsl run <文件> 命令加载执行，或在服务器启动、关闭时自动运行。

HimDSL is a Domain-Specific Language (DSL) plugin for Minecraft Java Edition servers. Built on top of an ANTLR4 grammar and running inside a Bukkit / Spigot / Paper plugin environment, it lets server administrators and map authors write event listeners, scheduled tasks, GUI menus, numeric computations, and state machines using a concise, Java-like syntax — without writing or compiling a Java plugin. Scripts use the .himdsl extension, live in the plugin data folder, and are executed either through the /himdsl run <file> command or automatically on server startup and shutdown.

---

设计理念 / Design Philosophy

HimDSL 的核心目标是"降低门槛，不牺牲表达力"。它保留了 Java 程序员熟悉的语法元素：类型化变量、函数重载、for / while / do-while、复合赋值、++ / --、lambda 表达式、结构体、枚举。同时，它又针对 Minecraft 做了大量贴合场景的扩展：实体选择器（@a、@p、@e 等）、占位符（$player(name, hp)$、$server(tps)$ 等）、事件注解（@EventHandler）、定时注解（@BukkitRunnable）、以及一套开箱可用的 GUI 抽象。

The core goal of HimDSL is "lower the barrier without sacrificing expressiveness." It keeps syntax elements familiar to Java programmers: typed variables, function overloading, for / while / do-while, compound assignment, ++ / --, lambda expressions, structs, and enums. At the same time, it adds a large set of Minecraft-oriented extensions: entity selectors (@a, @p, @e, …), placeholders ($player(name, hp)$, $server(tps)$, …), event annotations (@EventHandler), scheduling annotations (@BukkitRunnable), and a ready-to-use GUI abstraction.

---

功能一览 / Feature Overview

HimDSL 提供的功能可归纳为六大块。第一，语言核心：变量、类型、运算符、控制流、函数与重载，构成了编写任何逻辑的基础。第二，数据结构：数组、vector（列表）、set、map、stack、queue，以及 toJson / fromJson 序列化能力。第三，自定义类型：struct 定义字段与成员方法，enum 定义用户枚举，二者都可与 Java 反射系统互操作。第四，Minecraft 集成：选择器、占位符、EntityRef 引用、PlaceholderAPI 桥接、HimDungeons Boss API 软依赖。第五，事件与调度：@EventHandler 挂载 Bukkit 事件，@BukkitRunnable 创建定时任务，二者都通过 start / stop 控制生命周期。第六，GUI 系统：new GUI(rows, title) 创建界面，GUISlot 定义槽位图标与回调，支持左键、右键、Shift 组合点击。

The features fall into six groups. First, the language core: variables, types, operators, control flow, functions and overloading — the basis for any logic. Second, data structures: arrays, vector (list), set, map, stack, queue, plus toJson / fromJson serialization. Third, custom types: struct for fields and member methods, enum for user-defined enums, both interoperating with Java reflection. Fourth, Minecraft integration: selectors, placeholders, EntityRef, the PlaceholderAPI bridge, and a soft dependency on the HimDungeons Boss API. Fifth, events and scheduling: @EventHandler for Bukkit events, @BukkitRunnable for timers, both controlled with start / stop. Sixth, the GUI system: new GUI(rows, title) to create menus, GUISlot for icons and callbacks, supporting left-click, right-click, and Shift combinations.

---

一段最简脚本 / A Minimal Script

下面是一段可以直接运行的脚本，它向所有在线玩家广播一条消息。将其保存为 hello.himdsl，在服务器控制台执行 /himdsl run hello.himdsl 即可看到效果。

Here is a runnable script that broadcasts a message to every online player. Save it as hello.himdsl and run /himdsl run hello.himdsl from the server console.

int main() {
    // 用 runcmd 以控制台身份广播 /say
    // Broadcast via /say as console
    runcmd("CONSOLE", "say Hello, HimDSL!");
}

再看一个稍复杂的例子：用选择器找到最近的玩家，读取他的名字与生命值，并把结果打印到控制台。

A slightly more advanced example: locate the nearest player with a selector, read their name and health, and print the result to the console.

int main() {
    player p = @p;
    string name = $player(p, name)$;
    double hp = $player(p, hp)$;
    runcmd("CONSOLE", "say " + name + " 当前生命值: " + hp);
}

以上两段脚本体现了 HimDSL 的基本风格：函数入口为 main，语句以分号结尾；字符串拼接可直接用 +；占位符写在 $类型(参数)$ 中；函数调用与 Java 保持一致。

These two scripts illustrate the basic style of HimDSL: the entry point is main, statements end with semicolons; strings concatenate with +; placeholders use the $type(args)$ form; and function calls match Java conventions.

---

运行环境与依赖 / Runtime & Dependencies

HimDSL 运行在 Minecraft Java 版服务端（Bukkit 及其衍生实现）上，作为一个标准插件加载。它没有强制依赖任何第三方插件，但会检测并使用以下可选依赖：PlaceholderAPI（当存在时，$papi(...) 系列函数可用真实占位符）、HimDungeons（当存在时，$boss(...)$ 与部分玩家占位符如 atroom 可用）、WorldEdit（部分世界占位符可扩展）。所有这些依赖均为软依赖（soft dependency），缺失时相应功能会安全降级而不影响脚本加载。

HimDSL runs on Minecraft Java Edition servers (Bukkit and its derivatives) as a standard plugin. It does not hard-depend on any third-party plugin, but detects and uses the following optional dependencies when present: PlaceholderAPI (enables real placeholders through the $papi(...) family), HimDungeons (enables $boss(...)$ and certain player placeholders such as atroom), and WorldEdit (for extended world placeholders). All of these are soft dependencies — when absent, the corresponding features degrade gracefully without affecting script loading.

---

文档结构导读 / How to Read This Documentation

本套文档按照由浅入深的原则编排，共分十三部分。第一部分（入门）帮助你在十分钟内跑通第一个脚本；第二至第五部分（语言基础、控制流、函数、数据结构）系统讲解语言本身；第六部分（自定义类型）介绍 struct 与 enum；第七至第九部分（Minecraft 集成、事件与调度、GUI）是与服务端交互的核心；第十部分（内置函数参考）是速查手册；第十一部分（进阶）讨论反射、作用域、调试与常见陷阱；第十二部分（扩展 API）面向希望从其他插件调用 HimDSL 的开发者；第十三部分（示例脚本）提供可直接复制运行的完整案例。

The documentation is organized in thirteen parts, progressing from basic to advanced. Part 1 (Getting Started) helps you run your first script in ten minutes. Parts 2–5 (Language Basics, Control Flow, Functions, Data Structures) cover the language itself. Part 6 (Custom Types) introduces struct and enum. Parts 7–9 (Minecraft Integration, Events & Scheduling, GUI) are the core of server interaction. Part 10 (Built-ins Reference) is a quick lookup. Part 11 (Advanced) discusses reflection, scoping, debugging, and common pitfalls. Part 12 (Extension API) targets developers who want to call HimDSL from other plugins. Part 13 (Example Scripts) provides complete, copy-paste-ready cases.

如果你是第一次接触 HimDSL，建议按顺序阅读"入门"部分的四篇，然后跳到你最关心的功能章节；如果你已经熟悉 Java，可以直接从"语言基础"开始，遇到 Minecraft 相关的内容时再查阅相应章节。

If you are new to HimDSL, read the four pages in "Getting Started" in order, then jump to the feature chapters you care about most. If you are already comfortable with Java, you can start at "Language Basics" and consult the Minecraft-related chapters when you encounter them.

---

关于错误与调试 / Errors and Debugging

HimDSL 的语法解析器在遇到错误时会抛出带有行号与列号的异常信息，帮助你快速定位问题。运行时错误（例如选择器未匹配、字段不存在、类型不匹配）则会以堆栈形式打印到服务端日志，同时通过命令返回简要说明。可以通过 /himdsl debug on 打开详细日志，/himdsl debug codeon 在每次运行脚本前打印脚本内容，便于对照分析。建议在编写复杂逻辑时始终保持调试模式开启。

When the parser hits a syntax error, HimDSL throws an exception carrying the line and column, so you can locate the problem quickly. Runtime errors (selector with no match, missing field, type mismatch, etc.) are printed to the server log with a stack trace, while the command returns a brief summary. Use /himdsl debug on to enable verbose logs, and /himdsl debug codeon to print the script content before each run — helpful when cross-checking behavior. It is recommended to keep debug mode on while developing complex logic.

---

下一步 / Next Steps

准备好开始了吗？请翻到 [安装与快速开始 / Getting-Started]，我们将带你完成插件的放置、数据目录的确认、以及第一个脚本的执行流程。

Ready to begin? Head to [安装与快速开始 / Getting-Started], where we walk through placing the plugin, verifying the data folder, and running your very first script.

HimDSL 文档 / Documentation

入门 / Getting Started

• 首页 / Home
• 安装与快速开始 / Installation & Quick Start
• 第一个脚本 / Your First Script
• 命令速查 / Command Reference
• 自动执行脚本 / Auto-run Scripts

语言基础 / Language Basics

• 词法结构 / Lexical Structure
• 变量与类型 / Variables & Types
• 运算符 / Operators
• 字符串与字符 / Strings & Chars

控制流 / Control Flow

• if / else
• for 循环 / for Loop
• while 与 do-while / while & do-while
• break / continue / return

函数 / Functions

• 定义函数 / Defining Functions
• 函数重载 / Function Overloading
• Lambda 表达式 / Lambda Expressions
• 函数式接口 / Functional Interfaces

数据结构 / Data Structures

• 数组 / Arrays
• List / Set / Map
• Stack / Queue
• JSON 序列化 / JSON

自定义类型 / Custom Types

• struct 结构体 / Structs
• 结构体方法绑定 / Struct Method Binding
• enum 用户枚举 / User Enums
• Java 互操作 / Java Interop

Minecraft 集成 / Minecraft Integration

• 选择器总览 / Selectors Overview
• 选择器过滤器 / Selector Filters
• EntityRef 引用 / EntityRef
• 占位符参考 / Placeholders Reference
• PlaceholderAPI 桥接 / PAPI Bridge

事件与调度 / Events & Scheduling

• @EventHandler
• 事件类型解析 / Event Type Resolution
• EventWrapper
• @BukkitRunnable
• start / stop

GUI 系统 / GUI System

• 创建 GUI / Creating a GUI
• GUISlot 槽位 / GUISlot
• 点击回调 / Click Callbacks
• onClose 回调 / onClose Callback
• GUI 刷新 / GUI Refresh

内置函数参考 / Built-ins Reference

• 数学函数 / Math Built-ins
• 高精度计算 / BigDecimal Built-ins
• 字符串函数 / String Built-ins
• 集合函数 / Collection Built-ins
• 文件 I/O / File I/O
• 命令与 sleep / Commands & sleep

进阶 / Advanced

• 反射与类解析 / Reflection & Class Resolution
• 枚举解析机制 / Enum Resolution
• 作用域与闭包 / Scopes & Closures
• 调试技巧 / Debugging
• 常见陷阱 / Pitfalls

扩展 API / Extension API

• HimDSLAPI
• 自定义占位符 / Custom Placeholders
• 嵌入式调用 / Embedding

你真的需要 API 吗？/ Do you really need the API?

• 你真的需要API吗/Do you really need API
• 更多可能 / More options