MagicPaper 是 Magic 的 proof-of-use integration:它证明 Magic 可以把 Paper / Folia 服务器能力转化为可组合、可执行、可被 Agent 理解的语义。

MagicPaper 是 Magic 脚本语言在 Minecraft Paper / Folia 服务器中的实现。它把 Paper 服务器核心能力、常用插件能力和服务器业务逻辑封装成 Magic 语义,让服主或开发者可以用更短的文本编排 GUI、触发器、计时器、物品、Buff、经济、权限、技能等功能。

MagicPaper 的定位不是单纯的"技能插件"或"GUI 插件",而是一个基于 Magic 的服务器功能编排层。复杂能力仍然由 Java 和第三方插件提供,MagicPaper 负责把这些能力注册成语义,使同样的文本量能够表达更多逻辑,并让第三方可以快速接入这一套语言。

当前实现包含:

• 基于 Magic 的脚本执行器,可同时启用 Magic 系统语义和 MagicPaper 领域语义。
• Paper / Folia 任务执行语义,支持同步与异步执行。
• 配置型魔咒、.m 源文件导入、服务器启动执行、事件触发执行、定时执行。
• GUI 系统,支持分页、按钮脚本、动态数据按钮。
• 物品系统,支持 NBT、Lore 模板、变量刷新、属性、镶嵌孔、物品触发魔咒。
• Buff、冷却、BossBar、粒子、实体、坐标、药水、Yaml、随机等基础模块。
• PlaceholderAPI、LuckPerms、Vault、PlayerPoints、MythicMobs、ItemsAdder、ProtocolLib、AbolethPlus、MMOItems、EpicCraftingsPlus、AuthMe、Adyeshach、RemoteKeyboardBukkit、BungeeCord 等可选接入。
• 面向第三方插件的 API:注册语义、注册触发器、注册计时器、执行魔咒、访问上下文、GUI、Buff、冷却和魔法物品。

插件面向 Paper / Folia 服务端实现,软依赖均为可选挂钩;不安装对应插件时,只影响对应语义能力。

Magic 是语言核心;MagicPaper 是 Minecraft 环境实现,也是 Magic 当前最直接的 proof-of-use integration。

MagicPaper 启动时会创建 MagicManager,并根据 config.yml 中的开关注册语义:

extended-syntax:
 system: true
 paper: true

• system: true 注册 Magic 内置语义,如变量、计算、控制流、容器、输入输出。
• paper: true 注册 MagicPaper 语义,如玩家、物品、GUI、触发器、经济、权限、技能等。

这意味着第三方插件也可以把自己的能力注册成 Magic 语义,让 MagicPaper 成为不同插件之间的低成本编排层。

构建需要 Java 和 Maven:

mvn package

构建产物位于 target/。将生成的 Jar 放入服务器 plugins/ 目录后启动服务器即可。

首次启动时,如果 config.yml 中 default-file: true,插件会释放默认配置和示例文件。

作为依赖接入时,可以使用 MagicPaper 的 Maven 坐标;具体版本号以你发布或本地安装的构建为准:

<dependency>
 <groupId>cn.originmc.plugins</groupId>
 <artifactId>MagicPaper</artifactId>
 <version>${magicpaper.version}</version>
</dependency>

MagicPaper 依赖 Magic 语言核心;作为开发依赖时可按同样方式引入 Magic:

<dependency>
 <groupId>cn.origincraft.magic</groupId>
 <artifactId>Magic</artifactId>
 <version>${magic.version}</version>
</dependency>

项目 pom.xml 中已经包含 Paper、Folia、PlaceholderAPI、NBTAPI、ProtocolLib、MythicMobs、ItemsAdder、Vault、PlayerPoints 等仓库与依赖配置。

插件数据目录中的主要文件夹:

MagicPaper/
 config.yml 插件总配置
 lang/ 语言文件
 magic/ YAML 格式魔咒,可由命令、触发器、计时器、GUI 调用
 import/ 启动时导入到上下文的 .m 源文件
 onload/ 服务器启动后执行的 .m 源文件
 trigger/ 事件触发器配置
 timer/ 定时器配置
 gui/ GUI 配置
 item-format/ 物品 Lore 解析模板
 attribute/ 属性配置
 data/ 公共数据

一个最小魔咒文件示例:

spell:
 - stap(HelloWorld)
display: "HelloWorld"
description:
 - "Send a message to all online players"

一个触发器配置示例:

execute-spell:
 - HelloWorld

一个计时器配置示例:

type: paper
later: 20
interval: 20
execute-spell:
 - HelloWorld

仓库的 examples/ 目录提供了几类可拷贝到 MagicPaper 配置体系中的 .m 场景脚本:

