Custom Jobs Guide

1 Choose a Job ID

Pick an unused ID between 4351 and 9999. The patch fills the sprite tables from 4351 up to MaxJob, which is 10000 and exclusive, so an ID below 4351 gets no body path and 10000 itself is never populated. 4351 to 4360 belong to Gravity's 2025 jobs (Druid, Karnos, Alitea and their baby and riding forms), so start at 4361 unless you mean to override one. The ID must match on both client and server.

For this guide, we'll use EXAMPLE_JOB with ID 4435. A complete working example is included in the WARP; see the Inputs/Luafiles514/ folder and examples/CustomJobs/data/ for all the files.

2 Client-Side Lua Files

The CustomJobs patch uses 7 separate .lua files in data/luafiles514/lua files/JobInfo/. Each file handles one aspect of the custom job. Your custom entries are loaded at runtime; stock job data is loaded from the GRF automatically.

PCIds.lua: Job ID Definition

Defines your custom job's numeric ID. This is the master ID that all other files reference. It must match the server-side JOB_ enum value exactly. Each custom job needs a unique ID in the range 4351 to 9999.

PCIds = PCIds or {}
PCIds.EXAMPLE_JOB = 4435

PCNames.lua: Display Name

Sets the name shown in the BasicInfo window, character select screen, and party window. This is the human-readable name players see in the UI. Without this entry, your custom job will display as "Poring".

PCNames = PCNames or {}
PCNames[PCIds.EXAMPLE_JOB] = "Example Job"

-- You can also rename stock jobs. Both forms work, pick whichever:
PCNames[PCIds.WARLOCK]      = "Dark Wizard"     -- by name
PCNames[4055]               = "Dark Wizard"     -- by raw ID (same thing)
PCNames[PCIds.LORD_KNIGHT2] = "Holy Knight"     -- mounted variant
PCNames[4014]               = "Holy Knight"     -- same thing, raw

Gender-specific names (optional)

Multi-language names (optional)

PCPaths.lua: Sprite Folder Name

Maps your job ID to the body sprite folder/file name. This value must match your .spr and .act filenames exactly; it is case-sensitive and ASCII only (no Korean characters). The client appends the CP949 gender suffix automatically.

Example: if you set "EXAMPLE_JOB", the client looks for EXAMPLE_JOB_³².spr (male) and EXAMPLE_JOB_¿©.spr (female) in the body sprite directory.

PCPaths = PCPaths or {}
PCPaths[PCIds.EXAMPLE_JOB] = "EXAMPLE_JOB"

PCPals.lua: Palette Prefix

Controls which palette files are used when players change hair/clothes colors via @dye or the stylist NPC. Palette files follow the pattern jobname_gender_N.pal where N is the color index. For most custom jobs, inherit from an existing job (Novice is the safest default). If you create your own palette files, set this to your custom prefix string. This is a filename prefix, not a folder. The .pal files sit flat in the body palette folder, data/palette/¸ö/ (몸, Body), as <prefix>_<gender>_<N>.pal. A folder named after the prefix is never opened.

PCPals = PCPals or {}
-- Inherit Novice's palettes. The (or "") fallback handles cases
-- where PCPals hasn't been populated from GRF yet.
PCPals[PCIds.EXAMPLE_JOB] = (PCPals[PCIds.NOVICE] or "")

PCHands.lua: Weapon Sprite Folder

