Beginner Guide to make an UI modification

[[ShAn]Montis]

01. Table of Contents
____01. Table of Contents (duh!)
____02. Introduction
____03. Preparations
____04. Modding the game
____05. Coding
____06. Creating a .s2z file
____07. Creating a .honmod file
____08. Wrapping it up
____09. Potential webspace
____10. Resources and useful links
____11. Programs used


02. Introduction
THIS GUIDE IS OUTDATED* AS IT WAS WRITTEN BASED ON FRONTEND 1.0, I WILL UPDATE IT WHEN I HAVE TIME AND I'M IN THE MOOD.

*outdated = the techniques are still valid but it wouldn't work if you followed my instructions because the altered part of the interface has been moved and rewritten

In this guide I will show you modding beginners how to mod the UI based on my Blacksmith Random Button mod. If you have any comments or suggestions about this guide, feel free to post in this thread, or look me up in IRC irc.s2games.com, channel #honlabs. If I'm not there, you'll find plenty of other helpful souls there.


03. Preparations
First of all, think of what you want to do.
In this case: alter the random button so the sound is not that strange clonk noise but a line from Blacksmith (Let's roll the dice!).
So you need the sound file or at least know where it is.
To do this, you can either search (kind of) blindly by clicking through all the resource files or you can search with system by checking the respective interface file and search for the text which resembles the stuff you are looking for. Searching with system usually takes longer, as the files are rather well organized, and as soon as you have some basic understanding where everything is, you can find stuff quite fast when searching "blindly".

So I went into the resources0.s2z by opening it with Winrar, found the sounds for blacksmith in heroes/dwarf_magi/sounds and extracted them to my desktop to listen, which would fit.
Writing it down on a sheet of paper (yes, I still use that stuff!):

ill_advised   Seem's like a gamble to me
move_2        Will leave it to chance
move_4        Let's roll the dice
taunt_prior   Feelin' lucky, aye

Now we have a choice of four sounds which we can build in.

Next Step: find the interface file(s) which you need to alter.
Those are in resources0.s2z as well, in the ui folder. There are a lot of different of package files which are name pretty self explanatory.
Everything with cc_ is for the community and clan panel.
Everything with game_ is for the pre- and in-game interface
Everything with main_ is for the mainmenu and the lobby where you can find games and stuff like that
ui_items are templates for pretty much every small item like a checkbox, slider, dropdownmenu etc but that's not relevant for this mod.

Now, the file we need is game_hero_select.interface. Extract it to your game/ui/ folder. The ui/ folder shouldn't exist so you have to create it, except if you already created that before and tried to mod something already.

Next, disable all your current mods by renaming the resources999.s2z into resources999.#s2z or moving it into a disabled mods directory, so you can restore it later more quickly (shame on you, if you don't use the HoN Modman!). This is done so you can be sure your HoN is clean and if you have a bug it's definately from the stuff you coded (or HoN itself) and not from another mod interfering.
Then launch HoN and start a practice game.

It helps if you actually go ingame, open the test panel, disable creep spawns (so no annoying "one of your towers is under attack" sounds play) and then remove the hero - now you have unlimited time to mod away and will be staying in the hero selection screen until you do something different.
Last thing for prepping is opening up the console (CTRL+F8) and typing

set host_dynamicresreload 1

That will spare you some time of opening the console everytime you make a change and typing

reloadinterface game_hero_select

[[ShAn]Montis]

04. Modding the game
As we now have made all preparations for our modding pleasure, we can now go into the code.
Open the file game/ui/game_hero_select.interface with your preferred text editor (I recommend Notepad++, see resources) and search for random.
The first thing you find should be:

    <!-- Random button -->

Everything between <!-- and --> is considered a comment which is ignored by the game and therefore only there to organize the code and for people to find stuff quicker. See also AsiaPingPongs Beginner Guide to Styling Syntax
Anyway, the only interesting thing here for us is the onclick event of the button. If we were lazy, we could just edit the line

onclick="PlaySound('/shared/sounds/ui/hero_select/button_random.wav'); ... "

into

onclick="PlaySound('/heroes/dwarf_magi/sounds/voice/move_4.wav'); ... "

and that would be it (don't do that yet). But luckily we aren't lazy and also want to make a .honmod file and a more complex button which tells the world that we randomed on purpose and have this cool mod.

Note that the path to the file is the exact one where we found the file in the resource0.s2z. Another important thing to note is the file extension, which isn't ogg like we found it in the resource0 file but wav. When dealing with textures this is similar: we find dds files and in the UI you write tga.

Why is this?
ogg-files are compressed files and dds files have multiple layers for the level of details settings, of which only one is needed. So when HoN loads, it puts the decompressed and proper level of detail data in the memory for faster access.

So, instead of making the aforementioned change, we copy everything between and including

    <template name="random_button">

and the next

    </template>

and put it in a new textfile which we name blacksmithbutton.package. You can save this file in the same directory as the game_hero_select.interface for convenience or put it into a subfolder for better organization if you have multiple mods and/or interface files to edit. We'll leave it in the UI folder for the moment.
Now the package file isn't complete. We need to put

<?xml version="1.0" encoding="UTF-8"?>
<package>

at the start of the file before the copied code and

</package>

at the end of the file, after the copied code.
Now we can mod all we want without altering or even destroying the actual interface file. The problem is: the files are not connected.
To do this, go back to the game_hero_select.interface and put this line:

    <include file="/ui/blacksmithbutton.package" />

right at the start of the file after <!-- Packages -->, line 4. If you hit save now, did everything as I told you and have HoN running in the background you should hear the "choose wisely" sound again - that means the interface you just altered got reloaded. Actually this happens everytime you alter something in the blacksmithbutton.package as well.
Speaking of which: switch back to that file, everything we do will now be in there - you can close game_hero_select.interface for good.

[[ShAn]Montis]

05. Coding
First thing, make the change I mentioned earlier so when you leftclick the randombutton, you hear the "Let's roll the dice" sound.
Save the file choose wisely and switch to the game. Click the random button and see if it works. If it doesn't, you screwed something up: go straight to prison and don't collect 400 bucks.

Second we want to also have a rightclick action. To make it more complex, it should randomly choose between the four found blacksmith lines, output them in allchat in red(!) and also play the sound for you.
So, remove your hero again and switch out to the text editor.
After the onclick="..." line, add a new line

onrightclick="AllChat('I just randomed');"

save, and switch to the game to test it. Rightclick the button and look at the chat. Working? Great. (God, I'm awesome, aren't I?)

Now, as I don't know of function to generate a number between 1 and 4 (or 0 and 3, whatever), we have to write our own random number generator (hasn't got to be THAT random, just random enough). I searched for a cvar which changes often. Go in game, to console (CTRL+F8) and type cvarlist. OMG WTF is this? Okay we'll cut the searching part and got straight to the cvar _cl_ms. This one records how long your HoN Client has been running in milliseconds, so it basically changes every thousandth of a second. Random enough for our purposes. All we have to do is divide it by four and get the remainder for a random number between 0 and 3.
The function for this would be

_cl_ms%4

The per cent character is the "divide by and get remainder" and the 4 is, well... the number with which we divide by.
Now we have our random number, unfortunately it is a floating point number, where we'd rather have an integer for comparison purposes. Floor function to the rescue:

Floor(_cl_ms%4)

This gives us exactly what we need.

Now for the conditions:

If(_condition_, _action if condition is true_, _action if condition is false_)

_condition_ is only allowed to have a state of either true or false, else it won't work. Our condition in this case would be:

Floor(_cl_ms%4) == 0

This would be true in (about) 1/4th of the cases we press the button. So we have to adress every possibility and put up 4 Ifs. Remove the previous onrightclick="AllChat('I just randomed');" and replace it with the following:

onrightclick="If(Floor(_cl_ms%4) == 0, AllChat('random 0'));
If(Floor(_cl_ms%4) == 1, AllChat('random 1'));
If(Floor(_cl_ms%4) == 2, AllChat('random 2'));
If(Floor(_cl_ms%4) == 3, AllChat('random 3'));"

Save and test. Have in mind that the chat has a spamprotection so it probably will stop to print out your numbers after 3 or 4 clicks in which case you have to wait.

Now we can implement the different sounds - the problem we have here is that theoretically, only one action is allowed for one condition, but luckily, S2 thought of that and instead of making a huge chain of Ifs we can just use Split().
That works like that:

If(_condition,
Split(_action 1 if condition true_, _action2 if condition true_, _action# if condition true_));

Note that you can split into as many actions as you like. Also note that you don't actually need a "action if condition is false" part, but the syntax requires that you drop the comma too if that's the case.

So our code would be like that

If(Floor(_cl_ms%4) == 0,
    Split(AllChat('^rLet\'s roll the dice!'), PlaySound('/heroes/dwarf_magi/sounds/voice/move_4.wav')));

Notice the \ before the ' on Let's roll the dice? That's to mark the next character as part of the string and not part of the code. If you wouldn't use that, it wouldn't work (yes, I tested that). The ^r colors the text red, but I bet you know about that already.

Adding the other 3 possible conditions the same way:

onrightclick="If((Floor(_cl_ms%4) == 0),
    Split(AllChat('^rLet\'s roll the dice!'), PlaySound('/heroes/dwarf_magi/sounds/voice/move_4.wav')));
    If((Floor(_cl_ms%4) == 1),
        Split(AllChat('^rWill leave it to chance!'), PlaySound('/heroes/dwarf_magi/sounds/voice/move_2.wav')));
    If((Floor(_cl_ms%4) == 2),
        Split(AllChat('^rFeelin\' lucky, aye!'), PlaySound('/heroes/dwarf_magi/sounds/voice/taunt_prior.wav')));
    If((Floor(_cl_ms%4) == 3),
        Split(AllChat('^rSeem\'s like a gamble to me!'), PlaySound('/heroes/dwarf_magi/sounds/voice/ill_advised.wav')));"

Save and test. Okay, sound plays, text displays, but I didn't actually random a hero, did I?

Check the onclick= action and look what the command is there. Looks like RandomHero(); is the deal. Also there's another command for removing the tooltip after clicking, so we will follow S2's lead on that.

onrightclick="If((Floor(_cl_ms%4) == 0),
    Split(AllChat('^rLet\'s roll the dice!'), PlaySound('/heroes/dwarf_magi/sounds/voice/move_4.wav')));
    If((Floor(_cl_ms%4) == 1),
        Split(AllChat('^rWill leave it to chance!'), PlaySound('/heroes/dwarf_magi/sounds/voice/move_2.wav')));
    If((Floor(_cl_ms%4) == 2),
        Split(AllChat('^rFeelin\' lucky, aye!'), PlaySound('/heroes/dwarf_magi/sounds/voice/taunt_prior.wav')));
    If((Floor(_cl_ms%4) == 3),
        Split(AllChat('^rSeem\'s like a gamble to me!'), PlaySound('/heroes/dwarf_magi/sounds/voice/ill_advised.wav')));
    RandomHero(); Trigger('HeroSelectTip', false, '', '');"

Save and test.
Congratulations, you finished your first mod!
Or did you? Damn, you somehow have to get this into a .honmod file! More about that in the next post.

[[ShAn]Montis]

Okay, now we want to share our hard work with others on the forum. Thus, we need some form of webspace. See section Potential webspace for that.
First, we'll do the simple thing and create a .s2z file for our potential admirers.


06. Creating a .s2z file
With Winrar and it's context menu addition it's as simple as going into the game/ folder, rightclicking the ui/ folder we created, add it to an archieve (zip, not rar!) and rename that zip file we just created to resource###.s2z (the ### are to be replaced with 3 digit number like 998, request an official number here).
Upload this, done.

Now for the more complicated part of turning this into a .honmod file for use with the HoN Modman.


07. Creating a .honmod file
Essentially we need 3 things for creating a .honmod.
1. everything we did so far
2. a mod.xml
3. a icon.png

as we have 1. already, I'm going straight to 2.
The easiest thing to do (what probably almost every first-time-modder including myself did) is to take a completed mod, extract the mod.xml and alter it to your needs.
We're going to start from scratch here so you'll learn what everything does.
Looking into the thread of the HoN ModMan, we can see the basic buildup.
Create an empty textfile in the game/ folder and name it mod.xml.
Now, put this inside:

<?xml version="1.0" encoding="UTF-8"?>
<modification
    application="Heroes of Newerth"
    appversion="-0.2.*"
    mmversion="1.2"
    name="Blacksmith Random Button"
    version="1.0"
    description="Want to random? That's good because it's me, Blacksmith!"
    author="ModdingBeginner94"
    weblink="http://#"
>
 
</modification>

Of course substituting the author with your name. The name="..." and the description="..." are shown in the mod manager later and should resemble a (short) name for your mod and a description which the user can read (they probably know, what they've downloaded so you can keep it relatively simple there).

Now, as the ModMan extracts the files from resources0.s2z and edits them only to put them into resources999.s2z, we need to tell him, what we want to be edited and how.
So, in between the <modification>-Tags, we put

<editfile name="/ui/game_hero_select.interface">
    <find><![CDATA[<!-- Packages -->]]></find>
        <insert position="after"><![CDATA[
    <include file="/ui/blacksmithbutton.package" />]]></insert>
    </editfile>

What the modman does with this: <editfile> makes him open the ui/game_hero_select.interface file. After that, he searches (<find>s) the string <!-- Packages -->.

Sidenote:
The <![CDATA[...]]> is required so you don't have to mark every single syntax element to not actually work as a syntax element in the mod.xml but as a string to be put into the interface file.

After finding the text we searched for it will insert the text we need

<include file="/ui/blacksmithbutton.package" />

Looks familiar? That's the line which we added to the game_hero_select.interface! So, the ModMan now actually does the same thing we manually did before. Cool, huh?

Now we just need one more thing: putting our external file blacksmithbutton.package into the later created resources999.s2z.
It's as simple as that:

<copyfile name="/ui/blacksmithbutton.package" />

For organisation's sake we will but that line above the <editfile>-tags, so everyone who opens our mod.xml sees quickly which additional files we use.

Your mod.xml should now look like this:

<?xml version="1.0" encoding="UTF-8"?>
<modification
    application="Heroes of Newerth"
    appversion="-0.2.*"
    mmversion="1.2"
    name="Blacksmith Random Button"
    version="1.0"
    description="Want to random? That's good because it's me, Blacksmith!"
    author="ModdingBeginner94"
    weblink="http://#"
>
<copyfile name="/ui/blacksmithbutton.package" />
<editfile name="/ui/game_hero_select.interface">
    <find><![CDATA[<!-- Packages -->]]></find>
    <insert position="after"><![CDATA[
    <include file="/ui/blacksmithbutton.package" />]]></insert>
</editfile>
</modification>

Save.

Now to part 3.
Make an 48x48 pixel image with your favorite graphics program and save it as icon.png in your game/ directory. I won't give you any advice on this here, you should research or know about that yourself.

If you created the resources###.s2z before, you can make a copy of that now. If not, just zip (again: zip, not rar!) the game/ui/ folder so the zip file contains the ui/ folder and all files and subfolders in it. Open this zip-file or the copied resources file and put the mod.xml and the icon.png in the root directory of the zip. Go into the ui/ folder inside the zip file and delete the file game_hero_select.package, as that will be created by the ModMan later through the mod.xml anyway. Now close the file, rename it to mynewcoolmod.honmod, copy it to your mods directory and try it out with the ModMan. Remember to close your HoN first before applying mods, and also rename or move (or even delete if you're over confident) your ui/ folder, so it doesn't interfere with your resource files.
If you did everything as I said, it should work now!


08. Wrapping it up
The final step is cleaning up: move all created files except the .honmod file (which should already be in your mods/ folder) into another directory so it won't clutter your game/ folder and/or interfere with your installed mods or your future modding trips. Done.

Okay I lied. The final step is: make a thread in the forum, copy the thread URL into weblink="http://#" of the mod.xml, upload your s2z and honmod files, put those in the thread you created, request a mod number for your mod and get worshipped for your modding prowess.

You also can thank Ignorance for making me write this guide. Well, of course you can also thank me and support my suggestions in my signature and download and use all the amazing and extremely essential *cough* mods I made.
On a final note I would like to thank my good friend GMJ for helping me with the random number generator even though he had no clue of HoN modding.


09. Potential webspace
- mediafire.com
- dropbox.com (also has other cool features that come in handy when working with multiple computers)
- atspace.com


10. Resources and useful links
- HoN Wiki XAML reference
- Thread: The Master Repository - Request Mod Numbers Here
- Thread: HoN Modification Manager
- Thread: Beginner Guide to Styling Syntax
- Thread: How To Make Your HonMod's Auto-Updateable
- Thread: Advanced Console Use


11. Programs used
- Notepad++ for the coding
- Photoshop for the mod icon
- Winamp for listening to the soundfiles
- Winrar for the zipping

- and of course: the HoN Modification Manager by Notausgang

[MaxGhost]

Another combination of programs (what I use):
- Photoshop
- Notepad++
- VLC Media Player
- 7zip

[[ShAn]Montis]

The problem with VLC which I had was that it cuts off the first half second or so of sound files I played, so I switched to Winamp which worked fine. :-)

[[LC]Barter]

Photoshop for the mod icon

Paint.net or GIMP are great also and free :P

[MaxGhost]

The problem with VLC which I had was that it cuts off the first half second or so of sound files I played, so I switched to Winamp which worked fine. :-)

