Mod Options Framework (beta)

In development.

Mod Options FrameWork


Content:

• Introduction
• Download framework
• Download options
• Documentation
• HowTo add your options
• HoN Mod Manager (.honmod) template
• Options template
• Version history

Introduction.

This is a framework for modders that don't want to write their own options UI, or start from scratch.

It'll place a new tab called "Mods" in the game options.



Mod authors will then be able to easily write option UIs for their mods.


Back to top

Download Framework.

Everyone that want to use the features of the framework must download and install this mod.
If you're a mod author using the framework you have to get your users to download this for it to work.

Download: (.honmod) (.s2z) (Version history)

Warning IE has issues with the link. Use an alternative (better) browser. (Chrome) (Firefox)
Solution: Right-click -> Save As... and rename the extension from .xml to .honmod.

Back to top

Download Options.

Standalone:

• BardUI Options (v2) (Outdated, pending update)
  
• [URL="http://bit.ly/9zKYoO"]Buddy Follow Options[/URL] (Outdated)
  
• [URL="http://bit.ly/cgHCFo"][U]Channel Bar Options[/U][/URL][U][U][/U][/U] (Obsolete! Channel Bar has embedded options now) (Reference only)
  

Embedded: (Mods own options interface is removed if this framework is present)

• [URL="http://bit.ly/cTLkfk"]Buddy Follow v1.1[/URL] (v2) (Outdated)
  

Back to top

Documentation.

• All cvar attributes are automatically created and setsaved. So no need to create them first, the framework will take care of that.
• It's strongly recommended that cvartypes are kept to default types.
• When resetting cvars the default attribute is used, if not set the default default value will be used. (See specific element for default value)
• Underlined attributes are optional.
• All attributes are case-sensitive.
• Listed attribute values are the default value for the attribute.
• The ' or &#39 is not allowed. Not even in tooltip.

Create new instance. You need only one and it must be the first element.
It creates a container panel for your UI elements and attach a button linking to your options in the lobby.

<instance
    name="mod_options"    
    mod_id            A unique ID tag. Can be anything as long as it's unique (global) to your mod. Cannot contain spaces. (Example: mod_id="MOD_NAME_options")
    mod_name            The name of your mod.    
    itemheight="3h"            Height of all listitems, your elements cannot exceed this height.
/>

Cosmetic elements:

<!-- 
    Empty: Adds an empty line.
-->
<instance
    name="mod_empty"
    mod_id            Must be the same as used in the mod_options instance.
    font            Font.
    label            Label
    label_offset        Label offset.
/>

<!-- 
    Empty: Adds a line separator.
-->
<instance
    name="mod_line"
/>

<!-- 
    Header: Adds a header/separator.
-->
<instance
    name="mod_header"
    mod_id            Must be the same as used in the mod_options instance.
    align            Vertical alignment. (Note align is not horizontal here)
    collapsed="false"        Content should be collapsed by default.
    label_font="dyn_10"            Font.
    label            Label
    show_collapse="true"        Show collapse button.
/>

<!-- 
    Header: Adds a keybind header.
-->
<instance
    name="mod_keybind_header"
    mod_id            Must be the same as used in the mod_options instance.
    label_font="dyn_10"            Label font.
    label_color="yellow"            Label text color.
/>

Option Elements:

<!-- 
    General attributes: Below attributes are present in all of the below elements.
-->
<instance
    mod_id            Must be the same as used in the mod_options instance.
    trigger            Trigger to be called upon change.
    call_event            Call onevent of given object upon change. Works on alt_info interfaces.
    font="dyn_10"            Font.
    group_enable_value            Value to reach before group is enabled.
    group_disable_value            Value to reach before group is disabled.
    group_leader="false"            Group leader determine if group_id should be enabled/disabled.
    group_leader1="false"            Group leader determine if group_id1 should be enabled/disabled.
    group_leader2="false"            Group leader determine if group_id2 should be enabled/disabled.
    group_id            Group ID. Cannot contain spaces. Elements can be a member of multiple groups
    group_id1
    group_id2
    onchange            Executes code upon change. Remember to escape ' like so \\\'.
    inline="false"        If set the element will appear on the same line as the previous element.
    inline_padding="1h"        Space between elements.
