Korax Mod Developer Reference Guide

You can create two types of addons for Korax Mod 5: custom maps (or map packs) and mods that introduce new NPCs, monsters, items, quests etc.

Creating a custom map (pack)

Creating and editing maps

To create a new map or adapt an existing one for Korax Mod 5, use Doom Builder 2 (DB2). Korax Mod 5 is distributed with two configuration files for DB2: kmod5_Hexen.cfg and kmod5_ZDoom_Hexen.cfg; they are based on Hexen.cfg and ZDoom_Hexen.cfg from the standard DB2 distribution, adding entries for the new monsters and items (and removing definitions for some items that are not relevant).

NPCs

Three NPCs are included with the Korax Mod 5 distribution that you can use on any maps you want:

  • Merchant: buys and sells a wide variety of artifacts
  • Blacksmith: sells a wide variety of armor pieces; fully repairs your currently equipped armor; sells armorer’s hammers that allow you to (partially) repair your armor when not in town
  • Innkeeper: offers food and lodging that reset your hunger and fatigue counters to zero; sells portable food that can be used to lower the hunger counter when not in town

Editing map scripts

You can use the DB2 script editor to create and modify ACS scripts. Korax Mod 5 is distributed with modified versions of the original Hexen maps, including a decoded version of the original map scripts, some of which have been heavily modified. All new and modified scripts have a “// kmod5” comment in the script head, making it easy to locate them. This guide also includes a number of examples in the Appendix.

When configuring a map at first entry, use ENTER instead of OPEN, so that you can check the player’s inventory for identifiers that allow you to detect things like the RPG complexity setting, the game difficulty wrapper used by conversations, etc.

If you prefer not to add NPCs with conversation options, you can give the player any weapons and spells (also armor and artifacts if you so wish) when he enters a certain map using a script with conditions (check the ENTER scripts in map35 of kmod5maps.wad for an example).

Packaging your map

It is recommended that you distribute your map(s) in a ZIP archive along with a few other files:

  • yourmapname.wad
    this is the .wad containing any maps you created
  • yourmapname.bat with the following content:
    vavoom.exe -opengl -openal -debug -file yourmapname.wad
  • yourmapname.sh with the following content:
    ./vavoom.bin -file yourmapname.wad
  • yourmapname.txt
    Put any information regarding your map(s) here

Creating a mod

First, create an empty ZIP archive and rename it to yourmodname.pk3 (where “yourmodname” stands for what you want to call your mod).

Adding maps

Consult the previous chapter on pointers about creating new maps or modifying existing ones. Once you have your map(s), just copy any number of .wad files into your PK3 archive.

Adding NPCs and conversations

To add your own NPCs, you can use DECORATE. First, create your definition files in your PK3 archive (e.g. mynpcs.txt), then copy the file “decorate.txt” from kmod/basepak.pk3 into your PK3 archive. Do not delete/modify any of the existing entries or the game might not work! Add your entries at the bottom of this file in the following format:

#include "mynpcs.txt"

To link a conversation to an NPC, add the following attribute to the DECORATE definition of the NPC:

ConversationID 12345

You can use any ID for the conversation, just make sure to include the same ID in the conversation lump’s definition:

conitem myfirstnpc 12345

To add a conversation, first create a text file in your PK3 archive (e.g. convo001.txt), then copy the file “coninfo.txt” from kmod/data.pk3 into your PK3 archive. You can delete any existing entries if you don’t use those conversations in your mod, or you can leave them and add your own entries at the bottom of the file in the following format:

import convo001

Adding items

You can add new items using DECORATE. First, create your definition files in your PK3 archive (e.g. myitems.txt), then copy the file “decorate.txt” from kmod/basepak.pk3 into the root of your PK3 archive. Do not delete or modify any of the existing entries or the game might not work! Add your entries at the bottom of this file in the following format:

#include "myitems.txt"

Packaging your mod

It is recommended that you distribute your mod in a ZIP archive along with a few other files:

  • yourmodname.pk3
    this is the .pk3 containing your mod
  • yourmodname.bat with the following content:
    vavoom.exe -opengl -openal -debug -file yourmodname.pk3
  • yourmodname.sh with the following content:
    ./vavoom.bin -file yourmodname.pk3
  • yourmodname.txt
    Put any information regarding your mod here

Appendix

Script examples

Script lump header

It is recommended to start the map script lump with the following lines:

#include "zcommon.acs"
bool FirstTime = true;

