29 ratings
Modding WazHack
By Waz
This guide describes how to use the modding features of WazHack.
Creating a new Mod
A mod for WazHack consists of a folder or simple text and image files. That folder is inside a "mods" folder which you will need to create in a special location:

On Windows:

On MacOSX:
~/Library/Application Support/Waz/WazHack/mods

On Linux:

On Android:

On iOS, mods cannot be editted on-device. Create them on a PC then upload them to mod.io as described below.

Inside this "mods" folder you create your own folder (eg. "MyMod"), which must have these files:

  • metadata.txt
  • preview.jpg

The metadata.txt is in a simple "text tree" format that WazHack uses for most files. It is a tree structure of key-value pairs where depth is defined by single spaces. For example:

WazHackMod name Waz Examples description Some example character classes. tags Balanced,Allow on Mobile

Note the single space at the start of the "name" and "description" lines. Once uploaded, an additional "id" property will be added to the file automatically; it should not be changed.

The "tags" is a list of tags from the permitted list. If the tags include "Allow on Mobile", then you are giving permission for the mod to be published to users of the mobile version. Note that this does not guarantee that it will be made available.

The preview.jpg is the image you choose to represent your mod. Perhaps a group shot of your character classes. It should be a 16:9 image. Extensions of png, jpg, and jpeg are accepted.

Your mod's folder will also contain one .txt file for each new character class you wish to define, which use a similar file format.

See the "Waz Examples" mod for some examples: http://steamcommunity.com/sharedfiles/filedetails/?id=845557618
Creating a new Character Class
After creating your empty mod, you need to add some content. Currently, WazHack supports adding new character classes based on species of creatures in the game. You can play the game as a Kobold if you want, and you can give him any starting equipment you like. Obviously this can easily be abused to make overpowered classes that may spoil the game for you or for anyone else who tries your classes, so be sure to warn players if your mod includes overpowered classes both in the description and by adding the tag "Unbalanced" to the tags in the metadata.txt.

A new class is defined by a simple .txt file in your mod's folder, alongside the "metadata.txt" file described in the previous section.

Here is a sample, which if put in a orc.txt file defines a weak Orc:

WazHackModClass name Orc Adventurer description The Orc Adventurer is a furious creature with typically crude orcish gear. content type orc inventory 0 uncursed +0 orcish helm 1 uncursed +0 orcish ringmail 2 uncursed +0 orcish shield 3 uncursed +0 orcish shortsword 4 3 loaves of bread sex 1 pet giant rat petLevel 1 talents 0 gastronomy 1 dual wielding 2 first aid 3 mighty blows 4 shield parry 5 weapon knowledge 6 fury 7 courage belief foodism alignments 0 chaotic good,wild 1 neutral,even 2 chaotic evil,angry,cruel skills life,life,knives stats str 2d5+10 int 2d4+4 total 68 visuals skin #ff1111,#ffffff,0.5 scale 0.9 speed 1.1

Note again the use of single spaces to define the structure of the tree of information.

If you wish to make human characters, the "man" and "woman" types can also be used.

The supported properties under the "content" structure are:

The name of the creature from which the new class derives. May also be "man" or "woman".
a structure of numbered items, each item is like an in-game "wish", except loose terms like "bread" and not supported and capitalization must be correct.
0=Neuter, 1=Male, 2=Female, 3=Either, 4=Plural
creature name of pet (eg. cat)
the experience level of the pet
a structure of numbered items, each item is one of the in-game talents (eg. weapon knowledge). Note that Nightmare Mode is added for all classes regardless.
foodism, norse gods, atheism, inner power, or darkness
a structure of numbered items, each item is an alignment (chaotic good, chaotic evil, neutral, lawful good, lawful evil) and an adjective for that alignment (eg. neutral,boring)
a comma-separated list of skills to add 1 skill point to. Choices are: life, death, light, dark, knives, swords, greatswords, backswords, axes, clubs, polearms, bows, throwing, music.
a structured list of items, each item is a stat (eg. "str" or "dex") as the key and a dice roll as the value. The dice role also defines the allowed range (eg. 2d6+3 is 5 to 15). An additional item "total" is an integer giving the total number of points allowed (ignored if impossible given dice).
a structured list of items, each items, each choosing styles and colors (see below)
1 = normal scale for that creature, 0.5 = half-size, etc. Don't expect extremes to be playable.
1 = normal speed for that creature, 0.5 = half speed, etc.

