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.

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?

Statement-Driven Scripting

Vyn is built for readability, with blueprints (OOP) and concurrency as first-class features. It reads like plain English, so anyone can pick it up without a programming background.

~ variables
make name "Steve"

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

Loops & Functions

Cycle through ranges and define reusable tasks with a clean, minimal syntax.

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

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

Blueprints (OOP)

Vyn supports object-oriented design through blueprints, letting you structure scripts around reusable objects.

blueprint Pet do
    build takes name do
        make me.name name
    end
end

In-Game Integration

VynAPI embeds this language inside Minecraft and connects it to the game, so every resource pack becomes a potential script pack.

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

Core Features!

React to Events

Scripts respond to what happens around the player: every tick (onTick), arm swings (onSwingHand), and any sound that plays (onPlaySound).

Read Game State

Pull live data straight from the game: 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 with debugText, send chat messages, or play sounds at specific positions in the world.

Delayed Logic

The non-blocking wait statement lets you schedule logic after N ticks without freezing the game.

Ship Libraries

Share code between scripts and packs using importScript / excludeScript.

Hot Reload

Press F3 + T while developing and your scripts reload instantly, no restart required.

Extensible

Mod developers can register custom events and functions into every script environment 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, and two lines appear in the top-left corner of your HUD, updating every tick.

Events!

Available 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, non-blocking

📖 Full API reference: VynAPI README

For Mod Developers!

Registering Custom Events

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));
        };
    }
}

Firing Events

Fire events from anywhere in your mod, and any loaded script defining a matching task will receive it.

ScriptHandler.fireEvent("onMyEvent", someValue);

task onMyEvent takes value do
    ~ handle the fired event
end

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.

Version Support

Support & Links!

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