Metin2 Quest Files: Location, Loading, and Common Errors

New Metin2 private server admins frequently run into the same set of quest-related problems: files that don't load, functions that aren't found, or quests that silently fail. Most of these problems come down to file placement and loading order. This guide covers everything you need to know.

1. Quest File Location

Quest files live inside the server's locale directory:

share/locale/[xx]/quest/

Replace [xx] with your server's locale code — commonly de, en, tr, pl, or uk. The exact path depends on your server binary configuration and the LOCALE setting in your server config files.

The quest folder typically contains:

  • *.quest — compiled quest scripts (from source .quest files)
  • functions.lua — shared helper functions available to all quests
  • globals.lua — shared constants and tables
  • state.lua — quest state management helpers (on some server versions)

2. How Quests Are Loaded

The quest engine loads files in a specific order at server startup:

  1. globals.lua is loaded first — constants defined here are available to all subsequent files
  2. functions.lua is loaded second — helper functions defined here are available to all quests
  3. All *.quest files in the quest directory are loaded alphabetically

This means that if functions.lua is missing or has a syntax error, all quests on your server will fail to load. The server log will show something like:

[QUEST] failed to load functions.lua
[QUEST] script load error

Always fix functions.lua and globals.lua errors before debugging individual quests.

3. functions.lua and globals.lua — Are They Included by Default?

No. These files are NOT included with a standard server installation. You need to provide them. Most server packs circulating in the community include versions of these files, but they vary significantly between packs. Common functions you will find in functions.lua include:

  • get_time_format(sec) — converts a number of seconds to a human-readable string like "2 hours, 15 minutes and 30 seconds"
  • time_min_to_sec(n), time_hour_to_sec(n), time_day_to_sec(n) — time unit converters
  • is_valid_number(num) — number validation
  • table_is_in(t, element) — table search helper
  • clear_dungeon() — clears dungeon state

If your quest uses get_time_format() and you don't have a functions.lua that defines it, the quest will throw a nil function error at runtime.

4. Common Quest Errors and Fixes

Error: attempt to call a nil value (global 'get_time_format')

Cause: get_time_format is not defined — either functions.lua is missing, it loaded with an error, or this function isn't in your version of functions.lua.
Fix: Add the function to functions.lua or use the Dungeon Generator which includes the function in the downloaded zip.

Error: quest [name] already registered

Cause: Two .quest files define the same quest name (the quest name_zone begin identifier).
Fix: Rename one of the quests — the identifier in the file and the filename should both be unique.

Timer fires but d.select() returns false

Cause: server_timer() was called without a map index argument, so the arg is 0. d.select(0) always fails.
Fix: Always pass d.get_map_index() as the third argument: server_timer("name", delay, d.get_map_index()).

Quest loads but NPC chat option never appears

Cause: The NPC VNUM in the quest doesn't match the actual NPC on the map, or the NPC isn't flagged as a quest NPC.
Fix: Verify the VNUM in mob_proto and ensure the NPC has the NPC type, not MONSTER.

d.setf / d.getf values reset unexpectedly

Cause: The dungeon instance was reset (e.g. all players left and the instance was garbage collected) before the quest read the value.
Fix: Initialize all flags in the when login begin handler with a guard: if (d.getf("initialized") == 0) then ... end.

5. Regen Files

Regen files define mob spawns for a zone or dungeon floor. They live alongside quest files at:

share/locale/[xx]/quest/dungeon/yourquest_floor1.txt

Each line follows the format:

r  X  Y  sizeX  sizeY  direction  isAggressive  respawnTime  maxCount  count  mobVnum

These are loaded with d.set_regen_file("dungeon/yourquest_floor1.txt") inside the quest Lua code.

6. Generating Quest Files Automatically

Writing dungeon quests by hand — getting the timer scoping, state flags, floor sequencing, and regen format all correct — takes significant experience. The Metin2 Dungeon Quest Generator handles all of this automatically. Configure your dungeon through a visual form and download a zip containing the quest file, the Lib.lua, all regen files, and smart-extracted functions.lua and globals.lua with only the helpers your quest actually uses.