I use audacity if I really need to get closer.

[[ShAn]Montis]

yay, done!

upcoming: Beginners Guide to Templates and Packages

[Cbrad24]

Seems like I've started a trend with the contents.
Nice guide, Be sure to reference to this.

[MaxGhost]

Seems like I've started a trend with the contents.
Nice guide, Be sure to reference to this.

Nah you didn't start any trend. You missed the start of the trend actually... Ignorance wrote a few guides, and after that, we had enough guides to make this resources forum.

[[ShAn]Montis]

Paint.net or GIMP are great also and free :P

well, of course but as I work with Photoshop on a regular basis, I just use it for most stuff I do graphically anyway, so why learn a new program? :P

[Cbrad24]

Btw u should link to my guide next to atspace. Really wana see more mods auto updating

[[IUN]unbreakabler]

onrightclick="If(Floor(_cl_ms%4) == 0, AllChat('random 0'));
If(Floor(_cl_ms%4) == 1, AllChat('random 1'));
If(Floor(_cl_ms%4) == 2, AllChat('random 2'));
If(Floor(_cl_ms%4) == 3, AllChat('random 3'));"

ALRIGHT I THINK I FIGURED IT OUT.

You are missing a bracket level on each If statement.

You should probably mention to remove or just completely remove this line from your tutorial. For me it did nothing but confuse the **** out of me trying to get that to work at the same time as the onrightclick with If statements.