/>

<!-- 
    Button: Adds a Button.
    Note: group_enable_value, group_disable_value, group_leader, group_id, labeloffset and onchange is not available.
-->
<instance
    name="mod_button"
    layout="empty"
    cmd            Code to execute onclick. Remember to escape ', like so \\\'.
/>

<!-- 
    Checkbox: Adds a checkbox.
    Note: Width is not available.
-->
<instance
    name="mod_checkbox"
    layout="empty"
    cvar            Variable name.
    cvartype="bool"        Variable type.
    default="true"            Default variable value.
/>

<!-- 
    Slider: Adds a slider 
-->
<instance
    name="mod_slider"
    layout="default"
    cvar            Variable name.
    cvartype="float"        Variable type.
    default="0.0"            Default variable value.
    slider_step="0.1"        Minimum step the slider can move.
    maxlabel="Max"        Maximum label.
    maxvalue="1.0"        Maximum value.
    minlabel="Min"        Minimum label.
    minvalue="0.0"        Minimum value.
    showpercent="true"        Show cvar as a precent of maxvalue.
    decimal="0"            How many decimals of cvar to show.
    showstep="true"        Show step buttons.
    button_step="0.1"        Value to increase/decrease cvar with when +/- buttons are clicked.
/>

<!-- Textbox: Adds a textbox -->
<instance
    name="mod_textbox"
    layout="default"
    cvar            Variable name.
    cvartype="string"        Variable type.
    default            Default variable value.
    maxlength="150"        Max string length.
/>

<!-- 
    Drop Down: Adds a dropdown menu.
    Use mod_dropdown_additem for adding items to the menu.
-->
<instance
    name="mod_dropdown"
    layout="default"
    cvar            Variable name.
    cvartype="int"        Variable type.
    default="0"        Default variable value.
    maxlistlength="5"        Maximum list length before scrollbar appear.
/>

<!-- 
    Drop Down Additem: Adds a item to the last dropdown menu.
    Use mod_dropdown to create a new dropdown menu.
-->
<instance
    name="mod_dropdown_additem"
    label            Label.
    value            Value.
    texture            Path to texture.
    texture_width            Width of texture.
/>

<!-- 
    Keybind: Adds a keybind.
    Note: Cvar, CVarType is unavailable.
-->
<instance
    name="mod_keybind"
    layout="default"
    table="game"        ENUM: game, shop, ui, console. Defines where the key is accessible from.
    action="Cmd"            Action bound to the key. Like: OrderMove/ChatTeam/Cmd
    param        If action takes parameters they go here.
    trigger        Trigger to call when key is pressed. When using this attribute ommit action or it'll fail. Param will be send along with the trigger, separate multiple params with space.
/>

Back to top

HowTo add your options.

Example: Adding a checkbox

<!-- First of we want to create a button in the "Mod Lobby" -->
<instance name="mod_options" mod_id="test_options" mod_name="TestUI Options" />


<!-- 
Now we have a button to our user interface. Lets add a checkbox. 
Note that mod_id is the same for both, this is correct. 
We choose a variable (test_var) the checkbox should represent, and we want test_var to be on by default.
We also assign a tooltip to the checkbox.
-->
<instance mod_id="test_options" name="mod_checkbox" cvar="test_var" label="Checkbox" tooltip="This is a checkbox" default="true" />

<!-- That's it -->

Example: Adding a keybind

<!-- This will open up the Team Chat box ingame -->
<instance mod_id="test_options" name="mod_keybind" label="A keybind example" table="game" action="ChatTeam" />


<!-- This will call a trigger when the button is pushed -->
<instance mod_id="test_options" name="mod_keybind" label="A keybind example" table="game" trigger="myTrigger"  />


<!-- This will remove all cooldowns and restore HP/Mana on the selected unit in a practice game.
Since table="game" and action="Cmd" are defaults I've omitted them in this example -->
<instance mod_id="test_options" name="mod_keybind" label="A keybind example" param="Refresh #GetSelectedEntity()#" />


<!-- This will simulate a rightclick on the minimap. -->
<instance mod_id="test_options" name="mod_keybind" label="A keybind example" param="eval MinimapRightClick(\\\'0\\\',\\\'0\\\');" />