examples/
 01-onload-broadcast.m 服务器启动广播
 02-player-join-welcome.m 玩家触发器欢迎语
 03-cooldown-jump.m 冷却保护的大跳技能
 04-open-example-gui.m 打开默认 GUI
 05-give-named-reward.m 发放命名物品奖励

这些示例展示 MagicPaper 如何把"玩家、物品、GUI、冷却、Buff、广播"等服务器能力压缩成短语义。带 self 的脚本适合放在玩家事件触发器、物品触发魔咒或 /magicpaper words ... [player] 这类玩家上下文中执行。

主命令为 /magicpaper,别名为 /mp,基础权限为 magicpaper.command。

/magicpaper reload
/magicpaper reloadall
/magicpaper spells
/magicpaper words <words> [player]
/magicpaper spell <spell> [player]
/magicpaper publicwords <words>
/magicpaper publicspell <spell>
/magicpaper functions
/magicpaper functioninfo <function>
/magicpaper triggers
/magicpaper onload
/magicpaper boreremove <address> <index>
/magicpaper restart
/magicpaper coding
/magicpaper gui <id> [player]
/magicpaper clearguidata <id> [player]
/magicpaper updateguidata <id> [player]
/magicpaper lookailas <function>

说明:

• words 和 publicwords 用于直接执行一行 Magic 语义;命令参数中的逗号会被替换为空格。
• spell 和 publicspell 用于执行 magic/ 目录中载入的魔咒。
• public* 使用全局上下文;普通执行会创建临时上下文并导入 import/ 内容。
• functioninfo 会从当前已注册的 ArgsFunction 读取参数说明。
• lookailas 是当前代码中的命令拼写,用于查看语义别名。

/magicpaper coding 可以切换玩家聊天编码模式。玩家需要 OP 或 magicpaper.coding 权限。

快捷执行:

!m<Magic语句> 在临时上下文执行
!pm<Magic语句> 在全局上下文执行
!clear 清空 Coding 临时上下文

进入编码模式后,普通聊天会被写入当前代码缓冲区。可用关键字:

go 执行当前缓冲区
clear 清空当前缓冲区
look 查看当前缓冲区
spell <spell1> <spell2> 执行已配置魔咒
save <id> <display> <desc> 保存当前缓冲区为 magic/<id>.yml

触发器用于在事件发生时执行魔咒。当前内置触发器包括:

• 服务器:ServerOnLoad、ServerOnEnable、ServerOnDisable
• 玩家:PlayerJoin、PlayerInteract、PlayerDrop、PlayerBreak、PlayerPlace、PlayerTeleport、AsyncPlayerChat、PlayerRespawn
• 实体与物品:EntityDamage、ItemDrop
• 计时器:Timer
• 可选挂钩:BungeeCordMessage、PlayerKeyboard、EpicCraftingsPreCraft、EpicCraftingsCraft、EpicCraftingsPlaceClick

也可以通过 MagicPaperAPI.registerTrigger(...) 注册自定义触发器。

计时器是按固定 tick 间隔执行魔咒的特殊触发器。当前支持 Paper 与 Folia 两类计时器,并可通过语义动态创建:

• paperTimer() / ptimer()
• foliaTimer() / ftimer()
• addToTimer() / att()

GUI 系统支持配置菜单、分页、按钮点击执行魔咒,以及动态数据按钮。典型语义包括:

• guiOpen() / opengui()
• guiPreviousPage() / ppage()
• guiNextPage() / npage()
• guiDataClear() / cleargui()
• guiUpdate() / upgui()
• onlinePlayerButtons() / pbuttons()

物品系统是 MagicPaper 的核心模块之一,当前支持:

• 获取、给予、设置玩家物品。
• 修改名称、类型、数量、CustomModelData、耐久、附魔、隐藏标签。
• 读取和写入 NBT。
• Lore 行增删查、变量解析、模板刷新。
• 自定义属性写入、属性读取、属性缓存。
• 物品镶嵌孔、支持镶嵌地址、添加/移除镶嵌物。
• 主手物品触发魔咒。
• 物品序列化与反序列化。

常见语义包括 item()、itemGivePlayer()、itemSetPlayer()、itemNBTAdd()、itemNBTGet()、itemSetName()、newItem()、refreshVar()、itemAttributeSet()、itemBoreSet()、addItemToBore()、removeItemFromBore()、itemAddSpell()、mergeNBT()。

Buff 模块用于给目标添加有持续时间的状态;冷却模块用于限制行为频率。

• buffAdd()
• buffTimeGet()
• addCoolDown() / addcd()
• checkCoolDown() / checkcd()
• gocd()
• getcd()

MagicPaper 注册了 PlaceholderAPI 扩展,可通过以下形式取值:

