Modding WazHack

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:

%UserProfile%\AppData\LocalLow\Waz\WazHack\mods\

On MacOSX:

~/Library/Application Support/Waz/WazHack/mods

On Linux:

$XDG_CONFIG_HOME/unity3d/Waz/WazHack/mods

On Android:

Android/data/com.wazhack.WazHack/files/mods

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:

type	The name of the creature from which the new class derives. May also be "man" or "woman".
inventory	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.
sex	0=Neuter, 1=Male, 2=Female, 3=Either, 4=Plural
pet	creature name of pet (eg. cat)
petLevel	the experience level of the pet
talents	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.
belief	foodism, norse gods, atheism, inner power, or darkness
alignments	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)
skills	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.
stats	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).
visuals	a structured list of items, each items, each choosing styles and colors (see below)
scale	1 = normal scale for that creature, 0.5 = half-size, etc. Don't expect extremes to be playable.
speed	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:

Element	man styles	woman styles
hair	long, short, friar, wild	long, short, medium, pigtails
beard	long, short, bushy	(none)

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]

@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

[Aynot]

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]

<3

[Waz]

Guide is updated for 1.4. The new game version also gives better error messages in the mod list.

[Kodaxmax]

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]

Where is the Mods option? I can't seem to find it.

[ohshadow]

How do i install the modding branch xd

[infinitetech]

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]

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?

[Sawyer Blauers]

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.