Script Editor
Christopher (Talk | contribs) (→Keyboard Shortcuts) |
(Fixed references to XML page) |
||
| Line 1: | Line 1: | ||
| − | |||
{{tocright}}The '''HeroEngine Script Editor''' provides an interface to read and edit scripts. It is built directly into [[HeroBlade]] and has many of the same modern features that can be found in other language editors, but is designed specifically to help create scripts in HeroScript Language (HSL). | {{tocright}}The '''HeroEngine Script Editor''' provides an interface to read and edit scripts. It is built directly into [[HeroBlade]] and has many of the same modern features that can be found in other language editors, but is designed specifically to help create scripts in HeroScript Language (HSL). | ||
| Line 26: | Line 25: | ||
** Client scripts | ** Client scripts | ||
** Server scripts | ** Server scripts | ||
| − | ** | + | ** [[GUIXML]] |
'''Important''': The display of available scripts will at first ''only'' show Game-specific scripts (see [[Distribution package]]). To see all of the scripts in the original Clean Engine package, select the "Show Engine" checkbox at the bottom of the menu. | '''Important''': The display of available scripts will at first ''only'' show Game-specific scripts (see [[Distribution package]]). To see all of the scripts in the original Clean Engine package, select the "Show Engine" checkbox at the bottom of the menu. | ||
| Line 54: | Line 53: | ||
CTRL-SHIFT-C Open a Client Script | CTRL-SHIFT-C Open a Client Script | ||
CTRL-SHIFT-S Open a Server Script | CTRL-SHIFT-S Open a Server Script | ||
| − | CTRL-SHIFT-G Open a GUI XML file | + | CTRL-SHIFT-G Open a GUI XML file |
CTRL-SHIFT-L Open a CLI file (not yet working) | CTRL-SHIFT-L Open a CLI file (not yet working) | ||
CTRL-SHIFT-F Opens the Function List panel | CTRL-SHIFT-F Opens the Function List panel | ||
Revision as of 20:37, 19 October 2011
|
Related tutorials
Invoking
There are multiple ways to open the Script Editor. Either:
- With HeroBlade open and focus in the render window, hit CTRL-H
- Open HeroBlade's Organizer panel, and double-click a script to edit
- Via the HeroBlade dropdown menu, Tools > HeroScript Editor
Opening a Script
To edit a specific script, either:
- Choose it via the Organizer Panel
- In the Script Editor, hit CTRL-SHIFT-S for server scripts or CTRL-SHIFT-C for client scripts, and start typing the name of that script.
- Or, in the Editor, choose File/Open, and select either:
- Client scripts
- Server scripts
- GUIXML
Important: The display of available scripts will at first only show Game-specific scripts (see Distribution package). To see all of the scripts in the original Clean Engine package, select the "Show Engine" checkbox at the bottom of the menu.
Scripts that are part of Clean Engine, will be prefixed with a "_" character.
In the Script Picker, scripts listed with purplish/pinkish text are scripts that the viewer created (or "owns").
Scripts recently edited have a green background: dark green at first, then fading to white with each day, until back to fully white after a week.
Also, scripts listed with blue text are ones that the viewer was the most recent person to edit them, but does not own them.
Script editor
An opened script will look like this:
Keyboard Shortcuts
ESC Deselects All Selected Text, cancels member lists and parameter tips
ALT-G Jumps to and opens if necessary the script that implements the method in which the cursor is located.
CTRL-] Move to matching bracket/parenthesis
CTRL-ENTER Open line above
CTRL-SHIFT-ENTER Open line below
CTRL-SPACE Attempts to complete the current word
CTRL-SHIFT-SPACE Brings up function/method call parameter tip
CTRL-SHIFT-C Open a Client Script
CTRL-SHIFT-S Open a Server Script
CTRL-SHIFT-G Open a GUI XML file
CTRL-SHIFT-L Open a CLI file (not yet working)
CTRL-SHIFT-F Opens the Function List panel
CTRL-/ Comment out the currently selected (or where cursor is) lines.
CTRL-SHIFT-/ Un-comment out the currently selected (or where cursor is) lines.
CTRL-G Bring ups Goto Line# dialog
CTRL-H Toggles History Panel Open / Closed
CTRL-T Toggles Task List Panel Open / Closed
CTRL-R Resolve
CTRL-F Brings up Find / Replace Dialog
CTRL-SHIFT-A Brings up Find In All Scripts Dialog
CTRL-I Starts a Dynamic Incremental Search (search from cursor down) Using CTRL-I repeatedly,
will find the next occurrance of its current match.
CTRL-SHIFT-I Starts a Dynamic Reverse Incremental Search (search from cursor up). Using this
repeatedly will find the next previous occurrence of what it’s found so far.
CTRL-T Transpose characters
CTRL-SHIFT-T Transpose words
CTRL-SHIFT-ALT-T Transpose lines
CTRL-U Change selection to lowercase
CTRL-SHIFT-U Change selection to uppercase
CTRL-W Toggles Word Wrap On / Off
CTRL-Z Undo
CTRL-Y Re-do
CTRL-C Copy selected text
CTRL-V Paste at cursor (overwrites any selected text)
CTRL-X Cut (Removes the selected text from the original location after a paste)
DELETE Deletes the selected text or the next character to the right of the cursor
CTRL-F2 Toggle Bookmark on line where cursor is located
CTRL-SHIFT-F2 Clear Bookmark on line where cursor is located
F2 Goto Next Bookmark
SHIFT-F2 Goto Previous Bookmark
F4 Goto Next Find Result
SHIFT-F4 Goto Previous Find Result
F6 Auto Reindent Script
F7 Compile
SHIFT-F7 Submit
F8 Goto Next Error
SHIFT-F8 Goto Previous Error
File
- Compile
- Compiles the active (tab selected) file. This option is only visible when at least one file is open.
- New
- Creates an empty file for a client or server script. You’ll fill out a name for the script and a description. Descriptions can be later edited.
- Open
- Opens a server or client script.
- Save
- Saves only the active (tab selected) file.
- Save All
- Saves all unsaved files currently opened.
- Recent Scripts
- Give a list of recently opened scripts for quick access.
- Exit
- Closes HeroScript Editor
Edit
- Undo/Redo
- Undoes or re-applies separate edits made to the active (tab selected) script file in the order they were edited.
- Cut/Copy/Paste/Delete
- Work as expected.
- Auto Reindent Script
- Will go through the active script file (tab selected) and re-indent each line.
- Comment Selection
- Will Comment out the selected line/s of code. CTRL-/ is the keyboard shortcut.
- Uncomment Selection
- Will Uncomment out the Selected Line/s of code. CTRL-SHIFT-/ is the keyboard shortcut.
- Complete Word
- If the HeroSense word-completion box is not already open, this will open it.
- Parameter Info
- When the cursor is on a function/method call, this will show the parameter info tooltip.
- Word Wrap
- Toggles word wrap on and off. Word wrap forces the lines of code to fit on the screen, wrapping to the next line if necessary.
Search
- Find & Replace
- Allows you to find specific text in the active or all opened script files.
- Mark with bookmarks checkbox
- Marks each line as you click on the Find Next button.
- Mark All button
- This will mark each line where a match on the search if found.
- Use checkbox
- When checked, regular expressions can be used to search the script.
Incremental searching
- Incremental Search
- This allows you to do an interactive search of the currently active (tab selected) script. Instead of a dialog, when you do an incremental search, the mouse cursor will change to show you’re doing an incremental search
. As you type, the text edit cursor will move down (indicated by the arrow on the mouse cursor) to the next text that matches what is being typed, highlighting the letters it finds.
Below is an example of how this works. In this example, the writer ultimately typed id = The four pictures show how the search worked as the letters were typed in incrementally:
After typing in "i": 
After typing in "id": 
After typing in "id ": 
After typing in "id =": 
Note: After finding what you want:
- CTRL-I (incremental search) will find the next occurrence
- CTRL-SHIFT-I will find the previous occurrence.
- Reverse Incremental Search
- This works exactly like Incremental search except that this will search up (indicated by the arrow on the mouse cursor
) instead of down from the text edit cursor.
- Goto Line…
- Brings up a dialog allowing you to type in the line number you wish to the text edit cursor to “jump” to. This will scroll the window so that the line is visible.
- Show Functions and Methods
- This brings up a window that lists all the functions and methods in the currently active (tab selected) script.
- Double clicking on a function name will move the text edit cursor to its location in the text.
- Right-click in this window to toggle whether the functions are listed alphabetically or in the order they exist in the script.
- While open, when the cursor is placed on a line in a function or method, its name will be highlighted in the Function window.
Tools
- Compile
- Will attempt to compile the active script (tab selected). If successful, the Submit menu option will become available. A successful compile will not cause the script to be used by the server or client. You must successfully submit it first.
- Submit
- After a successful compile, this will submit the script to be saved and used by the server or client as the most recent revision of that script.
- Resolve
- If the submit encountered a specific situation, this menu option will become active. The situation is when someone else is editing the same script, compiled it and submitted it before you submitted your change. In this case, you must resolve the conflict before you can submit it.
- Abandon
- Only available when changes have been made to a script, whether they are saved or not. This will discard the changes and reload the last submitted version. CANNOT BE UNDONE
- Distribution Package
- Set the distribution package of the script to be either Required, Optional, Game, or Optional Game.
- Delete Script
- Marks the script as deleted. Its code will no longer be valid, but the script is not discarded completely.
- Undelete Script
- Marks a deleted script as not deleted. The code will not be valid again until after re-submitting it.
- DreamManager Link
- Add a task to DreamManager.
- Syntax Highlighting
- Brings up a dialog allowing the colors used in syntax highlighting to be changed. Syntax Highlighting controls the coloring of the code in the code windows.
- Options
- This dialog allows you to specify a different Merge and Diff application from the default which is set up for use with p4Merge.
HeroEngine has no build-in merge or diff tool leaving you free to choose a favorite if you have one. By default we tend to use P4Merge which is available as a free download from Perforce.com for both merging and diffing needs.
| Program | Merge Application (path may vary) | Arguments |
|---|---|---|
| Araxis Merge | C:\Program Files\Araxis\Araxis Merge\compare.exe | /3 /swap /wait /a1 %1 %2 %3 %4 |
| KDiff3 | C:\Program Files\KDiff3\kdiff3.exe | %1 %2 %3 -o %4 |
| p4merge | C:\Program Files\Perforce\P4merge.exe | %1 %2 %3 %4 |
| WinMerge | C:\Program Files\WinMerge\WinMergeU.exe | %2 %3 %4 |
Also, there are checkboxes to specify preferences regarding the types of scripts that will be shown each time the Open Script dialog is shown.
- Font
- Designate the font to be used in the scripts.
Windows
- Task List
- Toggles a set of tasks or problems to correct on the currently active (tab selected) script. This task list is populated after an attempted compile. The list will show the line and column where the message occurred and the error message associated with it.
- History
- Toggles a window showing the history of the currently active (tab selected) script. This history records all changes made by anyone to this script. Each history entry is recorded with a successful submit.
- Find Results
- Toggles the Find Results window, showing the results of the most recent search.
- Commented
- This checkbox will list only revisions that have comments attached to them. These would normally be when significant changes were made by a scripter.
- Functions and Methods
- See Show Functions and Methods on the Search Menu.
- List of Opened Scripts
- This will list all the opened scripts opened by the script editor
Toolbars
The toolbars give quick access to often used functionality.
File Toolbar
- New
- Quick way to create a new client / server script, or a GUI XML file. (CLI isn’t currently used)
- Open
- Quick way to open a client / server script or XML file
- Save Active Script
- Will save the currently active (tab-selected) script or XML file
- Save All Opened Scripts
- Saves all scripts/files currently opened in the editor.
Edit Toolbar
- Undo
- Undoes an edit
- Redo
- Re-applies the action undone by the last undo.
- Cut / Copy Paste
- does the normal copy, cut and paste operations on the selected text at the cursor location.
- Delete
- Deletes the current selected text.
- Find
- Quick access to the find / replace dialog.
Compile Toolbar
- Compile
- Compiles the currently active (tab-selected) script.
- Submit
- Submits the currently active and successfully compiled script to the server to replace the current latest script on the server (client or server scripts).
- Resolve
- If there’s a conflict after a “submit” with the script already on the server, this will bring up a tool to let you resolve the conflicts.
Bookmark Toolbar
- Add bookmark
- Adds a bookmark
at the line where the cursor is located.
- Next bookmark
- Moves the cursor to the next bookmark on the active (tab selected) script.
- Previous Bookmark
- Moves the cursor to the previous bookmark on the active (tab selected) script.
- Clear bookmark
- Clears the bookmark on the line where the cursor is located.
Script Edit Window
The edit window is where the work is done in creating the script
1: Bookmark 2: If cursor is next to a parenthesis, it will show the matching parenthesis in a grey box. 3: Line Numbers 4: Data Type (String in this case) 5: Keyword 6: Comment 7: Indented structures such as If / Else are connected by a grey vertical line. 8: Text (not a keyword) surrounded by quotes. 9: Clicking on this box will “hide” the section of code between it and its matching closing data structure.
HeroSense
HeroSense is a feature that helps you write HSL code as you type. It does this by offering context-sensitive suggestions, high-lighting syntax errors and showing you the expected arguments to methods and functions. All in real-time.
Here are the key features of HeroSense:
Syntax Errors
As the code is typed, it is parsed in the background and any syntax errors are made visible right when the code is fresh in your mind.
Name Completion
Whenever the script needs the name of a field, script, method, function, etc., the editor provides a list of all of the possible values in a nice unobtrusive notification window. The user can keep typing just using the window as a guide, or they can have the editor do the typing for them. The list automatically selects the first item that matches what has been typed so far, so a simple keystroke (Tab, Enter, or any character that isn't allowed in names) will complete that name.
Besides the list of names, the editor often has additional details that are displayed for the selected item after a brief pause.
In most scenarios, the list just automatically appears. For the cases where it doesn't, there is a special key combination to request completion (Ctrl-Space). If what is there already uniquely identifies the name, it will be inserted immediately; otherwise, the list is displayed as above.
When the editor completes a function or method name, it also goes that extra step and inserts parenthesis for you. It even positions the cursor either between the parenthesis or after them depending on if the function or method takes parameters.
Parameter Tips
Another indispensable feature is the parameter tip. Whenever your calling a function or method, the parameter tip shows the declaration with the current parameter's name in bold. Comment lines immediately before and after the declaration are included (up to 10 lines total).
The parameter tip automatically appears when the open parenthesis is inserted, and goes away when the cursor leaves the parenthesis. The tip can be brought up at any time by pressing Ctrl-Shift-Space with the cursor inside the parenthesis of the call.
History Window
The history window is where you can see the list of revisions.
1: Revision #, latest one first. 2: Name of account which did a successful submit for each revision. 3: Date/Time of the last successful submit 4: Comments related to their revisions. (Note: When the commented checkbox at the top of the History Window is checked, uncommented revisions will not appear on this list.)
Resolving Conflicts: The Merge Tool
What’s a Three Way Merge?
A three-way merge is the merging of three different files into one version. The merge tool here is doing a three-way merge. The top-left window is the server side’s latest version (the version you want to overwrite). The upper-right window is a view of the script you submitted. The bottom window shows the resolution of the conflicts between them.
The three files being merged are the current server side script version, and your two local versions of the same script file. Your two local versions are (1) the original version you had as of your last successful compile/submit; and (2) the file with the current edits (the script you want to become the current version).
Walking through a resolve
The scenario: There’s a problem with a script that needs fixing right away. You open the offending script and prepare to fix it. You notice that the problem is the function “testFunc()” is returning an Integer. You realize it must return a Boolean.
Unfortunately another equally dutiful GM (Sir Speedy), has already grabbed the same script, edited it and submitted a new version of the script. However, their fix is different from yours. Not knowing Sir Speedy was also fixing the problem, you compile and submit your code. To your horror, you see the following error in the status bar…
No worries, you just press the “Resolve” button. This shows:
- Code on both sides which shows no conflicts (not colored).
- Code that the merge tool is 100% sure must be deleted (green).
- Code that the merge tool is 100% certain must be deleted but where the code on both sides is not exactly the same. This means there’s a potential that this particular merge might be incorrect. You should look at the way it resolved this after all conflicts have been resolved.
- An un-resolvable merge (red). Merging this is beyond the merge tool’s ability to decide on a reasonable merge, and requires a human to make a decision.
- A popup menu where you can change how the merge tool has decided to merge the code. In this case, it’s being brought up so you can resolve the “un-resolvable” conflict. In this case, the choice is "Yours," which means that the person doing the merge (you) has decided the correct resolution to the conflict will be the “Your” code and not the “Theirs.”
After the merge is done
- The purple shows differences that have not become part of the final merge.
- The blue shows the code that’s become part of the final merge
- The grey shows where code (in this case it was blank lines with a space in them) was deleted and neither the “Theirs” version nor the “Yours” version was used.