onrightclick="AllChat('I just randomed');"

I am also just going to assume that you can only have one "event" or w/e its called for 'onrightclick' and that having two or more lines of code both using 'onrightclick' simply doesn't work.

[[ShAn]Montis]

onrightclick="If(Floor(_cl_ms%4) == 0, AllChat('random 0'));
If(Floor(_cl_ms%4) == 1, AllChat('random 1'));
If(Floor(_cl_ms%4) == 2, AllChat('random 2'));
If(Floor(_cl_ms%4) == 3, AllChat('random 3'));"

ALRIGHT I THINK I FIGURED IT OUT.

You are missing a bracket level on each If statement.

whoops! my bad

onrightclick="AllChat('I just randomed');"

I am also just going to assume that you can only have one "event" or w/e its called for 'onrightclick' and that having two or more lines of code both using 'onrightclick' simply doesn't work.

no, you can have multiple actions on one event (onrightclick). you just need all of them inside parantheses and separated by semicolons.
like:

onevent="Action1; Action2;"

this also goes for If-"actions".

I included the one line you mentioned just because you have to check what you're doing and check if you're doing it at the right place before going into details. I added a line to mention that you should replace it.

[[RdB]Avoidant]

Hello...

I'm a programmer, but I'm used to work on C, Java and alikes. I'm trying to do my first mod, but I'm having some difficulties to get the idea.

