Welcome to the often frustrating but occasionally satisfying world of video game modding! I'm sure you have fantastical ideas for adding hover-trains and giga-drills and mutant mecha-sharks to this game, but slow your roll, relic hunter! Currently we can only create custom guns for the game, this means we can:

•Create a gun sprite for use in the game.
•Modify some of the gun's properties.

From what we've learned on the official RHZ Discord[discordapp.com], we can expect to be able to mod Projectiles and Characters next!

This is the official modding tutorial video, made by Mark Venturelli, one of the game developers:


It does a great job of explaining all the steps for getting a custom gun into the game. However, there are discrepancies between what the video shows and the actual file names you'll deal with, which can frustrate you with uploading errors. There are also issues with some of the gun properties we can edit, which I'll point out further below.

I recommend you watch the video first, then check this Guide if you need clarification on something.

Here's what you need to start modding:
A text editor (Notepad++)
An image editor (I used Hexels 3 and Photoshop)
Relic Hunters Zero
SteamCMD
Example Mod

You can find links to download those things on the video page.

If you have any information modders should know, please post it and I'll get it added to the guide.

From what I can tell, the game's guns are made at [2x] scale, but give the illusion of being [1x] scale. This means that what looks like 1 pixel in the game is actually 4 pixels in a 2x2 square.



To keep things simple and match the game's blocky art style, draw your gun sprite at [1x] scale, then simply increase the size by 200% to get [2x] scale. Use the [2x] scale sprite to create the spritesheet.