<!-- Hope that clears up a few things. -->

Back to top

HoN Mod Manager Template

It's recommended to include a version check in your <requirement /> or <applyafter /> tags with the newest version of the framework, and remember to update it when you update your mod.

As standalone.

<modification>
    <requirement name="YOUR MOD" />
    <requirement name="Mod Options Framework" version="INSERT CURRENT VERSION-*" />
    <editfile name="ui/mod_options_elements.package">
        <find><=!=[=C=D=A=T=A=[<!-- INSERT AFTER THIS -->]=]=></find>
        <insert position="after">
            <=!=[=C=D=A=T=A=[
                <instance mod_id="MOD_NAME_options" name="mod_options"  mod_name="MOD_NAME Options" />
                <...>
            ]=]=>
        </insert>
    </editfile>
</modification>

Include in mod.xml.

<modification>
    <!-- Your Mod -->
    <editfile name="...">
        ...
    </editfile>
    
    <!-- Apply options if framework is present -->
    <applyafter name="Mod Options Framework" version="INSERT CURRENT VERSION-*" />
    <editfile name="ui/mod_options_elements.package" condition="'Mod Options Framework'">
        <find><=!=[=C=D=A=T=A=[<!-- INSERT AFTER THIS -->]=]=></find>
        <insert position="after">
            <=!=[=C=D=A=T=A=[
                <instance mod_id="MOD_NAME_options" name="mod_options"  mod_name="MOD_NAME Options" />
                <...>
            ]=]=>
        </insert>
    </editfile>
</modification>

Using a package.

<modification>
    <requirement name="Mod Options Framework" version="INSERT CURRENT VERSION-*" />
    <copyfile name="ui/MOD_NAME_OPTIONS.package" source="options.package" />
    <editfile name="ui/mod_options_templates.package">
        <find><=!=[=C=D=A=T=A=[<!-- INSERT AFTER THIS -->]=]=></find>
        <insert position="after">
            <=!=[=C=D=A=T=A=[
                <include file="MOD_NAME_OPTIONS.package" />
            ]=]=>
        </insert>
    </editfile>       

    <editfile name="ui/mod_options_elements.package">  
        <find><=!=[=C=D=A=T=A=[<!-- INSERT AFTER THIS -->]=]=></find>
        <insert position="after">
            <=!=[=C=D=A=T=A=[
                <instance to template package>
            ]=]=>
        </insert>
    </editfile>
</modification>

Back to top

Options Template

Template package.

<package>
    <template name="example_options">
        <instance mod_id="{name}" name="mod_options" mod_name="Example Template" />
        <instance mod_id="{name}" name="..." />
        ...
    </template>
</package>

You can then use <instance name="example_options" />. Note that the template name is also your unique mod ID. So choose wisely.

<find><=!=[=C=D=A=T=A=[<!-- INSERT AFTER THIS -->]=]=></find>
        <insert position="after">
            <=!=[=C=D=A=T=A=[
                <!-- Use template -->
                <instance name="example_options" />
            ]=]=>
        </insert>

Back to top

Version History

#################
## Version 0.9.5 ##
#################
Fix:
   - Fixed for HoN v1.0.3.

#################
## Version 0.9.4 ##
#################
Fixes:
   - Instead of making standalone templates for button catcher it now edits the default UI templates. (Popular demand)
   - You can now bind keys using modifiers again. (SHIFT+KEY)

#################
## Version 0.9.3 ##
#################
Fixes:
   - Fixed keybind incompatibility with other mods.
   - Fixed "'None' not valid axis" error message by default UI.
   - Inline attribute should now work for all elements.

#################
## Version 0.9.2 ##
#################
Fixes:
   - keybind:param: can now take args with space
   - keybind:trigger: if used keybind:param will be send with as trigger params, separate multiple params with space.

#################
## Version 0.9.1 ##
#################
Fixes:
   - keybind:trigger: Now works! Keep in mind the trigger has to be accessible from either the game or ui depending on your table choice.

