VynAPI

The Vyn scripting language, embedded in Minecraft.

Write .vyn scripts inside resource packs and have them run in-game, reacting to what happens around the player — no Java required.

✅ Minecraft 1.21.5 · 1.21.11 · 26.1 · 26.2 — Fabric · NeoForge · Forge (Forge on 1.21.x only)

📜 What is Vyn?

Vyn is a statement-driven scripting language built for readability, with blueprints (OOP) and concurrency as first-class features. It reads like English:

~ variables
make name "Steve"

~ conditionals
check name == "Steve" do
    say "Hi, Steve!"
otherwise
    say "Who are you?"
end

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

~ functions
task double takes x do
    reply x * 2
end

~ blueprints (OOP)
blueprint Pet do
    build takes name do
        make me.name name
    end
end

VynAPI embeds this language inside Minecraft and connects it to the game — every resource pack becomes a potential script pack:

my_pack/
└── assets/
    └── example/
        └── scripts/
            └── hello.vyn     ← plain-text script, loaded by VynAPI

✨ What can you do with it?

• 🎮 React to events — every tick (onTick), arm swings (onSwingHand), any sound that plays (onPlaySound)
• 📊 Read game state — player health, hunger, position, velocity, the block you're looking at, nearby blocks, biome, time of day, colors and more
• 🔊 Do things — draw text on the HUD (debugText), send chat messages, play sounds at positions
• ⏱ Delayed logic — non-blocking wait statement, in ticks
• 📦 Ship libraries — importScript / excludeScript between scripts and packs
• ♻️ Hot reload — press F3 + T while developing; scripts reload instantly
• 🧩 Extensible — mod developers can register custom events & functions via VynAddon

📥 Installation

1. Download the jar matching your Minecraft version and loader (Fabric / Forge / NeoForge)
2. Put it in your client's mods folder
3. Launch the game and enable a resource pack that contains .vyn scripts

Quick start

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

Load the pack, press F3 + T — two lines appear in the top-left corner of your HUD, updating every tick.

📡 Events

task onPlaySound takes sound do
    player.sendMessage(sound.getName() + " @ " + sound.getPosition())
end

🧰 Script API (the essentials)

Constants: player · world · key · modLoader

Player: 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) ...

World: getBlock(x, y, z) · getDimension() · getDayTime() · getGameTime() · getBiomeAt(pos) · getGrassColor(pos) · getFoliageColor(pos) · getWaterColor(pos) · calculateDistanceBetweenPositions(a, b)

Block: getName() · getPosition() · isAir() · hasBlockTag(id) · getLightBlock() · getLightEmission() · canBeReplaced() · instrument() ...

Types: new Position(x, y, z) · new Sound(id, volume, pitch, position)

Functions: debugText(text) · importScript(packId, name) · excludeScript(packId, name)

Statement: wait <ticks> do ... end — runs a block once after N ticks, without blocking the game.

📖 Full API reference: VynAPI README

🧩 For mod developers

Subclass VynAddon to register custom events and bind native functions, types, and constants into every script environment:

public final class MyAddon extends VynAddon {

    public MyAddon() {
        super("onMyEvent"); // custom event scripts can listen to
    }

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

Fire events from anywhere in your mod:

ScriptHandler.fireEvent("onMyEvent", someValue);

Any loaded script defining task onMyEvent takes value do ... end will receive it.

🔨 Building from source

# 1) Publish the Vyn engine to your local Maven repo
git clone https://github.com/Abdelaziz1586/Vyn.git
cd Vyn && mvn clean install

# 2) Build VynAPI for the version you want
git clone https://github.com/omardotcontent/VynAPI.git
cd VynAPI && git checkout 1.21.11      # or: 1.21.5, 26.1, 26.2
./gradlew :fabric:build                # or :neoforge:build / :forge:build (1.21.x only)

❗ Important

• Client-side only — install it in your client's mods folder; scripts never run on the server. Works in singleplayer and multiplayer.
• Pick the right build — each Minecraft version has its own jar:

• Never block the client thread — use wait instead of hold for delays, and keep onTick work light (it runs 20×/second).
• Scripts run on the client only — everything they do is local to the player. That's by design: resource packs are client-side.

❓ Support & links

• GitHub: omardotcontent/VynAPI
• Issues & suggestions: GitHub Issues
• The language itself: Abdelaziz1586/Vyn

Credits: OmarDotContent & Abdelaziz_Mohamed — Vyn port by Abdelaziz_Mohamed, mod port by OmarDotContent.