VynAPI

VynAPI

Vyn脚本语言，嵌入在Minecraft中。

Description

Vyn 脚本语言，现已嵌入 Minecraft。

在资源包内编写 .vyn 脚本，让它们在游戏内运行，对玩家周围发生的事件做出反应——无需 Java。

✅ Minecraft 1.21.5 · 1.21.11 · 26.1 · 26.2 — Fabric · NeoForge · Forge（Forge 仅支持 1.21.x）

📜 什么是 Vyn？

Vyn 是一种以语句驱动的脚本语言，专为可读性而设计，将蓝图（面向对象编程）和并发作为一等特性。它的语法读起来像英语：

~ 变量
make name "Steve"

~ 条件判断
check name == "Steve" do
    say "Hi, Steve!"
otherwise
    say "Who are you?"
end

~ 循环
cycle i from 1 to 5 do
    say "Iteration: " + i
end

~ 函数
task double takes x do
    reply x * 2
end

~ 蓝图（面向对象）
blueprint Pet do
    build takes name do
        make me.name name
    end
end

VynAPI 将此语言嵌入 Minecraft 并将其与游戏连接——每个资源包都可能成为脚本包：

my_pack/
└── assets/
    └── example/
        └── scripts/
            └── hello.vyn     ← 纯文本脚本，由 VynAPI 加载

✨ 它能做什么？

  • 🎮 响应事件 — 每个游戏刻（onTick）、挥动手臂（onSwingHand）、播放任何声音（onPlaySound）
  • 📊 读取游戏状态 — 玩家生命值、饥饿值、位置、速度、你正看着的方块、附近的方块、生物群系、一天中的时间、颜色等
  • 🔊 执行操作 — 在 HUD 上绘制文本（debugText）、发送聊天消息、在指定位置播放声音
  • ⏱ 延迟逻辑 — 非阻塞的 wait 语句，以游戏刻为单位
  • 📦 分发库 — 在脚本和包之间使用 importScript / excludeScript
  • ♻️ 热重载 — 开发时按 F3 + T；脚本会立即重新加载
  • 🧩 可扩展 — 模组开发者可以通过 VynAddon 注册自定义事件和函数

📥 安装

  1. 下载与你Minecraft 版本和加载器（Fabric / Forge / NeoForge）匹配的 jar 文件
  2. 将其放入客户端的 mods 文件夹
  3. 启动游戏，并启用包含 .vyn 脚本的资源包

快速开始

task onTick do
    debugText("Health: " + player.getHealth())
    debugText("Looking at: " + player.getTargetBlock().getName())
end

加载资源包后，按 F3 + T —— 你的 HUD 左上角会出现两行文本，每刻更新一次。

📡 事件

事件 触发时机 参数
onTick 每个客户端游戏刻（每秒 20 次） —
onSwingHand 本地玩家挥动手臂时 —
onPlaySound 世界中播放声音时（排除环境音） sound 
task onPlaySound takes sound do
    player.sendMessage(sound.getName() + " @ " + sound.getPosition())
end

🧰 脚本 API（核心部分）

常量： player · world · key · modLoader

玩家： getName() · getHealth() · getFoodLevel() · getPosition() · getX/Y/Z() · getVelocityX/Y/Z() · getYaw() · getPitch() · getTargetBlock() · getSteppingBlock() · getNearbyBlocks(radius) · sendMessage(text) · playSound(id, volume, pitch) · playSoundWorld(pos, id, volume, pitch) ...

世界： getBlock(x, y, z) · getDimension() · getDayTime() · getGameTime() · getBiomeAt(pos) · getGrassColor(pos) · getFoliageColor(pos) · getWaterColor(pos) · calculateDistanceBetweenPositions(a, b)

方块： getName() · getPosition() · isAir() · hasBlockTag(id) · getLightBlock() · getLightEmission() · canBeReplaced() · instrument() ...

类型： new Position(x, y, z) · new Sound(id, volume, pitch, position)

函数： debugText(text) · importScript(packId, name) · excludeScript(packId, name)

语句： wait <ticks> do ... end — 在 N 个游戏刻后运行一次代码块，且不会阻塞游戏。

📖 完整 API 参考： VynAPI README

🧩 面向模组开发者

继承 VynAddon 以注册自定义事件，并将原生函数、类型和常量绑定到每个脚本环境中：

public final class MyAddon extends VynAddon {

    public MyAddon() {
        super("onMyEvent"); // 自定义事件，脚本可以监听
    }

    @Override
    public Consumer<Environment> onEnable() {
        return env -> {
            NativeBinder.bind(env, MyType.class);                 // 脚本中可使用 new MyType(...)
            NativeBinder.defineConstant(env, "myVersion", "1.0.0");
            env.defineFunction("myFunction", new NativeFunction((e, args) -> null));
        };
    }
}

从模组的任何位置触发事件：

ScriptHandler.fireEvent("onMyEvent", someValue);

任何已加载的脚本，只要定义了 task onMyEvent takes value do ... end，都会接收到该事件。

🔨 从源码构建

# 1) 将 Vyn 引擎发布到本地 Maven 仓库
git clone https://github.com/Abdelaziz1586/Vyn.git
cd Vyn && mvn clean install

# 2) 为你想要的版本构建 VynAPI
git clone https://github.com/omardotcontent/VynAPI.git
cd VynAPI && git checkout 1.21.11      # 或：1.21.5, 26.1, 26.2
./gradlew :fabric:build                # 或 :neoforge:build / :forge:build（仅 1.21.x）

Important

❗ 重要说明

  • 仅限客户端 — 将其安装在客户端的 mods 文件夹中；脚本永不在服务器上运行。在单人游戏和多人游戏中均有效。
  • 选择正确的构建版本 — 每个 Minecraft 版本都有对应的 jar 文件：
Minecraft Java Fabric Forge NeoForge
1.21.5 21 ✅ + Fabric API ✅ ✅
1.21.11 21 ✅ + Fabric API ✅ ✅
26.1 25 ✅ + Fabric API ❌ ✅
26.2 25 ✅ + Fabric API ❌ ✅
  • 切勿阻塞客户端线程 — 请使用 wait 而非 hold 进行延迟，并保持 onTick 内的操作轻量（它每秒运行 20 次）。
  • 脚本仅在客户端运行 — 它们所做的所有事情都只影响玩家本地。这是有意设计的：资源包本就是客户端内容。

❓ 支持与链接

鸣谢： OmarDotContent 和 Abdelaziz_Mohamed — Vyn 移植作者：Abdelaziz_Mohamed，模组移植作者：OmarDotContent。