Script Editor – Arma Reforger

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Add some images)
(added pictures & links + tweaked some fragments)
Line 5: Line 5:
It also provides many tools and utilities for improved efficiency like '''syntax highlighting''', script '''auto-completion''', fast script '''validation''' and numerous different methods of '''searching''' files, scripts and '''symbols''' within the project.
It also provides many tools and utilities for improved efficiency like '''syntax highlighting''', script '''auto-completion''', fast script '''validation''' and numerous different methods of '''searching''' files, scripts and '''symbols''' within the project.


For a Script Editor newcomer's quickstart see the '''Getting Started''' section.
For a Script Editor newcomer's quickstart see the [[#Getting_Started|'''Getting Started''']] section.


To learn more about the features of the Script Editor, see '''Script Editor Features'''.
To learn more about the features of the Script Editor, see [[#Script_Editor_Features|'''Script Editor Features''']].




Line 16: Line 16:
There are numerous ways of searching through the code, namely '''Find File''', '''Text Search''' or '''Find Symbol''' in addition to the '''Outline''', '''Find In Entire Solution''' and '''Goto Declaration''' functionalities.
There are numerous ways of searching through the code, namely '''Find File''', '''Text Search''' or '''Find Symbol''' in addition to the '''Outline''', '''Find In Entire Solution''' and '''Goto Declaration''' functionalities.


To learn more about navigating the Script Editor and the codebase, see '''Navigate and find code'''. To learn more about script syntax error checking and validation, see '''Compilation and Errors'''.
To learn more about navigating the Script Editor and the codebase, see [[#Navigate_and_Find_Code|'''Navigate and find code''']]. To learn more about script syntax error checking and validation, see [[#Compilation_and_Errors|'''Compilation and Errors''']].


Run-time Debugging features include - but are not limited to - the '''Debugger''', '''Breakpoints''', '''Callstack''' and '''Watch'''. For more information regarding debugging, see '''Debugging'''.
Run-time Debugging features include - but are not limited to - the '''Debugger''', '''Breakpoints''', '''Callstack''' and '''Watch'''. For more information regarding debugging, see [[#Debugging|'''Debugging''']].


=== Editor Features ===
=== Editor Features ===


{| class="wikitable"
{| class="wikitable"
!Feature
!Description
|-
| Syntax Highlighting
| Syntax Highlighting
| Highlighting of language specific keywords, functions and matching braces.
| Highlighting of language specific keywords, functions and matching braces.
|-
|-
| Auto Complete
| Auto Complete
| Auto-completion/suggestion of code via known symbols. See '''Auto Complete'''.
| Auto-completion/suggestion of code via known symbols. See [[#Auto_Complete|'''Auto Complete''']].
|-
|-
| Script Validation and Error Checking
| Script Validation and Error Checking
| Syntax checking, for more information see '''Compilation and Errors.'''
| Syntax checking, for more information see [[#Compilation_and_Errors|'''Compilation and Errors.''']]
|-
|-
| Searching
| Searching
| Full-text search, symbol search, search for files and more. See '''Searching'''.
| Full-text search, symbol search, search for files and more. See [[#Searching|'''Searching''']].
|-
|-
| Line Numbers
| Line Numbers
| Script file line numbers display in the '''Text Editor'''.
| Script file line numbers display in the [[#Text_Editor|'''Text Editor''']].
|-
|-
| Debugger
| Debugger
| Code can be debugged step by step via the usage of the debugger. See '''Debugging'''.
| Code can be debugged step by step via the usage of the debugger. See [[#Debugging|'''Debugging''']].
|-
|-
| Undo and Redo
| Undo and Redo
Line 47: Line 50:
=== Navigate and Find Code ===
=== Navigate and Find Code ===


Moving around in the code can be done in several different ways, including navigating backwards and forwards to the last insertion points. Navigation can also be done ''via'' '''Goto Declaration'''.
Moving around in the code can be done in several different ways, including navigating backwards and forwards to the last insertion points. Navigation can also be done ''via'' [[#Goto_Declaration|'''Goto Declaration''']].


Search for and replace text in single or multiple files can be done using the '''Find in Files'''.
Search for and replace text in single or multiple files can be done using the [[#Find_in_Files|'''Find in Files''']].


{{Feature|informative|
{{Feature|informative|
For more information regarding code navigation, see '''Navigation'''.<br>
For more information regarding code navigation, see [[#Navigation|'''Navigation''']].<br>
For more information regarding searching, see '''Searching'''.
For more information regarding searching, see [[#Searching|'''Searching''']].
}}
}}


Line 59: Line 62:


The layout of the Script Editor is composed from many different windows and panels. They can be resizes, undocked from their position or docked to a preference.
The layout of the Script Editor is composed from many different windows and panels. They can be resizes, undocked from their position or docked to a preference.
To learn more refer to '''Script Editor Windows'''.
To learn more refer to [[#Script_Editor_Windows|'''Script Editor Windows''']].
In addition, the Script Editor can also be customized to a certain degree by changing the font and font size it uses by default - find more information in '''Preferences'''.  
In addition, the Script Editor can also be customized to a certain degree by changing the font and font size it uses by default - find more information in [[#Preferences|'''Preferences''']].  


=== Editor Shortcuts ===
=== Editor Shortcuts ===


Opposed to finding particular options from within the Editor windows manually, there is also the option to use some of (or all of) the available keyboard shortcuts - learning to use them might drastically improve the speed and efficiency of the workflow.
Opposed to finding particular options from within the Editor windows manually, there is also the option to use some of (or all of) the available keyboard shortcuts - learning to use them might drastically improve the speed and efficiency of the workflow.
For more information about keyboard shortcuts, see '''Keyboard Shortcuts'''.
For more information about keyboard shortcuts, see [[#Keyboard_Shortcuts|'''Keyboard Shortcuts''']].




Line 71: Line 74:


In this quick introduction to the Script Editor we'll take a tour of some of the windows, tools and other features.
In this quick introduction to the Script Editor we'll take a tour of some of the windows, tools and other features.
For a more in-depth look at features of the Script Editor see '''Script Editor Features'''.
For a more in-depth look at features of the Script Editor see [[#Script_Editor_Features|'''Script Editor Features''']].


=== Opening Workbench ===
=== Opening Workbench ===
Line 77: Line 80:
The Script Editor can be opened from the main ''Enfusion Workbench window'' at any time. There can only be one instance of the Script Editor running, but it can be opened and closed at free will.
The Script Editor can be opened from the main ''Enfusion Workbench window'' at any time. There can only be one instance of the Script Editor running, but it can be opened and closed at free will.


The Script Editor can be opened from the '''''Workbench menu bar (1)''''' by selecting the '''''Script Editor''''' '''''(2)''''' option in the '''Editors''' drop-down menu, or by clicking the '''Script Editor''' button in the Resource Manager's welcome page.
The Script Editor can be opened from the '''''Workbench menu bar (1)''''' by selecting the '''''Script Editor''''' '''''(2)''''' option in the '''Editors''' drop-down menu, or by clicking the '''Script Editor''' button '''''(3)''''' in the Resource Manager's welcome page.
 
[[File:armareforger-scripteditor-launch.jpg|800px]]


=== Default Layout ===
=== Default Layout ===
Line 85: Line 90:
In order to learn more about individual windows, please refer to individual pages. For information about working with the windows in general, see '''Script Editor Windows'''.
In order to learn more about individual windows, please refer to individual pages. For information about working with the windows in general, see '''Script Editor Windows'''.


# '''Menu Bar'''
# [[#Menu_Bar|'''Menu Bar''']]
# '''Debug'''  
# [[#Debug|'''Debug''' ]]
# '''Outline''' and '''Projects'''
# [[#Outline|'''Outline''']] and [[#Projects|'''Projects''']]
# '''Watch''', '''Errors''' and '''Find Results'''
# [[#Watch|'''Watch''']], [[#Errors|'''Errors''']] and [[#Find_Results|'''Find Results''']]
# '''Callstack''', '''Breakpoints''' and '''Output'''
# [[#Callstack|'''Callstack''']], [[#Breakpoints|'''Breakpoints''']] and [[#Output|'''Output''']]
# '''Console''' and '''Find in Files'''
# [[#Console|'''Console''']] and [[#Find_in_Files|'''Find in Files''']]
# '''Find Entity''', '''Find Symbol''', '''Find File''' and '''Bookmarks'''
# [[#Find_Entity|'''Find Entity''']], [[#Find_Symbol|'''Find Symbol''']], [[#Find_File|'''Find File''']] and [[#Bookmarks|'''Bookmarks''']]
# '''Text Editor'''
# [[#Text_Editor|'''Text Editor''']]


[[File:armareforger-scripteditor_layout.png|800px]]
[[File:armareforger-scripteditor_layout.png|800px]]
Line 98: Line 103:
=== Compilation and Errors ===
=== Compilation and Errors ===


For error management, see '''Debugging'''.
For error management, see [[#Debugging|'''Debugging''']].


Let's start by creating and validating our first script.
Let's start by creating and validating our first script.


Navigate to the '''''Projects (1)''''' window and open (or create and open) the '''''selected file (2)'''''.
Navigate to the '''''Projects (1)''''' window and open (or create and open) the '''''selected file (2)'''''.
[[File:armareforger-scripteditor_helloworld_00_openfile.png|800px]]


Write the wanted code ''via'' the '''''Text Editor (1).''''' In our case we have a '''''class Welcomer''''' that provides us with a void method '''''SayHello'''''.
Write the wanted code ''via'' the '''''Text Editor (1).''''' In our case we have a '''''class Welcomer''''' that provides us with a void method '''''SayHello'''''.


Pay close attention to the syntax '''''error on line 11 (2)'''.'' We are missing a closing bracket and a semicolon at the end of the line.
Pay close attention to the syntax '''''error on line 11 (2)'''.'' We are missing a closing bracket and a semicolon at the end of the line.
[[File:armareforger-scripteditor_helloworld_01_scripterror.png|800px]]


Use the '''Menu Bar''' to access the '''''Validate Scripts (2)''''' option in the '''Build''' tab.
Use the '''Menu Bar''' to access the '''''Validate Scripts (2)''''' option in the '''Build''' tab.
[[File:armareforger-scripteditor_helloworld_02_validate.png|800px]]


==== Errors ====
==== Errors ====
Line 115: Line 126:
'''Double Click''' {{Controls|LMB2}} on any error to navigate to its location in the '''Text Editor'''.
'''Double Click''' {{Controls|LMB2}} on any error to navigate to its location in the '''Text Editor'''.


After fixing errors and validating the scripts once again, no problems are found. The '''''Output (1)''''' window then shows that the compilation finished successfully''.''
[[File:armareforger-scripteditor_helloworld_03_errors.png|800px]]
 
After fixing errors and validating the scripts once again, no problems are found. The [[#Output|'''''Output (1)''''']] window then shows that the compilation finished successfully''.''


[[File:armareforger-scripteditor_helloworld_04_success.png|800px]]


= Preferences =
= Preferences =


The Script Editor can see some settings adjusted like the font family type and the font size in the Script Editor tab of the '''Workbench Options'''.
The Script Editor can see some settings adjusted like the font family type and the font size in the Script Editor tab of the [[Arma_Reforger:Resource_Manager:_Options#Font_Family|'''Workbench Options''']].


The '''''Workbench menu bar (1)''''' in the main Resource Manager window allows access to the options by selecting the '''''Workbench''' &rarr; '''Options (2)''''' entry in the '''Workbench''' drop down menu.
The '''''Workbench menu bar (1)''''' in the main [[Arma_Reforger:Resource_Manager|Resource Manager]] window allows access to the options by selecting the '''''Workbench''' &rarr; '''Options (2)''''' entry in the '''Workbench''' drop down menu.
 
[[File:armareforger-scripteditor_wb_options.png|800px]]


The settings can then be personalized in the '''''Options (1)''''' window by editing the properties available in the '''''Script Editor (2)''''' tab.  
The settings can then be personalized in the '''''Options (1)''''' window by editing the properties available in the '''''Script Editor (2)''''' tab.  


[[File:armareforger-scripteditor_wb_options_window.png|800px]]


= Navigation =
= Navigation =


== General ==
== General ==
Line 143: Line 159:
* '''Bookmarks''' &rarr; ''Provides bookmark options like'' '''Toggle Bookmark''' ''or'' '''Next Bookmark'''
* '''Bookmarks''' &rarr; ''Provides bookmark options like'' '''Toggle Bookmark''' ''or'' '''Next Bookmark'''
* '''Plugins''' &rarr; ''Provides and general and individual'' '''(options per plugin)'''
* '''Plugins''' &rarr; ''Provides and general and individual'' '''(options per plugin)'''
[[File:armareforger-scripteditor_main_panel.png|800px]]


=== Script Editor Windows ===
=== Script Editor Windows ===
Line 152: Line 170:
A window can always be closed by using '''''Click  '''''on the  icon in the window title bar.
A window can always be closed by using '''''Click  '''''on the  icon in the window title bar.
If the window needs to be re-opened, it can be done so ''via'' the '''''Menu Bar''' &rarr; '''Windows (1)''''' option.
If the window needs to be re-opened, it can be done so ''via'' the '''''Menu Bar''' &rarr; '''Windows (1)''''' option.
[[File:armareforger-scripteditor_windows_tab.png|800px]]


==== Docking and Undocking ====
==== Docking and Undocking ====
Line 158: Line 178:
To dock a window into a different position, keep dragging the '''windows title''' by holding the '''''Left Mouse Button  '''''.
To dock a window into a different position, keep dragging the '''windows title''' by holding the '''''Left Mouse Button  '''''.
Valid positions where the window can be docked will be visualized by the '''highlighted area.''' Release the '''''Left Mouse Button  ''''' and the window will dock itself.
Valid positions where the window can be docked will be visualized by the '''highlighted area.''' Release the '''''Left Mouse Button  ''''' and the window will dock itself.
[[File:armareforger-scripteditor_wb_windows_docking.gif|800px]]


=== Projects ===
=== Projects ===
Line 171: Line 193:


'''''Double Click  '''''on a selected Script File to open it in the '''Text Editor'''.
'''''Double Click  '''''on a selected Script File to open it in the '''Text Editor'''.
[[File:armareforger-scripteditor_outline_navigation.png|800px]]


==== Icons ====
==== Icons ====
Line 176: Line 200:


{| class="wikitable"
{| class="wikitable"
!Icon
!Description
|-
|
|
| Project
| Project
Line 194: Line 221:


'''''Right Click  '''''on any of the open tabs to expand a contextual menu that will provide additional options such as closing multiple files.
'''''Right Click  '''''on any of the open tabs to expand a contextual menu that will provide additional options such as closing multiple files.
[[File:armareforger-scripteditor_texteditor_navigation.png|800px]]


Files may be marked as '''read-only'''. Such script files can still be opened and read freely, but cannot be modified and saved. An example of such files may be core game data.
Files may be marked as '''read-only'''. Such script files can still be opened and read freely, but cannot be modified and saved. An example of such files may be core game data.
[[File:armareforger-scripteditor_readonly_file.png|800px]]


==== Icons ====
==== Icons ====
Line 202: Line 233:


{| class="wikitable"
{| class="wikitable"
!Icon
!Description
! colspan="1" |Information
|-
|
|
| Script Error
| Script Error
Line 236: Line 271:
Its dialog can browsed through using the '''Up''' and '''Down''' arrows, confirming selection using '''Enter''' or simply by using mouse '''Click  '''on the desired option.
Its dialog can browsed through using the '''Up''' and '''Down''' arrows, confirming selection using '''Enter''' or simply by using mouse '''Click  '''on the desired option.
The '''''Auto Completion Dialog (1) can''''' reappear by using the '''Left Control + Spacebar''' ( '''+''' ) key combination.
The '''''Auto Completion Dialog (1) can''''' reappear by using the '''Left Control + Spacebar''' ( '''+''' ) key combination.
[[File:armareforger-scripteditor_autocompletion.png|800px]]


=== Bookmarks ===
=== Bookmarks ===
Line 250: Line 287:


'''''Click'''''  on any of the symbols in the '''''Outline (1)''''' window to quickly navigate to them in the '''Text Editor'''.
'''''Click'''''  on any of the symbols in the '''''Outline (1)''''' window to quickly navigate to them in the '''Text Editor'''.
[[File:armareforger-scripteditor_outline.png|800px]]


=== Output ===
=== Output ===
Line 256: Line 295:
All scripts can send diagnostic or other messages to the '''Output''' window via the '''''Print''''' method. In addition text can be selected and copied at will.
All scripts can send diagnostic or other messages to the '''Output''' window via the '''''Print''''' method. In addition text can be selected and copied at will.


[[File:armareforger-scripteditor_output.png|800px]]


== Searching ==
== Searching ==
Line 264: Line 304:


Use '''Find File''' to find a script file by name. To search for text in files, refer to '''Find in Files''' instead'''.'''
Use '''Find File''' to find a script file by name. To search for text in files, refer to '''Find in Files''' instead'''.'''
[[File:armareforger-scripteditor_findfile_navigation.png|800px]]


To search for a file start by typing into the '''''search bar (1)'''''. The results are visible in the '''''search results (2)'''''.
To search for a file start by typing into the '''''search bar (1)'''''. The results are visible in the '''''search results (2)'''''.


'''''Double Click''''' ''' '''on any of the files in the '''''search results (2)''''' to open and navigate to them in the '''Text Editor'''.
'''''Double Click''''' ''' '''on any of the files in the '''''search results (2)''''' to open and navigate to them in the '''Text Editor'''.
[[File:armareforger-scripteditor_findfile.png|800px]]


=== Find Symbol ===
=== Find Symbol ===


Use the '''Find Symbol''' to find a particular symbol located within any of the script files. To search for text in files, refer to '''Find in Files''' instead'''.'''
Use the '''Find Symbol''' to find a particular symbol located within any of the script files. To search for text in files, refer to '''Find in Files''' instead'''.'''
[[File:armareforger-scripteditor_findsymbol_navigation.png|800px]]


To search for a symbol, type into the '''''search bar (1)'''''. The results are visible in the '''''search results (2)'''.''
To search for a symbol, type into the '''''search bar (1)'''''. The results are visible in the '''''search results (2)'''.''


'''''Double Click'''''  on any of the symbols in the '''''search results (2)''''' to open and navigate to them in the '''Text Editor'''.
'''''Double Click'''''  on any of the symbols in the '''''search results (2)''''' to open and navigate to them in the [[#Text_Editor|'''Text Editor''']].
 
[[File:armareforger-scripteditor_findsymbol.png|800px]]


=== Find in Files ===
=== Find in Files ===


Use '''Find in Files''' to search for a text match within any of the script files. To search for symbols, refer to '''Find Symbol''' instead.
Use '''Find in Files''' to search for a text match within any of the script files. To search for symbols, refer to '''Find Symbol''' instead.
For the search results of the Text Search window see '''Find Results'''.
For the search results of the Text Search window see [[#Find_Results|'''Find Results''']].
 
[[File:armareforger-scripteditor_search_fulltext_navigation.png|800px]]


Type into the '''''search bar (1). Click  '''''on the '''''Find All (2)''''' button to search. This should open the '''''Find Results (3)''''' window with results.
Type into the '''''search bar (1). Click  '''''on the '''''Find All (2)''''' button to search. This should open the '''''Find Results (3)''''' window with results.


'''''Click  '''''on any of the found results visible in the '''''Find Results (3)''''' window to open and navigate to them in the '''Text Editor'''.
'''''Click  '''''on any of the found results visible in the '''''Find Results (3)''''' window to open and navigate to them in the '''Text Editor'''.
[[File:armareforger-scripteditor_search_fulltext.png|800px]]


=== Goto Declaration ===
=== Goto Declaration ===
Line 295: Line 347:


In addition, use '''Left Control  + Click  '''key combination on desired symbol to navigate to the Declaration.
In addition, use '''Left Control  + Click  '''key combination on desired symbol to navigate to the Declaration.
[[File:armareforger-scripteditor_goto_declaration.png|800px]]


=== Find in Entire Solution ===
=== Find in Entire Solution ===
Line 304: Line 358:
'''''Click  '''''on the '''''Find In Entire Solution (2)''''' option in the contextual menu. This will perform a project-wide search.
'''''Click  '''''on the '''''Find In Entire Solution (2)''''' option in the contextual menu. This will perform a project-wide search.
For more information regarding searching and finding results, see '''Find Results'''.
For more information regarding searching and finding results, see '''Find Results'''.
[[File:armareforger-scripteditor_findallreferences.png|800px]]


=== Find Results ===
=== Find Results ===
Line 310: Line 366:


'''''Double''''' '''Click  '''on any of the entries within the '''''Find Results (1)''''' window to navigate to them and open them in the '''Text Editor'''.
'''''Double''''' '''Click  '''on any of the entries within the '''''Find Results (1)''''' window to navigate to them and open them in the '''Text Editor'''.
[[File:armareforger-scripteditor_findresults.png|800px]]


=== Find Entity ===
=== Find Entity ===
Line 321: Line 379:
'''''Double''''' '''Click  '''on any of the entries within the '''''Find Entity (1)''''' window to navigate to them and open them in the '''Text Editor'''.
'''''Double''''' '''Click  '''on any of the entries within the '''''Find Entity (1)''''' window to navigate to them and open them in the '''Text Editor'''.


[[File:armareforger-scripteditor_findentity.png|800px]]


== Keyboard Shortcuts ==
== Keyboard Shortcuts ==
Line 327: Line 386:


{| class="wikitable"
{| class="wikitable"
!Shortcut
!Function
|-
| {{Controls|Ctrl|S}}
| {{Controls|Ctrl|S}}
| Save All
| Save All
Line 443: Line 505:


Breakpoints are invalidated if placed in code that does not match the current code run by the connected game.
Breakpoints are invalidated if placed in code that does not match the current code run by the connected game.
[[File:armareforger-scripteditor_debugging_breakpoint.png|800px]]


After placing a breakpoint in our code, let's run the game. With an assumption that the code will be executed, we should see theicon pop up over the first encountered breakpoint.
After placing a breakpoint in our code, let's run the game. With an assumption that the code will be executed, we should see theicon pop up over the first encountered breakpoint.


The  icon shows the current execution step, as seen on the '''''current line (1)'''.'' The '''''Debug (2)''''' window can then be used to go through the code execution step by step.
The  icon shows the current execution step, as seen on the '''''current line (1)'''.'' The '''''Debug (2)''''' window can then be used to go through the code execution step by step.
[[File:armareforger-scripteditor_debugging_breakpoint_hit_debugger.png|800px]]


=== Debug ===
=== Debug ===
Line 457: Line 523:
* '''Step Out:''' Advance the debugger until the current function returns.
* '''Step Out:''' Advance the debugger until the current function returns.
* '''Stop:''' Stop the playmode and current debugging session.  
* '''Stop:''' Stop the playmode and current debugging session.  
[[File:armareforger-scripteditor_debugger_descriptors.png|800px]]


Hovering the mouse cursor over a variable displays its current value, in the addition to '''Watch''' usage, explained below.
Hovering the mouse cursor over a variable displays its current value, in the addition to '''Watch''' usage, explained below.
[[File:armareforger-scripteditor_debugging_steps.gif|800px]]


=== Connecting the debugger ===
=== Connecting the debugger ===
Line 464: Line 534:
Opening the Script Editor while the game is running automatically attaches the debugger ''via'' the default port, displaying the following '''''pop up message (1)'''''.
Opening the Script Editor while the game is running automatically attaches the debugger ''via'' the default port, displaying the following '''''pop up message (1)'''''.


In addition, a debugger can be connected to a different port ''via'' the '''Debug''' options from the '''Menu Bar'''.
[[File:armareforger-scripteditor_debugging_connectedpopup.png|800px]]
 
In addition, a debugger can be connected to a different port ''via'' the '''Debug''' options from the [[#Menu_Bar|'''Menu Bar''']].


One particularly interesting option is the '''Debug &rarr; Debug Custom''', which allows us to connect to a user provided port.
One particularly interesting option is the '''Debug &rarr; Debug Custom''', which allows us to connect to a user provided port.


Selecting the '''Debug &rarr; Debug Custom''' will make the following '''''window (1)''''' appear in which the debugger's port can be set.
Selecting the '''Debug &rarr; Debug Custom''' will make the following '''''window (1)''''' appear in which the debugger's port can be set.
[[File:armareforger-scripteditor_debugging_customport.png|800px]]


To launch the Enfusion Workbench or the game itself on a specific port, use the '''-debuggerPort''' command line argument.
To launch the Enfusion Workbench or the game itself on a specific port, use the '''-debuggerPort''' command line argument.
Line 474: Line 548:
In the following image, the '''''Properties (1)''''' of a Workbench shortcut is set to port 1234 via the argument '''-debuggerPort 1234''' as seen in the '''''Target (2)''''' field.
In the following image, the '''''Properties (1)''''' of a Workbench shortcut is set to port 1234 via the argument '''-debuggerPort 1234''' as seen in the '''''Target (2)''''' field.


[[File:armareforger-scripteditor_windows_properties_scriptdebugger_port.png]]
[[File:armareforger-scripteditor_windows_properties_scriptdebugger_port.png|800px]]


=== Watch ===
=== Watch ===


The '''Watch''' feature can be used to learn about how code changes in run-time. This allows the user to see the current values of variables while navigating through the code via the debugger.
The '''Watch''' feature can be used to learn about how code changes in run-time. This allows the user to see the current values of variables while navigating through the code via the debugger.
[[File:armareforger-scripteditor_debugger_watch.png|800px]]


=== Callstack ===
=== Callstack ===
Line 485: Line 561:


It must be read from the bottom up. In this case, the depicted call originated in: '''MyComponent:EOnInit &rarr;'''  '''MyComponent::DoWelcome &rarr; Welcomer::SayHello'''.
It must be read from the bottom up. In this case, the depicted call originated in: '''MyComponent:EOnInit &rarr;'''  '''MyComponent::DoWelcome &rarr; Welcomer::SayHello'''.
[[File:armareforger-scripteditor_debugger_callstack.png|800px]]


=== Console ===
=== Console ===
Line 490: Line 568:
In addition to the '''Callstack''' and '''Breakpoints''', the '''Console''' is of great debugging assistance.
In addition to the '''Callstack''' and '''Breakpoints''', the '''Console''' is of great debugging assistance.
The '''Console''' can be used in '''run-time''' to execute user scripts within the current stack.
The '''Console''' can be used in '''run-time''' to execute user scripts within the current stack.
[[File:armareforger-scripteditor_console.png|800px]]


Being in playmode is mandatory to use the console. Code which will be global to the current file can then be run.
Being in playmode is mandatory to use the console. Code which will be global to the current file can then be run.
The console can also be used when a breakpoint is hit while debugging and the run code will be local to the current instance.
The console can also be used when a breakpoint is hit while debugging and the run code will be local to the current instance.
For more information regarding breakpoints see '''Breakpoints'''.
For more information regarding breakpoints see [[#Breakpoints|'''Breakpoints''']].


Write code into the console and press the '''''Run (1)''''' button. Local variables can be used; for more information see '''Watch'''.
Write code into the console and press the '''''Run (1)''''' button. Local variables can be used; for more information see '''Watch'''.


Results will be visible in the '''''Output (2)''''' window.
Results will be visible in the [[#Output|'''''Output (2)''''']] window.
 
[[File:armareforger-scripteditor_console_run.png|800px]]


=== Virtual Machine Exceptions ===
=== Virtual Machine Exceptions ===
Line 505: Line 587:
Press '''Stop''' to halt the code execution immediately, ignore single or all cases ''via'' '''Ignore''' and '''Ignore All''', or navigate straight to the problem using the '''Debug''' button.
Press '''Stop''' to halt the code execution immediately, ignore single or all cases ''via'' '''Ignore''' and '''Ignore All''', or navigate straight to the problem using the '''Debug''' button.


[[File:armareforger-scripteditor_debugging_virtualmachineexception.gif|800px]]


{{GameCategory|armaR|Modding|Official Tools}}
{{GameCategory|armaR|Modding|Official Tools}}

Revision as of 14:20, 22 June 2022

Welcome to the Enfusion Script Editor!

The Script Editor is a text editor module with integrated debugger, available from within the Enfusion Workbench that allows the user to edit, manage and debug scripts. It also provides many tools and utilities for improved efficiency like syntax highlighting, script auto-completion, fast script validation and numerous different methods of searching files, scripts and symbols within the project.

For a Script Editor newcomer's quickstart see the Getting Started section.

To learn more about the features of the Script Editor, see Script Editor Features.


Script Editor Features

The Script Editor provides many features that make writing and managing code easier.

There are numerous ways of searching through the code, namely Find File, Text Search or Find Symbol in addition to the Outline, Find In Entire Solution and Goto Declaration functionalities.

To learn more about navigating the Script Editor and the codebase, see Navigate and find code. To learn more about script syntax error checking and validation, see Compilation and Errors.

Run-time Debugging features include - but are not limited to - the Debugger, Breakpoints, Callstack and Watch. For more information regarding debugging, see Debugging.

Editor Features

Feature Description
Syntax Highlighting Highlighting of language specific keywords, functions and matching braces.
Auto Complete Auto-completion/suggestion of code via known symbols. See Auto Complete.
Script Validation and Error Checking Syntax checking, for more information see Compilation and Errors.
Searching Full-text search, symbol search, search for files and more. See Searching.
Line Numbers Script file line numbers display in the Text Editor.
Debugger Code can be debugged step by step via the usage of the debugger. See Debugging.
Undo and Redo Changes made by the user can be undone and redone at will.

Navigate and Find Code

Moving around in the code can be done in several different ways, including navigating backwards and forwards to the last insertion points. Navigation can also be done via Goto Declaration.

Search for and replace text in single or multiple files can be done using the Find in Files.

ⓘ
For more information regarding code navigation, see Navigation.
For more information regarding searching, see Searching.

Editor Personalization

The layout of the Script Editor is composed from many different windows and panels. They can be resizes, undocked from their position or docked to a preference. To learn more refer to Script Editor Windows. In addition, the Script Editor can also be customized to a certain degree by changing the font and font size it uses by default - find more information in Preferences.

Editor Shortcuts

Opposed to finding particular options from within the Editor windows manually, there is also the option to use some of (or all of) the available keyboard shortcuts - learning to use them might drastically improve the speed and efficiency of the workflow. For more information about keyboard shortcuts, see Keyboard Shortcuts.


Getting Started

In this quick introduction to the Script Editor we'll take a tour of some of the windows, tools and other features. For a more in-depth look at features of the Script Editor see Script Editor Features.

Opening Workbench

The Script Editor can be opened from the main Enfusion Workbench window at any time. There can only be one instance of the Script Editor running, but it can be opened and closed at free will.

The Script Editor can be opened from the Workbench menu bar (1) by selecting the Script Editor (2) option in the Editors drop-down menu, or by clicking the Script Editor button (3) in the Resource Manager's welcome page.

armareforger-scripteditor-launch.jpg

Default Layout

The default (initial) layout of the Script Editor is composed of the following windows and panels, listed in counter clockwise order as seen on the image below.

In order to learn more about individual windows, please refer to individual pages. For information about working with the windows in general, see Script Editor Windows.

  1. Menu Bar
  2. Debug
  3. Outline and Projects
  4. Watch, Errors and Find Results
  5. Callstack, Breakpoints and Output
  6. Console and Find in Files
  7. Find Entity, Find Symbol, Find File and Bookmarks
  8. Text Editor

armareforger-scripteditor layout.png

Compilation and Errors

For error management, see Debugging.

Let's start by creating and validating our first script.

Navigate to the Projects (1) window and open (or create and open) the selected file (2).

armareforger-scripteditor helloworld 00 openfile.png

Write the wanted code via the Text Editor (1). In our case we have a class Welcomer that provides us with a void method SayHello.

Pay close attention to the syntax error on line 11 (2). We are missing a closing bracket and a semicolon at the end of the line.

armareforger-scripteditor helloworld 01 scripterror.png

Use the Menu Bar to access the Validate Scripts (2) option in the Build tab.

armareforger-scripteditor helloworld 02 validate.png

Errors

The script validation has resulted in multiple errors that can be seen in the Errors (1) window of the Script Editor.

Double Click Double Left Mouse Button on any error to navigate to its location in the Text Editor.

armareforger-scripteditor helloworld 03 errors.png

After fixing errors and validating the scripts once again, no problems are found. The Output (1) window then shows that the compilation finished successfully.

armareforger-scripteditor helloworld 04 success.png

Preferences

The Script Editor can see some settings adjusted like the font family type and the font size in the Script Editor tab of the Workbench Options.

The Workbench menu bar (1) in the main Resource Manager window allows access to the options by selecting the Workbench → Options (2) entry in the Workbench drop down menu.

armareforger-scripteditor wb options.png

The settings can then be personalized in the Options (1) window by editing the properties available in the Script Editor (2) tab.

armareforger-scripteditor wb options window.png

Navigation

General

Menu Bar

The menu bar allows access to some of the most sought after features of the Script Editor. The main tabs are:

  • File → Provides options of working with files like Save All
  • Edit → Provides editing options like Jump To Line, Navigate Back or Duplicate Line
  • Build → Provides build options like Validate Scripts or Compile and Reload Scripts
  • Debug → Provides debugging options like Debug Client, or Insert Breakpoint
  • Windows → Provides the option to open windows like the Projects, Outline or Callstack
  • Bookmarks → Provides bookmark options like Toggle Bookmark or Next Bookmark
  • Plugins → Provides and general and individual (options per plugin)

armareforger-scripteditor main panel.png

Script Editor Windows

Opening and Closing

The Script Editor works with windows which all contribute to the layout of the editor. Windows can be opened and closed by the user at any given time and moved or docked to a certain position within the editor.

A window can always be closed by using Click on the icon in the window title bar. If the window needs to be re-opened, it can be done so via the Menu Bar → Windows (1) option.

armareforger-scripteditor windows tab.png

Docking and Undocking

To undock a window from its position, either Click on the button or hover the mouse cursor over the window title bar and hold the Left Mouse Button while dragging the window out.

To dock a window into a different position, keep dragging the windows title by holding the Left Mouse Button . Valid positions where the window can be docked will be visualized by the highlighted area. Release the Left Mouse Button and the window will dock itself.

armareforger-scripteditor wb windows docking.gif

Projects

Summary

A project is a collection of code files that exists within a particular module.

To search for files, use the Search (1) panel that can be found within the Projects (2) window.

Left-click to select any entry from the projects window.

Right-Click on any entry to expand a contextual menu (3) that will provide additional options like removal or navigation to file via Explorer.

Double Click on a selected Script File to open it in the Text Editor.

armareforger-scripteditor outline navigation.png

Icons

All entries visible within the Projects browser use a specific icon representing their type:

Icon Description
Project
Directory
Script File

Text Editor

Summary

The text editor (1) will allow us to navigate through script files and edit them as desired. The navigation bar (2) can be used to switch between open script files.

Click on any of the open tabs to select them as active or on the icon to close an open tab. Additionally use the Scroll Wheel to cycle between open tabs.

Right Click on any of the open tabs to expand a contextual menu that will provide additional options such as closing multiple files.

armareforger-scripteditor texteditor navigation.png

Files may be marked as read-only. Such script files can still be opened and read freely, but cannot be modified and saved. An example of such files may be core game data.

armareforger-scripteditor readonly file.png

Icons

The following icons may appear during Text Editor usage:

Icon Description Information
Script Error The script will not compile.
Script Warning The script will compile, but might yield unexpected results.
Breakpoint (enabled) User-placed breakpoint in an enabled state.
Breakpoint (disabled) User-placed breakpoint in a disabled state.
Breakpoint (invalid) User-placed breakpoint that was invalidated.
Breakpoint Trigger Arrow Current execution step in the debugger.
Bookmark User-placed bookmark.

Auto Complete

The Script Editor can help fill in code through symbols suggestion with its Auto Completion feature. Simply start writing any code and the Auto Completion Dialog (1) will appear.

Its dialog can browsed through using the Up and Down arrows, confirming selection using Enter or simply by using mouse Click on the desired option. The Auto Completion Dialog (1) can reappear by using the Left Control + Spacebar ( + ) key combination.

armareforger-scripteditor autocompletion.png

Bookmarks

Right Click right next to the Line Number (1) panel in the Text Editor to place or remove a bookmark in code. Placed bookmarks will be visible in the Bookmarks (2) window.

Double Click on any bookmark from within the Bookmarks (2) window to quickly navigate to its location.

Outline

Summary

Outline can be used to see and navigate through symbols (i.e. variables, methods, classes etc.) in the currently open document. To search for symbols in the whole solution, use Find Symbol.

Click on any of the symbols in the Outline (1) window to quickly navigate to them in the Text Editor.

armareforger-scripteditor outline.png

Output

The Output window is especially useful while debugging. All scripts can send diagnostic or other messages to the Output window via the Print method. In addition text can be selected and copied at will.

armareforger-scripteditor output.png

Searching

The Script Editor also provides numerous ways of searching through the codebase.

Find File

Use Find File to find a script file by name. To search for text in files, refer to Find in Files instead.

armareforger-scripteditor findfile navigation.png

To search for a file start by typing into the search bar (1). The results are visible in the search results (2).

Double Click on any of the files in the search results (2) to open and navigate to them in the Text Editor.

armareforger-scripteditor findfile.png

Find Symbol

Use the Find Symbol to find a particular symbol located within any of the script files. To search for text in files, refer to Find in Files instead.

armareforger-scripteditor findsymbol navigation.png

To search for a symbol, type into the search bar (1). The results are visible in the search results (2).

Double Click on any of the symbols in the search results (2) to open and navigate to them in the Text Editor.

armareforger-scripteditor findsymbol.png

Find in Files

Use Find in Files to search for a text match within any of the script files. To search for symbols, refer to Find Symbol instead. For the search results of the Text Search window see Find Results.

armareforger-scripteditor search fulltext navigation.png

Type into the search bar (1). Click on the Find All (2) button to search. This should open the Find Results (3) window with results.

Click on any of the found results visible in the Find Results (3) window to open and navigate to them in the Text Editor.

armareforger-scripteditor search fulltext.png

Goto Declaration

The Goto Declaration functionality is another navigation tool available from within the Text Editor:

Right Click on any of the symbols (1) in the currently open script file to expand a contextual menu.

Click on the Goto Declaration (2) option in the contextual menu. This will navigate to the symbol declaration (3).

In addition, use Left Control + Click key combination on desired symbol to navigate to the Declaration.

armareforger-scripteditor goto declaration.png

Find in Entire Solution

Navigate the code using the Find in Entire Solution functionality from within the Text Editor.

Right Click on any of the symbols (1) in the currently open script file to expand a contextual menu.

Click on the Find In Entire Solution (2) option in the contextual menu. This will perform a project-wide search. For more information regarding searching and finding results, see Find Results.

armareforger-scripteditor findallreferences.png

Find Results

Find Results is a window that provide us with all found results when performing any search via the Script Editor search functionality. See Searching for more information.

Double Click on any of the entries within the Find Results (1) window to navigate to them and open them in the Text Editor.

armareforger-scripteditor findresults.png

Find Entity

Some entities in the world can be named and have a script associated with them. Such entity scripts can be found via the Find Entity window.

To be able to use the Find Entity option, open a world in the World Editor module of the Enfusion Workbench.

Then, filter for a particular entity by typing into the Search field (2) of the Find Entity window.

Double Click on any of the entries within the Find Entity (1) window to navigate to them and open them in the Text Editor.

armareforger-scripteditor findentity.png

Keyboard Shortcuts

Shortcuts are useful to improve the speed and/or efficiency of the Script Editor usage's workflow:

Shortcut Function
Ctrl + S Save All
Ctrl + O Open File
Ctrl + F Find in current file
Ctrl + ⇧ Shift + F} Find in all files
Alt + ⇧ Shift + O Find Files
Alt + ⇧ Shift + S Find Symbols
F3 Find Next
⇧ Shift + F3 Find Previous
Ctrl + G Jump To Line
Alt + G Find Stack Trace
Ctrl + Left Mouse Button on symbol Find in Symbols, Goto Declaration
Double Left Mouse Button Highlight selection
F7 Compile
Ctrl + F7 Compile current file on host (game)
F5 Debug: Continue
F10 Debug: Step Over
F11 Debug: Step Into
⇧ Shift + F11 Debug: Step Out
F9 Insert Breakpoint
Ctrl + F2 Toggle Bookmark
Ctrl + D Duplicate Line / Selected Text
Ctrl + Page Up Previous Tab
Ctrl + Page Down Next Tab
Ctrl + ↹ Tab Cycle Tabs
Ctrl + W Close Current Tab
Alt + ← Navigate Back
F2 Next Bookmark
⇧ Shift + F7 Previous Bookmark
Ctrl + Spacebar Show code completion suggestions
Ctrl + ⇧ Shift + Space Show tooltip for current cursor position


Debugging

Breakpoints

To place or remove a breakpointinto/from code, Click right next to the Line Number (1) panel in the Text Editor or press F9.

The placed breakpoint will then be visible in the Breakpoints (2) window. Breakpoints can be added, removed or toggled at any time, even during run-time.

The checkboxes (/) can be used from within the Breakpoints (2) window to enable or disable given breakpoint.

Disabled breakpoints will not be hit and will simply be ignored.

Breakpoints shown as are invalid and will not be hit by the debugger.

Breakpoints are invalidated if placed in code that does not match the current code run by the connected game.

armareforger-scripteditor debugging breakpoint.png

After placing a breakpoint in our code, let's run the game. With an assumption that the code will be executed, we should see theicon pop up over the first encountered breakpoint.

The icon shows the current execution step, as seen on the current line (1). The Debug (2) window can then be used to go through the code execution step by step.

armareforger-scripteditor debugging breakpoint hit debugger.png

Debug

The Debug window then provides us with the following options: Continue, Step Over, Step Into, Step Out and Stop.

  • Continue: Continue standard code execution until next breakpoint is hit.
  • Step Over: Advance the debugger without stepping into functions or methods.
  • Step Into: Advance the debugger one statement at a time.
  • Step Out: Advance the debugger until the current function returns.
  • Stop: Stop the playmode and current debugging session.

armareforger-scripteditor debugger descriptors.png

Hovering the mouse cursor over a variable displays its current value, in the addition to Watch usage, explained below.

armareforger-scripteditor debugging steps.gif

Connecting the debugger

Opening the Script Editor while the game is running automatically attaches the debugger via the default port, displaying the following pop up message (1).

armareforger-scripteditor debugging connectedpopup.png

In addition, a debugger can be connected to a different port via the Debug options from the Menu Bar.

One particularly interesting option is the Debug → Debug Custom, which allows us to connect to a user provided port.

Selecting the Debug → Debug Custom will make the following window (1) appear in which the debugger's port can be set.

armareforger-scripteditor debugging customport.png

To launch the Enfusion Workbench or the game itself on a specific port, use the -debuggerPort command line argument.

In the following image, the Properties (1) of a Workbench shortcut is set to port 1234 via the argument -debuggerPort 1234 as seen in the Target (2) field.

armareforger-scripteditor windows properties scriptdebugger port.png

Watch

The Watch feature can be used to learn about how code changes in run-time. This allows the user to see the current values of variables while navigating through the code via the debugger.

armareforger-scripteditor debugger watch.png

Callstack

To learn about the code flow in run-time the Callstack feature can be used. This feature shows us the methods' call order.

It must be read from the bottom up. In this case, the depicted call originated in: MyComponent:EOnInit → MyComponent::DoWelcome → Welcomer::SayHello.

armareforger-scripteditor debugger callstack.png

Console

In addition to the Callstack and Breakpoints, the Console is of great debugging assistance. The Console can be used in run-time to execute user scripts within the current stack.

armareforger-scripteditor console.png

Being in playmode is mandatory to use the console. Code which will be global to the current file can then be run. The console can also be used when a breakpoint is hit while debugging and the run code will be local to the current instance. For more information regarding breakpoints see Breakpoints.

Write code into the console and press the Run (1) button. Local variables can be used; for more information see Watch.

Results will be visible in the Output (2) window.

armareforger-scripteditor console run.png

Virtual Machine Exceptions

From time to time, unhandled code may be encountered - like in this example below, where we are trying to call a method via a null reference. In such cases a Virtual Machine Exception will be raised.

Press Stop to halt the code execution immediately, ignore single or all cases via Ignore and Ignore All, or navigate straight to the problem using the Debug button.

armareforger-scripteditor debugging virtualmachineexception.gif

Retrieved from "https://community.bistudio.com/wiki?title=Arma_Reforger:Script_Editor&oldid=322742"