HoN Script Editor Mv0.1/Sv1.0

[Oloko]

HoN Script Editor module

Introduction
Versions and download

Module
Schema

How to install
How to use

HoN project
Code completion
Validation tools
Options

FAQ
Special thanks

Introduction

HoN Script Editor is a module for the NetBeans IDE. The idea is to make the life of scripted easier by offering various useful tools (code completion, code validation, project management, etc.). You can see some screenshots in the "How to use" section.

This editor is not related in any way to S2Games, this is an unofficial editor I personally made.

This version of the editor is far from finished, since this was not fully tested, DATA LOSS should not happen, but is not impossible! Backup all of your work before and while using this module.
If you find any bugs or have any suggestion, you can simply post in this thread.

Versions and Download

Module
Schema

Module

Current version is: Beta v0.1
Download: MediaFire

Change log:

v0.1 12/08/2011:

• Released!

Schema

Current version is: 1.0
Download: MediaFire

Change log:

v1.0 12/08/2011:

• Released!

How to install

To make sure everything works, follow those steps carefully.

1. Download and install Java from http://www.java.com if you don't have it.
2. Download and install NetBeans IDE 7.0.1 from http://www.netbeans.org.
3. You can download any version of the IDE, the IDE will download any missing dependencies when installing. So you can choose the lightest one (PHP) if you simply want this module and nothing else.
4. Download the most recent version of HoN Script Editor module (link in the download section)
5. Start up Netbeans.
6. In the "Tools" menu, click on "Plugins".
7. On the "Downloaded" tab of the plugins window, click on "Add Plugins...".
8. Get to the org-hon-editor.nbm file you downloaded on step 3 and select it.
9. You should now see the HoNScriptEditor module in the list. Make sure it's marked for install and then click on "Install"
10. You will be warned that the module is not signed. Simply click on "Continue". Restart the editor if asked to.

You are now done with the installation!
Please read the next section to get started.

How to use

HoN project
Code completion
Validation tools
Options

HoN project
You can't create a new HoN project, you can only open existing project, so follow this to be able to open a project.

1. In NetBeans, go to "File" -> "Open Project..."
2. Go into your HoN directory.
3. You should see your "game" folder with a HoN logo, click on it
and then press the "Open project" button.

This is now your working directory for all your HoN maps/scripts.

If you want to "create" another HoN project, simply create an empty
resources0.s2z file in another folder and then open it as a project in NetBeans.
You will be able to open any folder with a resources0.s2z file as an individual project in NetBeans.

Code completion

When in a ".entity" file, you will be able to get "code completion" if you pres ctrl+space. Doing so will provide you with a list of elements/attributes that you can place at the location you are.
It will also provide some information/documentation about the element your are selecting in the list.

The code completion is done with the help of a XML schema file that is included in the module installation, but to keep it up to date, you will probably need to download newer versions from this thread.
For instruction on how to change the XML schema file used for code completion, see the How to - Options section.

Here is a screenshot of what code completion looks like:

In the picture above, we can see a lite of actions I can add at my cursor location. The Documentation panel at the top of the list display the a description of the element I have selected in the list. It also contain the list of attribute the element can have.
The attribute list on the panel: the attribute name, its "type", its default value if available and then a short description of the attribute if there is one (there is none in that screenshot).
Notice that the attribute "name" is in bold, that means its a required attribute to the element (its required for it to work).

There is also a list of children an element can have at the bottom of the documentation panel:

For this element, you can see that it has no child and that will probably be the case for most actions. On some action, you will see that you can have children, which can help to identify actions that can execute code for specific pattern like conditions, compare, areaofeffect, etc.

As for an attribute completion, here is a screenshot for the "areaofeffect" action:

Here you can see in the completion list that "targetscheme" is in bold. This is because I am missing it in my element and that it is required by it.
As for the documentation panel, you have a short description for the attribute if available, its type and then a default value if it has one. In this case the default value is "0" (unlimited number of impacts) even if I don't set it.

Validation tools

There is two validation tool available for entities files. One is the "XML check" and the other is "XML validation".

The "XML check" tool can be used to detect basic XML error like a missing closing tag.
The "XML validation" tool will not only do basic XML error detection, but will also do a validation of your XML file on the XML schema. This mean that it will also detect if there is a typo in an attribute, if an action is miss placed, if you are missing required attributes and more.
Here is a picture of the "XML validation" tool in action:

In the red box at the top is the two validation tools. The one to the left is the "XML check" tool and the one to the right is the "XML validation" tool.
In that picture the tool used is the "XML validation". The result of the validation is shown in the "Output - XML check" window at the bottom.
Here I have 3 errors:

1. <onimpact /> event can't be placed here.
2. <areaofeffect /> action is missing a required attribute named "targetscheme".
3. The <scriptcondition /> action is missing a ">" at the end.

At the end of each error you have the line number and clicking on the error will mark the line in red in the editor as shown in the picture for the <onimpact /> error.

The "XML validation" tool might something return error on lines that you know works. That is either because your schema file is out of date and you should update it or that the official documentation I based my schema on is wrong. If you still get the error after updating, then report it in this thread.
Since the schema I made is based on the inaccurate and incomplete documentation we have, then it might return false positive in some case, but it will most of the time save you a lot of time for basic error.

Options

For now there is only one option you can change for the module, but more might be added in the future.
To get to the module options go into the "Tools" menu, then "Options".
In the "Options" window, click on the "Miscellaneous" icon. You should now see a tab named "HoN Editor", clicking on it will show the options for the module.
Here is a picture of it:

The "Schema path" option is the path to the file that is used for code completion and validation. If its not set, the module will use the file that came with the installation.
You will, at some point, need to update your schema file. So you simply need to download the most up to date file from this thread and then set its path here. Take note that if the file that is set here is not found, the module will load its bundled schema file.

FAQ

Q. I'm trying to create a HoN project, but I can't find it in the list of project.
A. You can't create a HoN project, you can only open up existing projects and that is a folder that has a resources0.s2z file in it. Read the How to - HoN project section for more informations.

Q. Can I use your schema file for my own project?
A. You can use the schema file how you want but I would still like to have some credits for it since it took me a lot of time to make.

Q. Can I help you with anything?
A. For now I'm mostly looking for feedback more than anything. Giving out suggestion, bug report is the only thing I need right now (unless you could provide me with a more accurate official documentation).

Special Thanks