%magic_spell_name%

也可以在 Magic 中使用:

• placeholderAPI() / papi()
• papiStr()

用途包括按玩家状态返回不同文本、把战斗力映射为聊天颜色、把经济余额映射为称号等。

数据实体当前默认使用 YAML 存储,配置中预留了数据库连接字段。YAML 语义包括:

• yamlManager() / yamlm()
• newYaml() / nyaml()
• yamlGet() / yamlg()
• yamlSet() / yamls()
• yamlSave()
• yamlSaveAll()
• hasyaml()
• hasyamlkey()

对象语义:

• player() / p()
• location() / loc()
• item()
• entity()
• bossbar()
• component() / minimsg()
• potion()
• particle()

行为语义:

• consoleCommand() / ccommand()
• playerCommand() / pcommand()
• senderToPlayer() / stp()
• senderToAllPlayer() / stap()
• playerTeleport() / ptp()
• playerAsyncTeleport() / patp()
• updateInventory() / upinv()
• actionMsg()
• playerCloseInv() / closeinv()
• potionAdd()

当前代码中已经包含以下挂钩能力:

• LuckPerms:Meta 设置、临时 Meta、Meta 读取、权限判断。
• PlaceholderAPI:变量解析、整句解析、Magic 占位符扩展。
• Vault:余额读取、增加、扣除、判断是否足够。
• PlayerPoints:点券读取、增加、设置、扣除、判断是否足够。
• MythicMobs:释放技能、生成生物,并包含 MythicMobs 监听扩展。
• ItemsAdder:获取自定义物品、放置自定义方块。
• AbolethPlus:数据读取、写入、编辑、过期时间、物品存取。
• AuthMe:登录状态判断。
• EpicCraftingsPlus:合成相关触发器。
• RemoteKeyboardBukkit:键盘触发器。
• ProtocolLib:物品变量刷新等发包层支持。
• MMOItems、Adyeshach、BungeeCord:相关 Hook 与辅助能力。

主要入口是 MagicPaperAPI。当前 API 支持:

• registerFunction(PaperFunction function, String... aliases):注册 MagicPaper 语义。
• registerTrigger(MagicPaperTrigger trigger):注册触发器。
• registerTimer(String id, MagicTimer timer):注册计时器。
• getSpell(...) / getSpells() / isSpell(...):读取已载入魔咒。
• execute(...):执行魔咒或单行语义。
• createNormalContext() / createSpellContext(...) / getMainContext():创建和访问上下文。
• getCoolDownManager()、addCoolDown(...)、getCoolDown(...):冷却操作。
• getMagicItem(...):包装 Bukkit ItemStack。
• hasMagicBuff(...)、getMagicBuffs(...)、getMagicBuffTime(...)、getMagicBuff(...):Buff 查询。
• openGui(...)、addGuiSetting(...):GUI 操作。

新增语义时,优先继承 PaperFunction;如果不依赖 Bukkit/Paper,也可以继承 Magic 原生的 ArgsFunction 或 OnlyStringFunction。

magic/HelloWorld.yml:

spell:
 - stap(HelloWorld)
display: "HelloWorld"
description:
 - "Send a message to all players"

命令执行:

/magicpaper spell HelloWorld

直接执行一行语义:

/magicpaper words stap(HelloWorld)

在聊天中快捷执行:

!mstap(HelloWorld)

MagicPaper 的核心思想是让服务器功能变成可组合语义。

传统插件往往把"什么时候触发、对谁触发、触发什么、如何变化"写死在配置或代码里。MagicPaper 希望把这些拆开:

• 事件由触发器提供。
• 时间由计时器提供。
• 环境对象由 Paper 语义提供。
• 第三方能力由 Hook 语义提供。
• 具体逻辑由 Magic 文本编排。

这样,复杂 Java 代码可以沉淀为稳定语义,普通使用者只需要组合这些语义即可完成服务器玩法。

• 继续完善语义文档生成,让 /magicpaper functioninfo、README 与源码保持一致。
• 稳定 Paper/Folia 执行模型,减少不同服务端调度差异带来的使用成本。
• 扩展数据实体存储,补全数据库实现与持久化策略。
• 强化 GUI、物品、触发器和 Buff 的组合能力,让它们成为可复用的服务器功能模块。
• 提供更清晰的第三方接入规范,使其他插件能快速把能力注册成 Magic 语义。
• 与 MagicRedis 等实际项目一起验证 Magic 在非 Minecraft 场景中的表达能力。
• 在样本足够时探索自然语言到 Magic 语义的转换,让中文或其他自然语言可以生成对应魔咒。

本项目采用 GNU GPL-3.0 许可证。使用、修改和分发本项目代码时,请遵循 GPL-3.0 的相关要求。