How to write a script
-
This is an easy-level tutorial on how to edit, save, and run a (client-side) HSL script. For server-side scripts, see Creating server scripts, and for quickref expert instructions, see HSL for programmers.
Overview
The first thing to understand about writing scripts in HeroEngine, is that there are two different types of scripts:
For more on this, see Client-Server architecture.
The language for both sides, client and server, is the same, but each works with its own DOM database, and the scripts are stored and compiled separately.
When accessing a script via the Script Editor, it is necessary to specify client-side or server-side at the beginning. Also, when browsing a directory of scripts, you will be browsing only one side or the other at a time.
As a reminder of which type of script you are currently editing, a "C" or "S" will appear at the top of the Editor.
Scripts execute in response to external events (see Script entry points). This may be commands from a player client, callbacks from input events, server events, or other methods.
- Client scripts can also be run or CALLed manually, from the Console Window
- Server scripts can be run manually via commands which are typed into the Chat panel.
Create and run a client-side script
Client-side scripts run only on the client. They can be run manually by using the CALL command in the Console window.
- Open HeroBlade
- Ensure that the Console window is open, since you'll need to type a command into it later to run the script. If it is not open, ensure that it is checked in the Tools Menu.
- Open the HeroScript Editor with CTRL+H, or go to the HeroScript menu and choose "HeroScript Editor (HSE)".
- From that window's menu, choose: File >> New >> Client Script
- Name the script. It must have a unique name. If this is your first script, give it your own name.
- For more information on valid names, see Definition Names.
- Create a function in the script. For example:
function HelloWorld() SendChat(SYSTEM.EXEC.THISSCRIPT + " Hello world! Or at least Hello Area!", "game") .
- The SendChat() function takes two parameters: (<message>, <channel>) How channels are used is defined by each game's specific chat implementation, so for this example we simply use an empty string.
- Compile the function by clicking on the menu button that says "Compile" or F7 on your keyboard.
- At this point, in the bottom part of the editor, you will see either
Compile succeeded, or an error. If there's an error, it will tell you which line number and what type of error. Fix it, and compile again, and repeat, until you get a successful compile. - Even with a successful compile though, the script still isn't ready to run yet, because it hasn't been submitted to HeroEngine.
- At this point, in the bottom part of the editor, you will see either
- Submit the new version of the script, by clicking on the
Submitbutton.
- This will bring up a "comments" box. Enter something into the box that gives a rough summary of what you've done, like "Created new script" or "fixed a typo", etc.
- At the bottom of the editor window, should now be a message:
SUBMIT of <script name> succeeded. New version number: <##>
- At the bottom of the editor window, should now be a message:
- Switch back to the game window.
- Run the script, by typing into the input box of the Console window, with the following syntax:
call <scriptname> <functionname>
- Example:
call chiv HelloWorld
- Example:
- You should see a message pop up that looks like:
[<Your name>] [<Your script name>]Hello world! Or at least, Hello Area!
- Congrats!
Note: The reason that your name is prepended to the beginning of the message, is because this is automatically done by the SendChat() function. This function was used, since it was the easiest way to get a message from the Client to show up. To generate a message that does not use this format, it will be necessary to use a server-side script.
For your next trick, please continue to Creating Server Scripts.