If you want to to draw your gun at actual size (so you don't have to resize) use this Jimmy sprite as a guide.


https://raw.githubusercontent.com/mventurelli/relichunterszero/master/RelicHuntersZero.gmx/sprites/images/spr_jimmy_idle_0.png

In the video, Marc shows us how he makes a spritesheet in Photoshop, but you'll probably develop your own workflow and go faster with shortcuts.

The following is an example of how I made this Keytar. The process is generally the same for all weapons.




By looking at the game and estimating, Raff's original Keytar is about 25 pixels long, so I used that as a rough guide for how big this one has to be. I also copied the white keys to give it uniformity with the original.

As you can see, my new gun has an interesting shape but it kinda looks like butt lol.




The exact numbers don't matter, just crop it enough that there's room for the 2px white outline that's coming up.

Since you have more pixels to work with at [2x] scale, it's possible to refine the design of your gun. Try not to over-detail it though, so it will look okay in the game.

Here I heavily twerked the [2x] sprite into a prettier shape. I only used 2 purples and 2 yellows, it's enough to give those parts a little depth.

Once you're happy with how the gun looks you can make the spritesheet.


Should look like this, all on one layer:




You should end up with spaces on the sides, like this:




They should neatly snap into place if you have that feature enabled. Should look like this now:




Use the Wand Tool to select only the solid color. Then, simply use the your keyboard shortcuts to Cut and Paste it, that should make it its own layer.



You should now have a Gun layer and a Solid Color layer. Now select the Gun layer and make sure it's above the Solid Color layer.




This sprite shows up when you stand near the gun in game.

Make your Pencil Tool 2px big to make the job easier.

Holding Shift and Clicking with the Pencil will instantly draw a straight line from the last place you clicked to where your cursor is now.




This sprite shows up in the ammo area on the HUD. In-game it automatically gets tinted with the color of the ammo type the gun uses.

Use whatever method you want to make it white. Lasso, paintbucket, lightness, psychic powers, etc.


We don't need that layer anymore. After all that you should end up with the guns and a transparent background:



Now save the image as a PNG called "spritesheet".

That's it, now you're ready to mess with the Config file.

Many of the properties in the Config file are self-explanatory, but some of them are vague and hard to guess what value (number) you should use. Also, some of them aren't working properly, or don't work like you'd expect.

Refer to the "configGunExample" file you downloaded to see what values can be used for these, the video also has useful tips. And feel free to ask people in the Workshop what numbers they used for their guns, I found the best way to guess what number you need is to study many different guns.

• type
  This is the type of item you're making. Currently we can only use "gun" here, but more types of items will be available to mod in future updates.
  
  
• name
  The name of your item. It always shows up in uppercase letters in the game.
  
  
• weapon_class
  For guns, this is what kind of gun it is. Although this doesn't have a direct effect on what your gun does, some Characters perform better or worse with certain kinds of guns.
  
  
• sound
  The sound heard when the gun fires.
  
  
• projectile
  This determines what kind of projectile the gun will fire, as well as what it will look like. Each projectile has different abilities (see the Projectile Types section in this guide).
  
  Setting this to "default" will fire a normal projectile, the color and shape will vary depending on the "ammo_type".
  
  
• projectile_damage
  How much damage each projectile deals.
  
  
• projectile_range
  How far a projectile will go before disappearing (or detonating, in the case of Flak and Blast projectiles).
  
  
• projectile_piercing
  How many enemies a projectile will pass through before hitting. All enemies the projectile passes through take the projectile's damage.
  
  For normal projectiles, set this to "0" so the projectile hits the first enemy it touches.
  
  
• projectile_recoil
  This value changes how far a gun will visibly jolt back in the player's hands when fired. Setting this to "0" means the gun won't jolt back at all when fired.
  
  
• projectile_power
  How far a projectile will push away an enemy when it hits them (also known as "knockback").
  
  If you're using a rapid-fire weapon, consider using something really low (like "0.3") so you don't accidentally send enemies flying all over the place.
  
  When using a shotgun-like weapon or a gun with burst fire, which fire many projectiles at once with one pull of the trigger, each projectile will affect the enemy with its own knockback power. This means if each pull of the trigger fires 5 projectiles, and the gun's "projectile_power" is 4, an enemy hit with all 5 projectiles will suffer 20 knockback (5 projectiles at 4 power each).
  
  
• projectile_speed
  How fast the gun's projectiles will travel.
  
  If you make a cool projectile, consider setting this to something like "20" to "30" so we get a chance to actually see it!
  
  
• projectile_speed_decay
  This is a modifier that allows us to add acceleration or deceleration to a projectile. Using a positive number will cause the projectile to slowdown over time. Using a negative number will cause the projectile to speed up over time.
  
  
• projectile_bounce
  Determines if the gun's projectiles will bounce off enemies after hitting/damaging them.
  
  
• projectile_bouce_max
  How many times the gun's projectiles will bounce.
  
  If "projectile_bounce" is set to "0", then this number does nothing.
  
  
• drop_casing
  Determines if the gun will visibly eject bullet casings when fired.
  
  
• goes_through_walls
  Determines if the gun's projectiles will go through environmental objects. Setting this to "1" allows the gun's projectiles to pass through things like Boxes and Kami Cages without affecting them. However, they will still be stopped by the rocky walls used as a level's border.
  
  The Keytar's musical projectiles ("sonicBoom") will go through anything, even the rocky walls, no matter what you set this to.
  
  
• accuracy
  How accurate the gun is. Watch the video because Marc explains this well. A value of "1" gives the gun almost pin-point accuracy, a value of "25" will cause projectiles to exit the gun at a random angle within a 25-degree cone.
  
  
• accuracy_aiming
  Similar to above, this determines the accuracy only while holding the Aim Button.
  
  
• ammo
  Think of this as the gun's magazine. This is how many projectiles a gun can fire before needing to reload.
  
  
• ammo_type
  The type of ammo a gun uses (light, medium, or heavy). This also determines what color the blank white gun on your spritesheet will be.
  
  
• ammo_cost
  This determines the size of the gun's ammo pool, and how much ammo you get from Ammo Boxes. Increasing the number will decrease the ammo pool and how much ammo you get from Ammo Boxes, using a smaller number will increase this.
  
  If you're making a gun that deals low damage at a fast rate, like a flamethrower or beam weapon, it may be a good idea to use something low, like "0.4", so you don't run out of ammo too quickly.
  
  
• reload_time
  How long it takes the gun to reload, in seconds.
  
  
• fire_automatic
  Determines if the gun is automatic ("1") or semi-auto ("0"). Automatic means the gun will fire continuously as long as you hold the trigger. Semi-Auto will only fire once per pull of the trigger.
  
  
• fire_amount
  How many projectiles are fired simultaneously per pull of the trigger. Even though increasing this number makes the gun fire more projectiles at once, it has no effect on "ammo" or "ammo cost". In other words, it doesn't make the gun consume more ammo.
  
  
• fire_rate
  How fast the gun can fire, in terms of seconds. Increasing this value slows the fire rate, decreasing it increases the fire rate.
  
  As an example, let's use the value of "2":
  
  •If the gun is automatic, holding the trigger will fire a bullet once every 2 seconds.
  •If the gun is semi-auto, the gun can only be fired once every 2 seconds.
  
  A "fire_rate" of "0.1" is really fast, and "1.0" feels a little slow. I suggest starting at around "0.5" and tweaking it as necessary.
  
  
• fire_rate_decay
  Similar to "projectile_speed_decay", this is a modifier that allows us to increase or decrease a gun's fire rate over time while firing.
  
  This seems to be affected by "fire_amount" (in addition to "fire_burst"). For example, if "fire_amount" is 3 (fires 3 projectiles simultaneously), the gun's fire rate will increase/decrease 3 times faster while firing.
  
  
• fire_rate_decay_recovery
  How quickly the fire rate goes back to normal after you stop firing. (Honestly, I can't tell if this is working properly.)
  
  If you set this to a negative number, the fire rate will increase/decrease forever and never go back to normal until you restart the game.
  
  If "fire_rate_decay" is "0", this does nothing.
  
  
• fire_rate_decay_min
  After some testing, this seems to let us set a limit to how much a gun's fire rate can be affected by "fire_rate_decay".
  
  
• fire_burst
  If you want the gun to fire a burst of projectiles (sequentially, not simultaneously) every time you pull the trigger, set this value to how many projectiles it should fire. For a normal, non-burst fire gun, set this to "1".
  
  
• fire_burst_rate
  This only affects the fire rate of the projectiles fired by "fire_burst".
  
  If "fire_burst" is "1", this does nothing.

• crosshair_recoil
  How much the square crosshairs (square-hairs?) grow with each shot. Increasing this value doesn't affect the gun's innate accuracy, but having huge crosshairs will obviously make it harder to aim. The enlarged crosshairs will shrink back to normal over time, but keep in mind the enlargement will persist even if you switch guns.
  
  If you're making a rapid-fire gun, consider setting this to a low number so the crosshairs don't fill the screen!
  
  
• shake_amount
  How much the screen shakes when the gun is fired.
  
  
• beam_thickness
  How thick the gun's beam is, in pixels. If the gun isn't a Beam weapon, this does nothing.
  
  
• beam_color_(r,g,b)
  The color of the gun's beam. Simply enter the RGB numbers into the appropriate spots. If the gun isn't a Beam weapon, this does nothing.
  
  
• price
  How much the gun costs at the Shop in Endless Mode.
  
  
• tier
  How rare the gun is. This affects how often it appears in Endless Mode (I think).
  
  Tier 1 is Common
  Tier 2 is Uncommon
  Tier 3 is Rare (Relic Gun)

Official Projectiles
These are all the projectiles found in the base game. These determine what your modded gun's bullets will look like. Some of them are simply a cosmetic change, but some have unique innate properties.

• default
  The most basic projectile. The color of this projectile is determined by the gun's "ammo_type". (Green, red, blue)
  
  
• blast
  Causes a small explosion where it lands, damaging nearby enemies for [4x] the projectile's damage. (I think it's [4x], needs more tesitng)
  
  
• beam
  A laser beam is fired, dealing continuous damage while held on an enemy. Functionally, you can think of it as a rapidfire gun with super fast projectile speed, but you can of course modify those properties.
  
  
• kamiRocket
  
  
• flame
  This is the Flamethrower's signature projectile. It resembles a little fireball. The projectile will start small and grow bigger as it reaches the end of its range. It will also glow if it lingers long enough. (To see the glow effect, you may need to use "projectile_speed_decay" to make the projectile slow down drastically after firing.)
  
  There's a little "poof" effect when this projectile disappears, the color of that "poof" is determined by "ammo_type".
  
  This projectile does NOT deal damage over time (like a "burn effect"), it just looks like fire.
  
  To get the "cloud of fire" effect when firing, try a low "projectile_speed" and a high value for "accuracy" so the projectiles spread out a lot. Then use a fast "fire_rate" and low "fire_amount", or vice-versa for a different experience. Using "projectile_speed_decay" can also help.
  
  
• flak
  
  
• flakRelic
  
  
• plasma
  Resembles a ball of crackling blue plasma.
  
  
• rocket
  
  
• skull
  
  
• sonicBoom
  This is the Keytar's signature projectile. It resembles a big white music note.
  
  Aside from looking cool, it will always go through objects and rocky walls regardless of what "goes_through_walls" is set to. However, "projectile_piercing" will still affect it.

Custom Projectiles
With permission, here I'll list custom projectiles made by modders to let everyone know how they work.

• Coming soon...

• joypad_rumble_factor
  How much the controller rumbles when the gun is fired.

After some quick exprimentation, setting this value to "10" gives a strong vibration, "14" is stronger, and "40" feels about the same as "14". I think the min/max values for this are something like "0 - 20". (Yes, the numbers in "configGunExample" are wrong.)

Another wrinkle, I discovered that different controllers vibrate at different strengths, even at the same values! I'm using an Official Wireless XB360 controller and a Wired GameStop XB360 controller. The Game Stop controller vibrates violently at "14", but the Wireless one is unimpressive.

I then tested both controllers with Borderlands: TPS and had mixed results. When using a shotgun, The Wireless one had really weak rumble compared to the Wired one. However, both controllers rumbled just as hard when using an SMG and a Rifle. I don't know what to make of this, please chime in with any insight.

I am now using XBox One Wired controllers made by Power A and the rumble is satisfying, like with the previous Game Stop controller. Maybe there's a rumble bug with Official XB360 controllers?

These properties are also found in the Config file. They deal specifically with the gun's physical position in the game.

• sprite_w
  Your spritesheet's width, in pixels.
  
  If you did everything correctly, your spritesheet's width should be a number that's a multiple of 3. Divide that number by 3 and use that result here.
  
  For example, if the spritesheet's width is 180 pixels, then use "60" here.
  
  
• sprite_h
  Your spritesheet's height, in pixels.
  
  No 5th dimensional calculus required, simply use whatever the height in pixels is.
  
  
• origin_x, origin_y
  These determine the position of the gun in the game in relation to the character. We'll only be making sure it looks good in the character's hands. Most likely the gun will be off-center when it shows up on a table, but don't sweat it.
  
  Adjusting Y shifts the sprite vertically, adjusting X shifts it horizontally.
  
  Increasing Y shifts the sprite up, decreasing Y shifts it down. Increasing X shifts the sprite left, decreasing X shifts the sprite right. (For you graph junkies out there, yes, X works backwards here.)
  
  In the video Marc shows a way to get these numbers, but it never worked for me. If it doesn't work for you either, try this way:
  
  If your spritesheet is about the same size as the one I made up there (198 x 28), go ahead and set both of these to "15" as a starting point. Upload the mod and see if the gun is in a good position. If it's not, estimate how many pixels you need to move it, adjust these X,Y values accordingly, and upload again. Keep doing this until you're satisfied with the position. For the Keytar in this guide, I ended up using (Y: "14") and (X: "25").

The video and the "readme" file included in the "Example Gun" download do a good job of explaining the process.

Your workflow for uploading a mod may go something like this:

• Open SteamCMD and log in by using this command:
  
  

  login name password

  
  
• When you get a confirmation message, type this command:
  
  

  workshop_build_item path_to_the_mod.vdf_file

  
  
• Press Enter on your keyboard and wait a few seconds while the program does its thing. If everything worked you'll get a "Success!" message.
  
  
• Exit Steam if you have it open, then open it again and log in through there as usual. Go to your Workshop items and check that your mod is working the way you want it to. Change its visibility to "Public" when you feel it's ready.

These are some quirks you should know about:

• You don't have to close SteamCMD after uploading a mod. This makes it possible to upload another mod (or update the same one) without having to retype everything. Just press Up or Down on the keyboard to cycle through commands you've used that session.
  
  
• After using SteamCMD to log in and upload a mod, you must restart Steam (and log in through it) to be able to subscribe/download/update/etc. Every time you upload or update mods you must restart Steam to receive the update.
  
  
• If you press Enter after typing a command and more than 10 seconds pass with nothing happening, SteamCMD most likely froze. Just close/reopen it and try again.

Any bugs or peculiarities I find will be listed here.

• Currently it's not possible to assign the Keytar or Flamethrower firing sound to a gun because the names are unknown.
  
  
• Even though you can assign the "sonicBoom" projectile to a gun, you have to assign a different "sound" to it because the name for its original sound is unknown. This may result in random sounds playing when the gun is fired. The Keytar sound and "sonicBoom" projectile may be tied together in a way that makes modding with them difficult.
  
  
• When using the "beam" projectile, setting "fire_amount" over "1" will fire extra beams as expected, but any beams after the first won't be visible.
  
  
• The Laser Sight that appears when aiming can be blocked by objects in the environment
  
  
• Currently the "flame" projectile will only be visible in the game if you use the modded gun with Punny. However, the "flame" reflection will still appear on polished floors (like on the spaceship) regardless of the character.
  
  
• Certain combinations of modded guns will cause one or both of them to act wonky. For example, equipping my "Twin Kohmak" guns with "Heirophant Green" will cause the flames on the TK to disappear until you restart the game.

Something I noticed from making a few mods and watching the live devstreams is that players appreciate knowing a little about a modded weapon, but also like discovering what it can do on the fly. This suggests that modders should try to give enough information about their modded gun to make players curious, but not drown them in stats.

For example, go ahead and let people know what ammo type it uses, or that you made a SMG so players can pick it for their next run with Red. If you really want to share stats, consider simply uploading a screenshot of the gun's stat page.

Give players a general idea of how you intended the gun to be used. While it can be fun to discover what a gun can do by using it, a player who loves shooting from across the screen probably won't be too thrilled to find that your pistol has super short range.

And while I don't think you need to write an essay linking your gun to the Rise and Fall of the Ducan Empire, it wouldn't kill you to add a little creative writing.