First, I can't find much documentation, API of the commands, etc... Just the stuff on honwiki.

I tried doing a simple thing that would say stuff, OrderHold and say stuff again...

I tried:
onevent="Split(AllChat('stuff1'),OrderHold,AllChat ('stuff2'));"
onevent="AllChat('stuff1'),OrderHold,AllChat('stuf f2')"
onevent="AllChat('stuff1');OrderHold;AllChat('stuf f2');"

None of those seems to have the pretended effect, as I'm getting the "stuff1" on the chat, but neither the hero stays on Hold, nor "stuff2" appears in the chat.

1- Could you please help me on this simple task? How can I execute more than one action?
2- is there is any other documentations besides honwiki?


Thanks in advance.


Disclaimer: English is not my native language, so I'm sorry if any thing is badly written.

[MaxGhost]

OrderHold(); is the correct syntax. The () is mandatory for it to work.

You'll want to do onevent="AllChat('stuff1'); OrderHold(); AllChat('stuff2');"

[[sSi]Ignorance]

Action('OrderHold') works. Not sure why OrderHold doesn't.
Edit: I'm talking about doing this through UI calls. OrderHold(); should work in the actual UI. If you want to do it through the console, the best way is 'Action OrderHold'.

[MaxGhost]

Action('OrderHold') works. Not sure why OrderHold doesn't.

Like I said, because parentheses are mandatory.

[[RdB]Avoidant]

It isn't working :|

I tried just this:
onevent="AllChat('stuff0');AllChat('stuff1');"

And all I see is 'stuff0'...

Probably I'm doing something wrong, but I can't figure it out...

Is there any other documentation, or honwiki is all I have?

thx.