Customs

With Main.dll, a custom item had to be added on both sides: the server defined it in its Item.txt, and the client needed a regenerated item.bmd plus the Encoder tables packed into ClientInfo.bmd. If they did not match, the item looked wrong or the server rejected it.

Now the server is the only source. At login, the server sends the client a catalog with every definition: items, monsters, effects, pets and tooltips. The client only needs the models (.bmd files and their textures) in its Data folder. There is no item.bmd to regenerate and no code to touch.

Client and server must be the same version (0.97.20 or later). This system does not work with the DLL client.

Where the files go

A persistent Docker volume is not updated when you pull a new image: whatever you add there is kept across versions.

After adding or changing a custom, restart the server and log in again to receive the new catalog. The JSON files are validated at startup: a file with errors is discarded entirely and the reason is written to the GameServer log.

Indexes: the classic range and the extended one

Each item section (swords, axes, maces, spears, bows, staffs, shields, helms, armors, pants, gloves, boots, wings, helpers, potions and jewels) has 32 indexes in 0.97k, from 0 to 31.

On top of that, each section accepts indexes 32 to 511: these are added items, which fit without overwriting any original item. An added item must state which original item it imitates (the Behavior column): that decides the logic the game has written per item type, such as whether it uses arrows, whether it is a wing or a jewel, or which excellent options it can have. Everything else (name, stats, size, model, glow, effects) comes from its own row.

Example 1: an item with the Encoder tables

If you already have customs built for the DLL, the Encoder tables are still used without converting anything. They go in the server’s Data/Custom/Encoder/: CustomItem.txt, CustomGlow.txt, CustomBow.txt, CustomMonster.txt, ItemPosition.txt and MapFog.txt.

The Knight Blade at index 0,20:

// Data/Custom/Encoder/CustomItem.txt
00,020		22		"Sword21"		// Knight Blade

// Data/Custom/Encoder/CustomGlow.txt
00,020		191	165	127		// Knight Blade

Model in the client: bin/Client/Data/Item/Custom/20/ (sword21.bmd and its textures).

Example 2: an item in the extended range

The same model as an added item, at 0,32. Everything goes in one row of Data/Item/Item.txt: after the usual columns you add the behavior, the model folder and name, and the glow color in RGB.

32	0	22	1	4	1	1	0	"Crimson Knight Blade"	...	00,020	"Item\Custom\20\"	"Sword21"	255	40	40

It behaves like the Knight Blade (00,020), uses the Sword21 model and glows red. Copy a full row from the section and adjust its stats: the ... in the example stands for the usual columns and is not written like that.

To test it with a GM account: /make 0 32.

Example 3: a full set

The Great Dragon set at index 21 of sections 7 to 11 (helm, armor, pants, gloves and boots):

// Data/Custom/Encoder/CustomItem.txt
07,021		0		"HelmMale22"		// Great Dragon Helm
08,021		0		"ArmorMale22"		// Great Dragon Armor
09,021		0		"PantMale22"		// Great Dragon Pant
10,021		0		"GloveMale22"		// Great Dragon Glove
11,021		0		"BootMale22"		// Great Dragon Boot

Models in the client: bin/Client/Data/Player/Custom/21/. The same pieces can also be defined without the Encoder, with the model columns in Item.txt ("Player\Custom\21\" "HelmMale22").

Custom equipment is also visible on other players and on the character selection screen.

Example 4: effects, pose and tooltip

Data/Custom/Items/<section>_<index>.json adds to an item, custom or original, effects drawn on the model’s bones, its pose in the inventory and its own tooltip lines.

Wings with flares and particles:

{
  "item": "12,032",
  "effects": [
    { "on": "equipped", "type": "sprite", "texture": "Effect/Flare.jpg",
      "bones": [5, 6, 7, 8, 18, 19], "color": [0.5, 0.0, 0.0], "scale": 0.6,
      "pulse": { "speed": 0.002, "scale": 0.2, "color": 0.4 } },
    { "on": "equipped", "type": "particle", "particle": 1230,
      "bones": [13, 31], "chance": 2, "color": [0.8, 0.8, 0.3], "scale": 0.5 }
  ]
}

The tooltip takes up to 6 lines, as plain text ("Zen picker") or with a color ({ "text": "Zen picker", "color": "gold" }). Colors: white, blue, red, gold, green, darkred, purple, darkblue and darkgold.

The server ships two real examples: 03_000.json fixes the Light Spear’s position in its inventory slot, and 13_400.json sets the Pet Rudolph’s pose and tooltip.

Example 5: a custom pet

Pet Rudolph (13,400) circles around the player and picks up nearby zen. It is included as an example and uses four files:

{
  "item": "13,400",
  "blendMesh": 0,
  "movement": { "type": "orbit", "radius": 50, "period": 4000, "height": 20 },
  "abilities": [ { "type": "pickup", "what": "zen", "range": 3, "interval": 1000, "delay": 1500 } ]
}

The client draws the movement; the abilities, such as picking up zen, are run by the server. To test it: /make 13 400.

Example 6: a custom monster

With the Encoder table, Data/Custom/Encoder/CustomMonster.txt (index, type 0 = NPC and 1 = monster, golden, scale, folder and model):

152		1		1		2.0		"Monster\\Karane\\"		"Karane"		// Karane

Or directly in Data/Monster/Monster.txt, with the same columns at the end of the row:

152	0	"Karane"	...	0	0	1	1	2.0	"Monster\Karane\"	"Karane"

Model in the client: bin/Client/Data/Monster/Karane/.

Custom wings

Custom wing stats (defense and damage constants) are defined in the server’s Data/Item/CustomWing.txt. As with the rest of the catalog, the server is in charge: the client keeps no copy of its own.

Item.txt column reference

Optional columns at the end of each row (* = no value):

From the web panel

The admin panel has editors for items (Item.txt) and monsters (Monster.txt), and for the custom zones (CustomSafeZone, CustomPkFree, CustomNpcMove). See Admin Panel.

Server .txt files must be saved in ANSI / Windows-1252 without BOM: UTF-8 breaks accented characters in the client.