#################
## Version 0.9 ##
#################
Fixes:
   - Many UI tweaks (default values), to bring it more in line with the FE2 options layout. (needs more work)
   - Slider now show value again
   - Various elements have disabled effect. (Still missing a few)
   - Upper right close button works again.
   - Removed debugger spam.
   - New default value to mod_keybind:action="cmd"
   - All attributes that previously required you to exclude the unit now accepts any unit. Thous of you using the old syntax will notice your element will become very small as it's thinks your value is in pixels.

Lobby:
   - Hover effect when mousing over options.
   - No longer requires you to click the Configure button, just click anywhere.

New attribute:
   - checkbox:width: If used the checkbox will no longer auto set width to the length of the label. Use it to make a grid of checkboxes.
   - keybind:trigger: Will trigger the trigger on when key bind is pressed. (If used don't change action or param)

Removed attribute:
   - Textbox:enabled: Use mod_custom instead.

New element:
   - Mod_keybind_header: It's a cosmetic element for you to put above your keybindings. Shows a label with Primary / Secondary.

#################
## Version 0.8 ##
#################
Fixes:
   - Scrolling now works in the lobby.
   - Resized the lobby a bit.

New:
   - Lobby will now show a notification when there's a new version available.

#################
## Version 0.7 ##
#################
Fixes:
   - Content is now correctly shown when expanded (header:collapsed="true").
   - Groups are correctly disabled when collapsed.
   - Collapsing/expanding no longer have an upper limit to how many items it can handle.
   - More FE2 conversion fixes.

New:
   - Groups can now be nested.
   - Each line can now have multiple elements.
   - Elements now support layouts. Layouts are predefined layouts of how you want your option to be represented. You can make your own or use the defaults.

New attribute:
   - general:inline. Will place current element next to previous element. Keep in mind that if previous element have 100% width it'll not look good.
   - dropdown_additem:texture_width
   - general:group_id1
   - general:group_leader1
   - general:group_id2
   - general:group_leader2

New element:
   - Mod_custom. Allows for user defined templates while still having functions provided by the framework, like collapse.

#################
## Version 0.6.2 ##
#################
Fixes:
   - FE2 compatibility.

Notes:
   - Discontinued support for the in-game options panel (F10), use F6 instead.

#################
## Version 0.6 ##
#################
Fixes:
   - Creating variables should now work again.
   - Textboxes now save onchange.
   - Changed max collapsed items from 50 to 100.

New attribute:
   - dropdown_additem:texture. Allow for textures inside the dropdown menu, like icons. (See server filter tier for an example)

Bugs:
   - Yes, dropdowns are still bugged. We have to wait for S2 on that one. The bug involves the droppeddown menu to be underneath the next element and unclickable, since it's under.
   - Groups are not automatically disabled in combination with header:collapsed=1. Bug in S2 engine regarding onshow.

#################
## Version 0.5 ##
#################
Fixes:
   - Comboboxes that use cvartype=string will no longer have their cvar set to empty when Reset All is clicked.
   - Header:collapsed now works.
   - Collapsed elements will now have the correct order when shown again.
   - Dropdown, slider & textbox is grayed out when disabled, like checkboxes.
   - Created variables with cvartype=bool are now true booleans and not integers.

New element:
   - Mod_button. (See documentation)

#################
## Version 0.4 ##
#################
Fixes:
   - Trigger/event is now called on resetting settings.
   - Checkboxes now has the same width as it's label.
   - Dropdown menus default value is now empty, instead index 0 will be default. If default is not set.
   - Keybinds works now. (I think)

#################
## Version 0.3 ##
#################
Notes:
   - Header/separator elements now have the ability to collapse all it's elements down to the next separator. The implementation of collapsing elements is kinda stupid and limited.  Expect an improved (if possible) version down the road.
   - You can now disable/enable groups of elements based on a condition, like the state of a checkbox. 
   - Lobby has a new look inspired by [NL]arnold_swe

Fixes:
   - Issue with call_event not working. (Thanks wuuh_riddie)

New attributes: (see documentation for more info)
   - general:group_id
   - general:group_leader
   - general:group_disable_value
   - general:group_enable_value
   - header:show_collapse
   - header:collapsed

Issues:
   - Collapsed elements will not keep their order when expanded if more than 10 elements is collapsed.
   - Not all option elements have disabled textures. So they may not look disabled but they are. If someone with graphic making capabilities would make them I'll include them into the framework.
   - Same as v0.2

#################
## Version 0.2 ##
#################
Notes:
   - Decided not to applying my dropup menu as S2 will fix their code in 3-5 weeks. So we'll just have to endure!

Fixes:
   - Elements will now have 100% width and resize appropriately when a scrollbar appear.

New attributes:
   - call_event="object_name" which will call onevent of object_name, works in alt_info*
   - onchange="stuff to do" which allows for customized code. However if you use ' you'll need to escape them like so \\\'. If S2 adds a StringReplace() I'll add support for automatic escaping, but until then you'll have to do it manually.
   - Slider:showvalue will toggle the display of cvar in the label. Default is on.
   - The mod_options element (container) now support itemheight="x" which will set the height of each item inside it. Default is 3. Note that height is given as a number without a unit. Example: itemheight="4" will set the itemheight to 4h.

Issues:
   - Same as v0.1

#################
## Version 0.1 ##
#################
Notes:
   - Initial release

Issues:
   - Keybinds not working.
   - Dropdown menus goes underneath below elements and is unclickable. (S2 is their code)
      - Workaround: Select the box and use the arrow keys to navigate.

Planned:

- Create at least one more layout

- Simplify layout settings.

- Redesign lobby

- Update documentation

- Ingame update alert.

- Attribute to auto resize elements using inline so total width is 100% for all.

- Attribute auto_width which will change the width of an element based on the content.


This is what the dropdown bug looks like:

Workaround: Open the dropdown menu as you would normally then use the ARROW (up/down) keys to navigate and use ENTER to select.

(Written the: 26-February)
GoGo (S2 dev) said the dropdown menu issue will be fixed in about 3-5 weeks.

Until then we just have to endure.

Nice Tisser!

[[ToX]AsiaPingPong]

Like I said in IRC, would you be interested in integrating the move/resize system I made for miniui?
It would fit flawlessly into this: you would be able to move the frames of many different ui mods at the same time, without a separate customization system for each mod.

This is a nice mod. I was thinking about requesting something similar to this before you posted this. What I was thinking about was adding something like this in the CC panel instead. But this works well too.

Yes Asia!

Originally Posted by ZarakiToguro

This is a nice mod. I was thinking about requesting something similar to this before you posted this. What I was thinking about was adding something like this in the CC panel instead. But this works well too.

CC panel bug makes this unreasonable at the moment.

Wow, player-made in-game Mod/Addon configuration menu
=
100% awesomeness

This is very cool. The CC panel is buggy, and the main UI can get cluttered with mod option tabs. Can't wait to see this release.

Originally Posted by NiGHTsC

Wow, player-made in-game Mod/Addon configuration menu
=
101% awesomeness

Fixed.

Originally Posted by Ignorance

CC panel bug makes this unreasonable at the moment.

I'm not sure what you mean with bugged, but if you are referring to things overlapping when you have too many options in there, then that is why I was saying a Mods button should be included in the cc. That way there is only one button, and from there, you can access the various options for all your installed mods.

Again though, not really needed if it's in the options menu now; kinda redundant.

No he's talking about the problem that parts of the CC panel go black when there's too much stuff in there.

Please post screenshots where it's actually possible to see anything.

Originally Posted by MaxGhost

No he's talking about the problem that parts of the CC panel go black when there's too much stuff in there.

I see. Have not experienced this myself.

This looks awesome.

Added a sneakpeak

How is this coming along? Think quite a few people are waiting for this to be released so they can use this for their mod options. No pressure though

I'm almost done. Only missing a good solution to dropdown menus. I've ported Buddy Follow, Channel Bar and BardUIs (without dropdown menus obviously) options.

Originally Posted by Tisser

I'm almost done. Only missing a good solution to dropdown menus. I've ported Buddy Follow, Channel Bar and BardUIs (without dropdown menus obviously) options.

Great to hear Tisser. Keep up the good work.

Right so I'm getting no where with the dropdown menu. So I'm releasing an early beta.

Keybinds don't work and the dropdown menus are TOTALLY ****ED!