The first line ensures that Doom Builder 2 accepts and compiles ACS (to ensure you don’t use a ZDOOM-only action special, check https://www.vavoomengine.com/wiki/action-specials/ first). The second line defines a variable that you can use in an OPEN or ENTER script to make sure you only run a specific action when the player enters the map for the first time.

Setting up a map for different RPG complexities

The following example checks the RPG complexity setting and modifies parts of the map according to the complexity level:

script 100 ENTER
{
         if (FirstTime == true)
        {
                FirstTime = false;
                if (CheckInventory("ComplexityIdentifierOldschool"))
                {
                        GiveInventory("Grant250Exp", 1);
                        GiveInventory("Grant250Exp", 1);
                }
                 else if (CheckInventory("ComplexityIdentifierStandard"))
                 {
                        Door_Open(31,16,0);
                        Door_Open(32,16,0);
                        GiveInventory("Grant100Exp", 1);
                }
                else if (CheckInventory("ComplexityIdentifierOff"))
                 {
                        GiveInventory("KeyCastle", 1);
                        Door_Open(31,16,0);
                        Door_Open(32,16,0);
                        SetLineTexture(1, SIDE_FRONT, TEXTURE_MIDDLE, "-");
                        SetLineTexture(1, SIDE_BACK, TEXTURE_MIDDLE, "-");
                        SetLineBlocking(1, BLOCK_NOTHING);
                }
        }
}

This example script does the following:

  • Hypothetical scenario: A castle courtyard with a locked door on the north side and two doors on the east and west sides that only open from the inside. There is a portcullis on the south side that can be raised remotely. The map exit is behind the locked door that requires the Castle Key.
  • On Old school RPG complexity, the player needs to explore a large part of the castle until he finds the rooms behind the side doors, where he throws a switch on each side to open the portcullis, then enters the boss monster’s lair, picks up the Castle Key, and finally opens the locked door. We also give the player 500 experience for entering this map (note that like in the example above, you need to pass the hidden experience giver items to the player one by one or only the first one will auto-activate).
  • If RPG Complexity is set to Standard, it opens the two side doors right away, so the player only needs to enter the rooms behind those doors and throw the switches to open the portcullis, then fight the monster, pick up the key, and open the locked door on the north, saving him a lot of exploring. We also give the player 100 experience for entering this map.
  • If RPG Complexity is Off, in addition to the side doors the portcullis also opens right away. In addition, the player automatically receives the Castle Key, so he can exit the map any time, and it’s his choice whether to go kill the boss monster first (probably worth a lot of experience), or explore any parts of the castle (artifacts, treasure and experience).

Outfitting the player

The following example gives the player his third weapon upon entering the map, as well as a light armor with poison resistance if he doesn’t already wear one. If the difficulty is set to easy or medium, it also restores the player’s health to full:

script 100 ENTER
{
         if (FirstTime == true)
        {
                FirstTime = false;
                if (CheckInventory("ClassIdentifierFighter"))
                {
                        GiveInventory("WeaponFighterAxeoftheDepths", 1);
                }
                 else if (CheckInventory("ClassIdentifierCleric"))
                 {
                        GiveInventory("WeaponClericSerpentStaff", 1);
                }
                else if (CheckInventory("ClassIdentifierMage"))
                 {
                        GiveInventory("WeaponMageWandRed", 1);
                }
                 if (!CheckInventory("LightArmorPoison"))
                 {
                        GiveInventory("LightArmorPoison", 1);
                 }
                 if (!CheckInventory("DifficultyIdentifierHard"))
                  {
                        GiveInventory("CrystalVial", 12);
                 }
        }
}

Spawn numbers

These spawn numbers can be used in scripts or as Argument 1 for items like breakable pots and suits of armor. Note that numbers 1 through 108 are unchanged versus the original Hexen spawn numbers (the select entries below 109 displayed in this table are replicated from the ZDOOM wiki for a quicker reference).

Spawn NumberSpawned Actor
1Centaur
2Slaughtaur
3Green Chaos Serpent
4Ettin
5Afrit
6Stalker
7Stalker Leader
8Wraith
9Wraith (buried)
11Blue Mana
12Green Mana
13Boots of Stealth
17Banishment Device
18Chaos Device
19Dark Bishop
20Wendigo
23Health Vial
24Quartz Flask
25Mystic Urn
26Krater of Might
72Flechette
73Torch
74Disc of Repulsion
75Red Mana
109Time Bomb
111Potion of Charisma
112Potion of Constitution
113Potion of Dexterity
114Potion of Intelligence
115Potion of Strength
116Potion of Wisdom
120Silver Bar
121Gold Bar
129Afrit Leader
130Afrit Martyr
131Flame Centaur
132Spectral Centaur
133Centaur Ghost-King
134Ettin Slinger
135Ettin Grenadier
136Ettin Commander
137Ettin Warlord
138Stone Ettin
139Magma Serpent
140Heresiarch
141Exarch
142Heresiarch for EZ mode
143Ghost
144Dark Cardinal
145Dark Advisor
146Chilling Mist
147Toxic Mist
148Lava Dweller
149Specter
150Magma Stalker
171Brown Chaos Serpent
172Icon of the Defender
173Afrit Dominator