To the NetBeans community for their wonderful documentation/tutorial/wiki.
To TrueZIP (http://truezip.java.net/) for their nice library!

[Tafelpoot]

Woop woop ! First

[Tafelpoot]

After some testing, these are my first remarks :
- Typos in plugin description "It will also add a new type of project: HoN projets." , "XML validaiton"
- Nonsense commands are not detected, unlike in your screenshot where <onimpact/> calls an error. I cannot reproduce this
- Attribute values are not checked to be valid (like duration="herpderp"). Some attributes are easy to check (like numbers only). S
- Areaofeffect doesn't have the innerradiusoffset attribute (I wish it had it though) and the targetselection defaults to null (""), which implies it's a required attribute as well.
- You need a type="PlayerEntity" for setcamera, setgold, changeteam, takegold, ...
- Ubuntu Fileroller doesn't allow creating new files or moving files to s2z files. (linux problem)

Needless to say that this app is awesome, and it will get better !
I will make a bleeding edge edition, containing even more commands that are not officially supported yet. Examples : giveexperience, lineofeffect, ...

One last request : since you parsed the resources0.s2z , can you make a list with all the existing variables ? Example: source_health, source_team, source_strength, target_movespeed, proxy_charges , charges (= this_entity_charges), ...
And a list with all the functions for <condition test="function"/>, example in armadon3 :

<condition test="back_impact_angle le 55">

[Oloko]

Thanks a lot for the feedback, I really appreciate it.

After some testing, these are my first remarks :
- Typos in plugin description "It will also add a new type of project: HoN projets." , "XML validaiton"

Fixed, will be in the next version (v0.1.1).

- Nonsense commands are not detected, unlike in your screenshot where <onimpact/> calls an error. I cannot reproduce this

I would like to have more info on this one please. The tag <onimpact /> itself isn't wrong, what is wrong is if its used somewhere a event tag can't be used. In my screenshot, I used it in a <scriptthread /> event which is wrong.
First of, make sure you are using the XML validation tool and not the simple XML check, since a simple check will not recognize the schema. If that's not the issue, make sure it's really in a spot where it should throw an error.

This should trigger an error:
<hero>
<onframe>
<onimpact />
</onframe>
</hero>

but this will not:
<hero>
<onimpact />
</hero>

Even if it doesn't really make sense to do so, you can still do it (some official files have things like that) and its something used to force the display of some extra tooltip info.

Please tell me if it does work or not, since I can't reproduce this issue.

- Attribute values are not checked to be valid (like duration="herpderp"). Some attributes are easy to check (like numbers only).

That is one thing that is annoying. I can't really put a good type that would give a good validation for any attribute.
The issue with attributes in HoN scripts is that it can have almost any kind of value.
Lets use the duration attribute for example. The basic value for it would be a non-negative integer:
duration="1000"

but what if you do:
duration="1000,2000"

This is also a valid value and is used in a lot of place, so we would need a pattern validation that test for multiple non-negative integer with a ',' separator.
This is still easy to do, but we also have a value like this possible:
duration="value"
or we could even have:
duration="var0,var1,var2"
This of course doesn't make much sense when you look like this, but its not a bad syntax. Making a validation now would probably still be possible, but I don't know if its really worth it at that point. If you still think it could be useful to have, simply say so and I will try adding it.

There is the case of entities attribute that could have a basic pattern, since you can't use variables in them. So I could probably do validation for:

<gadget
lifetime="1000,2000"
>
</gadget>

Since you can't use variables at that point, you can only have a list of basic types separated with a ','.

- Areaofeffect doesn't have the innerradiusoffset attribute (I wish it had it though) and the targetselection defaults to null (""), which implies it's a required attribute as well.

The innerradiusoffset attribute is from S2 documentation in the sticky, but I haven't tested it. It is not used in any official script, so its a possibility for it not to be working. I will test it to validate.

As for the targetselection attribute, the default value is not null, but is simply not set. I know it seems to be the same, but it doesn't has the same meaning. The default value is not set because I don't know the default behavior of the action. We can agree that it's impossible that there is not one by default so it either has one or it would be required, but its simply that I don't know which one it is.

The thing is that every attribute should either be required or have a default value, but testing all of them is impossible for me. So for now I release it with the missing default value for most attributes and then people can report their find.

The idea is that the documentation/validation will be a bit lacking at first, but the more people gets involved, the more polished it will get.

- You need a type="PlayerEntity" for setcamera, setgold, changeteam, takegold, ...

As far as I know, the value of the PlayerEntity type would be the same as the EntityType, because a player entity is an entity. So it can be: proxy_entity, entX, targe_entity, etc. As long as the given entity is a player it will work.

But I agree that letting the user know it should target the player entity and not the hero would be good. So I will probably add a note in the documentation.

- Ubuntu Fileroller doesn't allow creating new files or moving files to s2z files. (linux problem)

I have only tested the editor on Windows XP and Windows 7 64-bit. I will try to install Linux (or use a live-cd) to test it (probably Ubuntu).

Needless to say that this app is awesome, and it will get better !
I will make a bleeding edge edition, containing even more commands that are not officially supported yet. Examples : giveexperience, lineofeffect, ...

I'm glad you like it!
Rather than making your own version of the schema, I think it would be nice if you could simply report the missing commands so that I can simply add it to mine. That way we will only have one file that everyone can use, rather than having multiple version of the schema.

One last request : since you parsed the resources0.s2z , can you make a list with all the existing variables ? Example: source_health, source_team, source_strength, target_movespeed, proxy_charges , charges (= this_entity_charges), ...
And a list with all the functions for <condition test="function"/>, example in armadon3 :

<condition test="back_impact_angle le 55">

I didn't actually parsed the resources0.s2z file, I simply validated by hand every single file in it (I know parsing it would have been easier, but I simply wanted to test my validation tool at the same time). Getting the list of usable variables is not impossible. It could be useful to add to the documentation sticky, but I won't really be able to use them in my editor.

Don't hesitate to give more feedback, even if its negative. The project is only at the beginning and I need to know what do people really want to have. Right now there is only the basic stuff that, the next step would be to have more advanced tools to help out scripting (ex: a single input box to create new targetscheme on the fly while scripting).

[Tafelpoot]

Woot long response.

1. it's the
<hero>
<onframe>
<onimpact />
</onframe>
</hero>
that doesn't pop any errors. The only errors i can produce are xml check errors. So the validation tool seems not to work for me ...

2. I did a lot of research on areaofeffect and lineofeffect, and I can verify that both targetscheme and targetselection are required if you want to obtain any targets.
Lineofeffect has the same possible attributes as areaofeffect, except it has no center attribute but it has start and end. For proof, look at the step abilities in my Chess map.
Also there is giveexperience, working the similar as givegold. I show how all these work in game_info.entity of the slither bomberman.

3. The fileroller issue ... it might get fixed in the next big update.

4. That list with variables and condition functions would be absolutely awesome. Maybe I could try to figure out how it should be done, something with zipgrep ... but I hoped you know how to do this

[[RiA]FlameStick]

This will be a great help

Tnx Oloko!

[Oloko]

I will be leaving HoN custom maps scene for obvious reason, so I won't be working on this anymore.

I will still receive e-mail for PM and posts from this thread. So if at some point someone wishes to continue this project, I might give out the source code, but I don't think there is any need for this right now.