Points your job at a weapon/hand sprite folder, so that each weapon type (sword, axe, bow, and so on) draws the right sprite when your job equips it. This table is read when you apply the patch, not by the client: WARP bakes every quoted row into the patched exe, after the five official rows Gravity ships for 2025 (Druid 4351 with its baby form 4352, Karnos 4353 with its baby form 4354, and Alitea 4355; the ids and folder names are Gravity's), so re-apply WARP after editing it. Only a quoted string counts as a row; an inheritance form such as (PCHands[PCIds.NOVICE] or "") means "stock hands" and adds nothing. The WARP log lists the rows it baked and the lines it skipped.

PCHands = PCHands or {}
PCHands[PCIds.EXAMPLE_JOB] = (PCHands[PCIds.NOVICE] or "")   -- stock (Novice) hands: the example ships no weapon sprites
-- PCHands[PCIds.EXAMPLE_JOB] = "example_job"                -- a quoted folder name is a baked row. Only when you ship
--                                                            -- data\sprite\<race>\example_job\example_job_<gender>_<weapon>.spr

PCImfs.lua: IMF Animation Reference

Links your job to its IMF (animation timing) files. IMF files control head positioning and animation frame timing. Keeps the seven-file set complete. The client builds the IMF filename from the sprite name plus the gender suffix, so the inheritance form below is all you need here; what your job cannot do without is the pair of .imf files in data/imf/ (Step 4). Without those, your character renders without a head.

PCImfs = PCImfs or {}
PCImfs[PCIds.EXAMPLE_JOB] = (PCImfs[PCIds.NOVICE] or "")

PCFuncs.lua: Core Helper Functions

Defines the classic helper functions (ReqPCPath, ReqPCJobName, GetValFromTbl, GetHalter and friends). The 2025-07-16 patch never calls them: it reads the tables straight through the Lua C API, so they are kept for compatibility with other clients, not because this one needs them. What earns this file its place are the three passes at the bottom: it auto-populates display names for stock jobs from the GRF, mirrors those names onto their peco/dragon/mado mounted variants, and wraps InitSkillTreeView so JOB_SKILL_TIER overrides (used by multi-tier custom job chains) take effect. Do not remove or rename any functions in this file; deploy it unedited. You should not need to edit this file; add your custom job data to the other 6 files instead. The WARP Inputs include a working copy.

Inheritance Tables (optional)

An alternative to the (PCPals[PCIds.NOVICE] or "") snapshot fallback. PCFuncs.lua exposes one inheritance table per lookup type, queried by the matching MapPC* function whenever the primary lookup misses:

Each entry maps a job ID to its parent job ID. When a primary lookup (PCPaths[jobid]) returns nil, the helper asks the matching Map* function, which reads the inherit table to find the parent and re-runs the full lookup against it; so chains traverse correctly even multiple levels deep.

PCPathInheritTbl = PCPathInheritTbl or {}
PCImfInheritTbl  = PCImfInheritTbl  or {}
PCPalInheritTbl  = PCPalInheritTbl  or {}
PCHandInheritTbl = PCHandInheritTbl or {}
PCNameInheritTbl = PCNameInheritTbl or {}

-- Tier 3 inherits from tier 2, tier 2 inherits from tier 1
PCPathInheritTbl[PCIds.EXAMPLE_JOB_3RD] = PCIds.EXAMPLE_JOB_2ND
PCPathInheritTbl[PCIds.EXAMPLE_JOB_2ND] = PCIds.EXAMPLE_JOB
-- (Repeat for any of the other four tables you want to chain.)

Inherit tables are best for genuine tier-style relationships where the parent's value should be used verbatim. The (or "") snapshot is fine for one-off "use Novice" fallbacks where the parent's data is already loaded.

Skills, baby forms, mounts and Doram

Skill Tree Files (optional)

If your custom job has skills, you also need two files in data/luafiles514/lua files/skillinfoz/:

jobinheritlist.lub: Skill Inheritance

Defines which parent job your custom job inherits skills from. Add your job's ID to the JOBID table and a JOB_INHERIT_LIST entry:

-- In the JOBID table:
JOBID.JT_EXAMPLE_JOB = 4435

-- In the JOB_INHERIT_LIST table:
[JOBID.JT_EXAMPLE_JOB] = JOBID.JT_NOVICE   -- inherits from Novice

skilltreeview.lub: Skill Tree Tab Name

Controls the tab label shown in the skill tree window. Without this, your job's tab will say "Etc":

-- In the SKILL_TREEVIEW_FOR_JOB table:
[JOBID.JT_EXAMPLE_JOB] = JOBID.JT_EXAMPLE_JOB

-- After the table, set the tab name:
JobSkillTab.ChangeSkillTabName(JOBID.JT_EXAMPLE_JOB, "Example Job")

Multi-Tier Job Chains (advanced)

For job systems with multiple tiers (like Night Watch: Gunslinger → Rebellion → Night Watch), the skill tree tabs are controlled by tiers. The C++ assigns tier 0 to the root job (whose parent is Novice). Tiers 0 and 1 merge on the first tab. Override tiers for higher classes via JOB_SKILL_TIER in PCIds.lua:

-- Example: 3-tier job chain (Base → 2nd → 3rd)
-- The base class is NOT listed, C++ naturally gives it tier 0
-- (same as Novice), so they merge on the first tab.
JOB_SKILL_TIER = JOB_SKILL_TIER or {}
JOB_SKILL_TIER[PCIds.EXAMPLE_JOB_2ND] = 1   -- 2nd tab
JOB_SKILL_TIER[PCIds.EXAMPLE_JOB_3RD] = 2   -- 3rd tab

The InitSkillTreeView wrapper in PCFuncs.lua reads this table at runtime. Use consecutive tier numbers (0, 1, 2); skipping a tier creates an empty tab. Tab names are set via ChangeSkillTabName in skilltreeview.lub (same convention as Night Watch: base class name first, then "2nd", "3rd"):

-- 3 named tabs + auto "Etc" tab (matches Night Watch: "Gunslinger", "2nd", "3rd")
JobSkillTab.ChangeSkillTabName(JOBID.JT_EXAMPLE_BASE, "Base Job", "2nd", "3rd")
JobSkillTab.ChangeSkillTabName(JOBID.JT_EXAMPLE_2ND,  "Base Job", "2nd", "3rd")
JobSkillTab.ChangeSkillTabName(JOBID.JT_EXAMPLE_3RD,  "Base Job", "2nd", "3rd")

The inheritance chain in jobinheritlist.lub defines the tab grouping:

[JOBID.JT_EXAMPLE_BASE] = JOBID.JT_NOVICE        -- Novice+Base merge on tab 1
[JOBID.JT_EXAMPLE_2ND]  = JOBID.JT_EXAMPLE_BASE   -- tab 2
[JOBID.JT_EXAMPLE_3RD]  = JOBID.JT_EXAMPLE_2ND    -- tab 3

Baby Class Support (limited)

Baby variants of custom jobs need sprite scaling entries to render at 75% size (like stock baby classes). Add to PCIds.lua:

-- Baby class sprite scaling (shrinks baby jobs to 0.75x)
-- Scales[1] = "3F400000" = 0.75 in IEEE 754 float
Scales = Scales or { "3F400000", "3F51EB85", "3F4CCCCD" }
Shrink_Map = Shrink_Map or {}
Shrink_Map[PCIds.EXAMPLE_JOB_B] = Scales[1]

The baby job ID must also be defined in PCIds.lua and have its own sprite files, PCPaths, PCPals, etc.

Mount Support

To enable the Boarding Halter (item 12622) for a custom job, define the mount ID and halter mapping in PCIds.lua:

-- Mount definitions
PCMounts = PCMounts or {}
PCMounts.EXAMPLE_JOB_RIDING = 4437   -- riding sprite job ID

Halter_Table = Halter_Table or {}
Halter_Table[PCIds.EXAMPLE_JOB] = PCMounts.EXAMPLE_JOB_RIDING

When the Boarding Halter is used, rAthena applies SC_ALL_RIDING and the client calls GetHalter(jobid); the returned riding ID becomes the actor's effective job for sprite/name resolution. That means the riding ID needs its own complete entry set across all five Lua data tables; treat it as a separate custom job:

Plus the actual asset files for the riding variant: body .spr/.act, costume_1/ .spr/.act, IMF (male + female), and icon BMP (icon_jobs_RIDING_ID.bmp + _die.bmp); all the same artifacts a base custom job needs (Steps 3-5). If you support multiple mount types (like Rune Knight's five dragon colors), each gets its own ID and full entry set, and Halter_Table can map the same base job to multiple mounts via additional Lua logic.

Doram Race

The client routes sprite/offset/scale/nameplate lookups through is_doram_job_id, which by default only knows the stock Summoner IDs. CustomJobs adds a Lua-table override so any custom job can opt in. Define PCRace in any JobInfo Lua file:

PCRace = PCRace or {}
PCRace[PCIds.MY_DORAM_NOVICE] = "doram"
PCRace[PCIds.MY_DORAM_2NDCLASS] = "doram"

Any non-nil value enables the Doram path; "doram" reads well and reserves room for future race values. Once set, the job's body sprite loads from data/sprite/도람족/몸통/ (CP949 µµ¶÷Á·/¸öÅë/) instead of 인간족/몸통/, and item offsets, sprite scale, shadow position, and nameplate Y-offset all follow the Doram code paths the stock Summoner uses.

Your sprite files for Doram custom jobs go in the Doram folder, not the human folder shown in Step 3:

(Same .act, costume_1/, IMF, palette, and icon rules as Step 3, just with µµ¶÷Á· instead of Àΰ£Á· for the body sprites.)

3 Sprite Files

Sprites go in the human race body directory. The Korean folder names are CP949-encoded on disk.

Sprite Files (4 base, 4 costume)

Korean Folder Reference

Using Existing Sprites as Placeholders

If you don't have custom sprites yet, copy an existing job's sprites and rename them. examples/CustomJobs/data/sprite/ includes Novice sprites you can use as a starting point.

4 IMF Files

One IMF per gender, carrying the head offsets for every frame of every action. Place them in data/imf/:

data/imf/example_job_³².imf    (male, ³² is CP949 for 남)
data/imf/example_job_¿©.imf    (female, ¿© is CP949 for 여)

Copy from any existing job. examples/CustomJobs/data/imf/ includes working IMF files.

5 Icon Files

Job icons go in data/texture/À¯ÀúÀÎÅÍÆäÀ̽º/renewalparty/ (À¯ÀúÀÎÅÍÆäÀ̽º is CP949 for 유저인터페이스):

icon_jobs_4435.bmp          (normal icon, 25x25 BMP)
icon_jobs_4435_die.bmp      (dead icon, 25x25 BMP)

Replace 4435 with your actual job ID. Copy from any existing job icon as a placeholder. examples/CustomJobs/data/texture/À¯ÀúÀÎÅÍÆäÀ̽º/renewalparty/ includes the Novice icons.

25x25 is the size the shipped example icons use; copy one of them and repaint it rather than guessing the dimensions.

6 WARP Patch

In WARP, open the SPECIAL CUSTOMIZATIONS group and tick Enable Custom Jobs (Reforged). MaxJob is hardcoded to 10000, so there is nothing to configure.

Applying the patch asks up to three questions:

Copy Lua Files

Whether to copy the seven Lua files out of WARP's Inputs/ folder for you. Answer Yes and WARP asks for a target folder next, then writes them to data\Luafiles514\Lua Files\JobInfo inside whatever you pick. The default is the folder holding the patched exe, so choose your client folder to use them straight away, or take the default and move them across with the exe.

Error Display ($showFailures)

How Lua loading errors are reported:

7 Server-Side (rAthena)

Your rAthena server needs to know about the new job: 6 source files, 1 message file and 4 database files, plus an optional skill tree entry. Make every edit, then rebuild the server.

A. Job ID: src/common/mmo.hpp

Add your job to the e_job enum, before JOB_MAX:

JOB_EXAMPLE_JOB = 4435,
JOB_MAX,

B. Map ID: src/map/map.hpp

Add a corresponding MAPID entry to the e_mapid enum (before the 2-1 Jobs section):

MAPID_EXAMPLE_JOB,

C. Job Conversion: src/map/pc.cpp

Add entries to both conversion switch statements:

// In pc_jobid2mapid(), converts job ID to map ID:
case JOB_EXAMPLE_JOB:    return MAPID_EXAMPLE_JOB;

// In pc_mapid2jobid(), converts map ID back to job ID:
case MAPID_EXAMPLE_JOB:  return JOB_EXAMPLE_JOB;

D. Job Validation: src/map/pc.hpp

Update the pcdb_checkid macro so the server recognizes your job ID as valid. Add or extend the range to include your job:

// In pc.hpp, pcdb_checkid_sub is one long chain of ranges joined by ||
// and every line ends with a backslash. Add yours as another term,
// after the last one and before the closing parenthesis:
||	( (class_) >= JOB_EXAMPLE_JOB && (class_) <= JOB_EXAMPLE_JOB ) \

E. Script Constants: src/map/script_constants.hpp

Export the job constant so NPC scripts can reference it. Add both entries:

// Near the other job exports:
export_constant(JOB_EXAMPLE_JOB);

// Near the EAJ_ exports:
export_constant2("EAJ_EXAMPLE_JOB",MAPID_EXAMPLE_JOB);

F. Job Name: src/char/inter.cpp

Add a case to the job name function so the char-server can display the name. Pick an unused msg_txt ID below 300, the char-server's message-table size (check conf/msg_conf/char_msg.conf; the stock file stops at 229). An ID of 300 or higher is rejected at load with an "Invalid message ID" warning, and the name comes back as ??.

case JOB_EXAMPLE_JOB:
    return msg_txt( 230 );  // first free slot

Then add the name string to conf/msg_conf/char_msg.conf:

230: Example Job

G. Database Files: db/re/ (or db/pre-re/)

Add your job to four YAML database files. The easiest approach is to add your job to an existing group (e.g., Knight or Novice). Find a Jobs: block and add your job name:

    Jobs:
      Knight: true
      Example_Job: true   # <-- add this line

Do this in all four files:

H. Skill Tree (optional): db/import/skill_tree.yml

- Job: Example_Job
  Inherit:
    - Job: Novice
  Tree:
    - Skill: SM_SWORD
      MaxLevel: 10
    # ... add your skills

I. Job Change NPC (example)

prontera,150,180,5	script	Job Master	2_M_SAGE,{
    if (BaseLevel < 10) {
        mes "Come back at base level 10.";
        close;
    }
    jobchange JOB_EXAMPLE_JOB;
    mes "You are now an Example Job!";
    close;
}

Or use the GM command in-game: @job 4435

File Checklist

Check off items as you complete them. Progress is saved in your browser.

Files in the repository

Two folders in the WARP0716 repository, under examples/CustomJobs/. A WARPGATE install already has them on disk, because the WARP tab installs the whole repository.

The example job

examples/CustomJobs/data/ is a complete working job using job ID 4435 (with baby variant 4436) and Novice placeholder sprites: 31 files, the seven Lua files, both genders' sprites with their costume slots, the four IMFs and the party icons. The folder mirrors the actual data/ directory structure with correct CP949-encoded Korean paths; you can copy the contents directly into your client's data/ folder or pack them into a GRF, add the job on the server (step 7), and it renders. The fastest way to build your own job is to copy this set and rename.

The WARP Inputs also include this example; enable the CustomJobs patch and these files work out of the box.

The Lua reference

examples/CustomJobs/lua-reference/ holds the seven complete JobInfo tables with every stock job listed: PCIds, PCNames, PCPaths, PCPals, PCHands, PCImfs and PCFuncs. Read them to see how an existing job is written before you add yours, and to check that an ID is free. Nothing in them needs editing.

Troubleshooting