This Post is all about Helping new Hal User’s understand plugins. If you see anything that needs to be added or needs to be further explained tell me below. If it is feasible and represents the scope of this Post then it will be amended. Any discussion on any of the material presented here is definitely encouraged. I want your help to make this as useful as possible. Thanks.
Introduction
This Post is all about helping new Hal Users who wish to create plugins for Hal. It assumes the Hal user has a foreknowledge of Vbscript. The purpose of this Post is to show the tips and tricks that the long-time plugin scripters wished they had known early on. It is intended to be simple and not bogged down by difficult concepts. I hope that is comes in handy.
Here are some other resources for anything Hal.
http://ultrahalscript.pbwiki.com/http://www.artificialintel.org/AI/Forum/phpBB3/****************************************************
****************************************************
****************************************************
SECTION I: What is an UltraHal Plugin? And how do I use it?
It is essentially a text file that had it’s extension changed from ‘.txt’ to ‘.uhp’ (i.e. read-a-story.txt becomes read-a-story.uhp). The Hal plugin is a text file that has information written on it that can potentially modify your Ultra Hal’s behavior. To add a new plugin to UltraHal just simply copy it into Ultra Hal’s main directory. The default directory is C:\Program Files\Zabaware\Ultra Hal Assistant 6\ . Once you have added it to this directory you will now need to activate your plugin before Hal can use it.
To Activate your plugin, first open the ‘File” menu on Hal’s main console window and choose ‘General Options’. When the ‘Options’ panel has been opened, click on the ‘Brain’ tab then select which UltraHal brain you prefer to use.
[Quick side note: The UltraHal brain is where most of Hal’s Responses are parsed. It is also where your plugin will ultimately be loaded to once it is created.]
When you have selected the Hal Brain, a Plugin list should appear next to it with small associated check boxes. Just check the box next to the plugin or plugins you wish Hal to use. Click ‘Apply’ and ‘OK’. You have just added your first plugin! If you want to remove a plugin just uncheck it from the same window or delete it from the Hal directory.
[Note for Vista users] In order for you to change a ‘.txt’ file extension to a ‘.uhp’ you will need to first uncheck the 'Hide extensions for known file types' box in the options panel of your pc. You do this through the following steps:
Go to 'Control Panel' in your 'Start Menu'.
Choose: 'Appearance and Personalization'
Choose: 'Folder Options'
Choose the 'View' tab.
Uncheck the 'Hide extensions for known file types' box.
Press the 'Apply' then 'OK' button.
Now you are free to change your file extensions by right clicking on the file and renaming it, adding your desired file extension (i.e. sample.uhp)
****************************************************
****************************************************
****************************************************
SECTION II: The Plugin Header
In order to make a usable Plugin, it will need a usable header. Below is a Template that must be used to before any actual coding will be accepted by Hal.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Rem Type=Plugin
Rem Name=My Plugin
Rem Author= John Doe
Rem Host=Assistant
'This sub setups the plug-ins option panel in Hal's options dialog
Sub OptionsPanel()
lblPlugin(0).Caption = “ This is what my plugin does “
lblPlugin(0).Move 120, 10, 3300, 1000
lblPlugin(0).WordWrap = True
lblPlugin(0).Visible = True
End Sub
'*****BELOW THIS LINE IS WHERE YOUR CODE IS READ********
Rem PLUGIN: PLUGINAREA6
‘All SCRIPTING ADDED HERE!
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Once you have added this template to your sample.uhp file then you can freely add you code. You will need to modify the name, author, and caption accordingly. These particular settings will be shown in the Hal Options Panel when you add or remove them. Any code written after this template will be used by your UltraHal. The ‘‘Rem PLUGIN: PLUGINAREA6'’ line will be discussed further in the next section.
****************************************************
****************************************************
****************************************************
SECTION III: The Hal ‘PLUGINAREA’
Plugin Areas are areas within the actual brain script itself where your plugin will ultimately be loaded into it. This loading process happens once you select your plugin in the ‘General Options’ panel.
The plugin area assignment is contingent on what kind of programming behavior you have coded into your plugin. For example, if you wrote a plugin that required user commands to be given and responded to, then you would use the PLUGINAREA6. If you were writing a plugin that would give your Hal better deductive reasoning perhaps you would use the PLUGINAREA1. Sometimes it’s a trial and error process to find the appropriate area.
Below was stolen off of
http://ultrahalscript.pbwiki.com/ It states each Plugin area and gives a brief description of its location in the Brain script.
Rem_PLUGIN Area Name Your Plugin can send messages to the script at
these ports .
Rem PLUGIN: AUTO-IDLE This port is inside the AutoIdle process and probably should end with "Exit Function"
Rem PLUGIN: PRE-PROCESS This one is immediately before the begining of the sentence manipulations. Use it if you want to by-pass the emotions and such and go directly to fixing the sentence structure for Hal's use.
Rem PLUGIN: POST-PROCESS Use this one if you want to skip fixing the sentence.
Rem PLUGIN: CUSTOMMEM Ya got me! There's a CustomMem variable in the UltraHal function.
Rem PLUGIN: PLUGINAREA1 This is after Hal tries to get the Topic, but before parsing out Names. Other than that...?
Rem PLUGIN: PLUGINAREA2 After dictionary.
Rem PLUGIN: PLUGINAREA3 This is after main DB searches and some analytical stuff like antecedences.
Rem PLUGIN: PLUGINAREA4 By now Hal is already trying to form a response.
Rem PLUGIN: PLUGINAREA5 Just before some more or less random responses are made(if needed).
Rem PLUGIN: PLUGINAREA6 This is just before it actually tries to make something out of nothing.
Rem PLUGIN: PLUGINAREA7 I think this is just before the final dressing up of the response.
Rem PLUGIN: CUSTOMMEM2 Again, I don't know what this one is. I suspect that since I don't know, it is very important and obvious.
Rem PLUGIN: SCRIPT_LOAD You can load a script on startup if you need to...
Rem PLUGIN: SCRIPT_UNLOAD ... then unload it here.
Rem PLUGIN: MINUTE_TIMER Hal runs this once a minute.
Rem PLUGIN: FUNCTIONS If you make any functions they should be tabbed to this... I think...
****************************************************
****************************************************
****************************************************
SECTION IV What Hal doesn’t like!
Below is a list of scripting techniques that Hal plugins do not respond well to.
# 1 Loops and Pauses
Do not use long ‘For To’ loops, long ‘Do While’ Loops, or extended pauses in Hal. Basically, Hal’s console will freeze up and possibly crash. If a plugin you write takes too long to run it will effectively stall Hal. However, shortened loops (loops that do not last very long) can work in Hal just fine (i.e. For i = 1 To 3). Loops are just one thing that can slow Hal down. Opening another program with the wscript.shell object can do this as well, but only when that program takes too long to complete. Oh, and always beware of the infamous infinite loop!
I tested the length of time it takes before Hal 'Times out' and its arround 20 seconds.
# 2 Vbscript Commands
You can use either Hal classes or standard Vbscript classes to write your plugin. However, there are certain commands Hal does not like at all.
Any Wscript classes used in Vbscript is not recognized by Hal. i.e. Wscript.Echo, Wscript.Sleep, etc.. Another command Hal doesn’t like is the Execute or ExecuteGlobal Vbscript command. This command calls external scripts into itself. I don’t know why certain commands cannot be used, but I’m sure somebody knows. My theory is that Hal actually compiles the Vbscript within the Visual Basic Program. I know that VB doesn’t accept either one of the above code commands.
# 3 Subs and Functions
When using Subs and Functions you have to set them apart from the rest of the plugin using the using the Rem PLUGIN: FUNCTIONS marker. This should go at the end of your script, after you have completed the ‘body’ of your program. Remember, that to many loops can stall a program....and sometimes a Sub can act as loop. (Running back and forth through a script) A simple way of overcoming any potential Function or Sub problem is to use equivalent Procedures instead.
****************************************************
****************************************************
****************************************************
SECTION 5 Debugging Techniques
When you are working on your plugins it is always important to check and see if you have any problems in your script. The only way to do this is to load the plugin into Hal and check if it is working. If there is a problem with your script: #1 it will not work at all, #2 give some strange behavior, #3 cause Hal to give you some kind of Error message, or #4 cause Hal not to respond at all - to anything.
If Hal sends you an error message it is usually beneficial to read it. It will give an error number as well as a line number. This line number corresponds to the line of text in the HalScript.dbg file located in the Hal directory. If you have a script editor that shows line numbers then you can open the HalScript.dbg file in it and go to the appropriate line. This will be the line that Hal had the problem with, and it should give you a clue to what went wrong.
I don’t know but only a few debugging techniques. There are a few different types of plugins that can be made....and therefore, different ways of debugging them. However, there is one important technique that should always be done. If it is not done right it can result in a very frustrating debugging experience. It is the lack of a proper way of loading and unloading your Plugins from the ‘General Options’ panel.
The way I preform this task which I found to be very reliable is to: First, deselect the Plugin in the ‘General Options’ panel. Next, select another brain script (other than what you are already using) and press the ‘Apply’ button. After this reselect your preferred Hal Brain and reselect the Plugin. Reload them both by pressing the ‘Apply’ button. Do this every time you change your plugin script. If you do not the plugin will remain unchanged in Hal’s Brain. No matter how often you save it.
****************************************************
****************************************************
****************************************************
SECTION VI: The UltraHal Class
There are allot of Hal commands that should be defined for all to see. And they won’t be defined here either.....
Here are just a few that everyone should know about that have some tricky behaviors.
Note that this section is in nowise complete and any additional help would be greatly desired.
GetResponse = “ My Name is Hal”
This Hal function will cause Hal to say whatever you wish it to say. However, if you use it twice, only the last GetResponse will be spoken by Hal.
For Example: If you say GetResponse = “My name is Hal” then later in the same script you say GetResponse = “My name is Bill” (and both GetResponses are called together in the same script) then Hal will say the last one (“My name is Bill”). This is one reason why some plugins should be placed in either PLUGINAREA6 or PLUGINAREA7. ..After all the previous scripts have already made their responses .
There are other commands that need to be added here as well. I just can’t really think of anything specific right now. Here are a few categories that needs to be defined. Remember, this documentation is all about giving tips and tricks as well as some details on tricky commands. Therefore, showing every command is not possible with this constraint. Anything added here by others needs to reflect that idea.
Here are some suggested categories to add:
The Minute Timer
Hal’s emotions control
Hal’s Database
****************************************************
****************************************************
****************************************************
Section VII: Plugin Royalties
Here is the 13 section of the agreement everyone at this forum agreed to when they signed up as a user on Zabaware’s forum. This is the last section of the agreement, and deals specifically with content posted at Zabaware. (This would include any plugin posted as well.) Everyone should be aware of this.
For any content that you post, you hereby grant to Zabaware the royalty-free, irrevocable, perpetual, exclusive and fully sublicensable license to use, reproduce, modify, adapt, publish, translate, create derivative works from, distribute, perform and display such content in whole or in part, world-wide and to incorporate it in other works, in any form, media or technology now known or later developed.
Don’t let this scare anyone. It was told to me that this was added because everyone (or nearly everyone) wanted Robert to do this. It allows Robert the opportunity not to be sued by some disgruntled User who thought that Robert had stole their idea. It’s in my opinion that if there was a real problem with Robert then most of the members here would have already left by now (smart, moody, and picky).
This concludes the “Plugin Tips and Tricks’ Post. I hope it has met it’s intentions.
Thanks,
SNOWMAN