Each of the "visuals" chooses an element of the creature's body and applies a style and a color to it. Most types only support the "skin" element and no special styles. For "man" and "woman", special elements and styles are supported:

man styles
woman styles
long, short, friar, wild
long, short, medium, pigtails
long, short, bushy

For each element, you can specify a style, texture, color, specular color, and shininess:
visuals hair long,#ff1111,#ffffff,0.5 beard short,#ff1111,#ffffff,0.5 skin myskin.png,#aa1111,#ffffff,0.5

All parts are optional.

Colors are web-style hex colors. Google "color picker".

The texture is mapped differently to each model, so you'll need to experiment, or ask for a template. The humanoid one is in Waz Examples. Alpha in the texture indicates mixing in the Color.

Note that for many creatures the color will be mixed with the textures of the creature and so may look completely terrible.

If you add the "debug" property (no value, just add it indented the same as name), you will get a little extra information, but also all textures will be output to your mod's directory. These are half-scale reduction from the built-in textures, but any scale textures can be used (though more than 512x512 is probably excessive).

Be sure to test your new class thoroughly before publishing it. Your in-development classes appear on pages just like the standard 16 character classes.

If your class does not appear, you have almost certainly made an error in the text file. You can see some verbose logging output in the WazHack_Data/output_log.txt file located where the WazHack executable is found on your system (use Steam's "browse local files" under Properties to find this).
Publishing your Mod
Steam Workshop

To publish your mod on the Steam Workshop, run WazHack, select the "Mods" option, and click the "Upload to Workshop" button that appears. You can make further changes and Update from here too, but beware of making major changes as players who are playing as your class wouldn't like to have their set of available Talents suddenly change mid-game!

When players play as a class from a mod, the savegame references the mod ID on Steam (which doesn't change) and the filename (minus the ".txt") of the class, so you should especially avoid changing these needlessly.

Note that if this is the first time you have published content, you may need to read and agree to Steam's Workshop Legal Agreement before your content will be visible to others.

Publish on mod.io

Mods published on mod.io are available to both Steam and mobile players.

To publish your mod on mod.io, pack the files in a ZIP file and submit it at https://wazhack.mod.io/ (login then press the "+" button). You can reuse your mod's preview image and description.

< >
Kodaxmax May 19 @ 5:56pm 
@AbsolutelyNaught Can you copy paste it to pastebin so we can see it? or add it to steam media.

You could also ask and paste it to the wazhack discord here: https://discord.gg/PxsCw7Yv
AbsolutelyNaught May 19 @ 1:01pm 
Hello, i'm encountering some difficulties making a mod for personal use. The mod is recognized in the mod menu in-game, but it outputs the error message "invalid metadata". I figured this meant there was something wrong with my metadata .txt file, but after thorough inspection there doesn't appear to be anything wrong. A total of 4 lines, with a single space at the front of lines 2 through 4. Does anybody have any ideas what might be causing the issue?
Kodaxmax Apr 22 @ 5:11am 
Waz  [author] Apr 13 @ 9:36pm 
Guide is updated for 1.4. The new game version also gives better error messages in the mod list.
Kodaxmax Oct 5, 2021 @ 8:44pm 
Can we have an updated guide for 1.4 please? creating and loading characters made with this method leads to the character selection UI not loading, even on mods that worked in 1.3
phoenixreigns10 Aug 22, 2019 @ 11:52pm 
Where is the Mods option? I can't seem to find it.
ohshadow May 11, 2019 @ 8:29am 
How do i install the modding branch xd

infinitetech May 8, 2019 @ 1:13pm 
you should try that just incase it works, i somewhat doubt that is the case however. make sure all other mods are off during testing of course.
Gunner Black May 6, 2019 @ 2:58pm 
Yeah, I dont know what I did wrong but it has to be filepath. Dropping thr text into someone elses mod works. Perhaps i should ignore the filepath and use that location under workshop\content?
Dadvarius (Chad/Chadself) May 6, 2019 @ 1:57pm 
Is your file properly indented?

For example, everything under WazHackModClass must be indented by one space. Everything in the inventory must be indented by another.