Mod Options FrameWork
Content:
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.
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 ' 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.
Code:
<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:
Code:
<!--
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:
Code:
<!--
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
Code:
<!-- 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
Code:
<!-- 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 TemplateIt'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.
Code:
<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.
Code:
<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.
Code:
<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 TemplateTemplate package.
Code:
<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.
Code:
<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
Code:
#################
## 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.
Originally Posted by IRC
Posting Permissions
