The Metin2 Quest System: Writing Quests in Lua From Scratch

What keeps a Metin2 server alive isn't its maps — it's the quests. Learning Metin2 quest creation means learning the heart of the system that tells players what to do, rewards them and moves the story forward. The good news: Metin2's quest system is a Lua-based mini-language that's surprisingly easy to learn. In this guide I'll write a quest from scratch using the same structure I use on my own server, Runa2.

How a quest file works

Every quest is built from three core blocks, and every begin must have an end:

• quest — the quest itself (a unique name).
• state — the stage of the quest. start is always the entry stage; you move to others with set_state().
• when — an event trigger such as login, levelup, kill, or an NPC .click / .chat.

The nesting order is always quest → state → when.

Your first quest: talk to an NPC and get a reward

The example below is a full quest that's given when you click an NPC, asks the player to confirm, and grants an item, experience and gold when finished:

quest welcome begin
    state start begin
        when 20095.chat."Start the quest" begin
            say_title("Villager:")
            say("Welcome, adventurer!")
            say("Will you help me?")
            local answer = select("Sure", "Not now")
            if answer == 2 then
                return
            end
            pc.setqf("welcome_step", 1)
            set_state(active)
        end
    end

    state active begin
        when 20095.chat."Finish the quest" begin
            if pc.getqf("welcome_step") == 1 then
                say("Thank you! Here is your reward.")
                pc.give_item2(27003, 5)   -- example item vnum
                pc.give_exp2(10000)
                pc.change_gold(50000)
                set_state(done)
            end
        end
    end

    state done begin
        when 20095.chat."Finish the quest" begin
            say("You have already finished this quest.")
        end
    end
end

A few details: the quoted "Start the quest" text is the menu option shown to the player — write it in your own language. select() returns the index of the chosen option (1, 2…). pc.give_item2(vnum, count) gives an item; 27003 is just an example item vnum.

Quest flags: storing progress

You store which stage a quest is at with quest flags. pc.setqf("name", value) writes a flag and pc.getqf("name") reads it. These flags are per-player and persistent. For example, a "kill 10 wolves" quest:

when 101.kill begin
    local count = pc.getqf("wolf_count") + 1
    pc.setqf("wolf_count", count)
    if count >= 10 then
        say("You killed 10 wolves!")
        pc.give_exp2(50000)
        set_state(done)
    end
end

Here 101 is the wolf mob's vnum. Each kill increments the counter; when it reaches 10, the reward is given and the quest moves to the done stage.

Common triggers

• when login begin — when the player logs in.
• when levelup begin — on level up (read the level with pc.get_level()).
• when <vnum>.kill begin — when a specific monster is killed.
• when <vnum>.click / .chat."Text" — when an NPC is clicked or a menu is opened.

Compiling and deploying the quest

Your .quest file doesn't run directly; it must first be compiled with the qc compiler. The typical flow: put the file in the server's quest folder, add it to the quest list and compile (usually make calls qc for you). Then reload it in-game with /reload q or restart the core. If there's a syntax error, qc tells you the line number — so compiling after every small change is a good habit.

Debugging tips

• Drop temporary say("reached here") lines to trace the flow.
• If an end is missing, qc warns you at compile time; indent your nested blocks to keep track.
• Keep flag names unique; reusing the same name across quests breaks progress.

Frequently asked questions

Do I need to know Lua to write quests?

You don't need to be a Lua expert. Knowing the basics — if, variables and function calls — combined with the quest system's built-in functions (say, select, pc.give_item2…) is more than enough.

Do I have to shut the server down to change a quest?

No. In most cases you compile with qc and refresh instantly with the in-game /reload q command.

How many states can a quest have?

There's no practical limit. Simple quests finish in 2–3 states; for long quest chains you can add as many stages as you need.

Want a custom quest system for your server? From battle passes to daily quests, I can build Lua quest systems — get in touch.