Difference between revisions of "HPL3/Scripting/Scripting Guide/Setting up CodeLite"

From Frictional Wiki
Jump to navigation Jump to search
(Created page with "{{Hpl3ScriptingGuideMenuBasic}} == CodeLite - Introduction == As mentioned Scripting in HPL3 can look a lot like regular programming, but less complicated. Because of that,...")
 
 
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{Hpl3ScriptingGuideMenuBasic}}
 
{{Hpl3ScriptingGuideMenuBasic}}
 +
{{shortPageTitle}}
 +
This is a quick guide on how to set-up the third party scripting tool - CodeLite.
 +
==CodeLite - Introduction==
  
−
== CodeLite - Introduction ==
+
As mentioned, scripting in HPL3 can look a lot like regular programming, but less complicated.
  
−
As mentioned Scripting in HPL3 can look a lot like regular programming, but less complicated.
+
Because of that, we need tools that will be able to aid us when we write our code. For HPL2, Notepad++ or even Notepad were enough for that. This time around, something more powerful is needed.
  
−
Because of that, we need tools that will be able to aid us when we write our code. For HPL2, Notepad++ or even Notepad were enough for that. This time around, something more powerful is needed.
+
CodeLite is very much like a text editor, but much more programming-oriented than Notepad++. It is the tool used officially by Frictional Games to develop their HPL3 games. Here are some of the relevant features of CodeLite:
 +
 
 +
*'''Code documentation on the fly'''
 +
*'''Code autocompletion and smart code suggestion'''
 +
*'''Fast and easy way to navitgate through large script files'''
 +
*'''The ability to run the game from CodeLite'''
  
−
We need a tool that will be able to provide us with easy access to documentation on the fly, autocomplete our code and provide easy ways to view the structure of our code, as well as referenced code from other script files.
+
For the scripting guide, CodeLite 12.0.0 will be used, which is the latest stable release that can work with HPL3 without any errors or bugs.  
−
For this, we will use a program called CodeLite.
+
[[File:Codelite-window.png|thumb|CodeLite with a scripting workspace for SOMA (click to view full size).|alt=|left]] {{clr}}
  
−
CodeLite is very much like a text editor, but much more programming-oriented than Notepad++.
+
==Setting-up CodeLite==
−
It will make our job much easier and reduce the chances of making errors in our code, which will eventually make our workflow faster and more efficient.
+
This section explains how to configure CodeLite so it can be suitable for HPL3 scripting, how to create a workspace and a project, and how to import the script files.
  
−
Now, there are other programs out there that could potentially work with HPL3.5 such as Visual Studio Code, but after extensive experimentation with various programs I came to the conclusion that CodeLite is currently the best tool when modding Rebirth. If you have any other suggestions, please let me know.
+
{{Note|You must install CodeLite on the same disk as the game you want to mod. For example, if Amnesia: Rebirth is installed on disk C:, you have to install CodeLite on C: as well.}}
  
−
For this tutorial series, we will use CodeLite 12.0.0, which is the latest stable release that can work with HPL3.5 without any errors or bugs.  
+
#[[CodeLite#Optimized_Color_Theme|Download the optimized color theme]]
 +
#[https://downloads.codelite.org/ReleaseArchive.php Download and install CodeLite version 12.0.0.]
 +
#'''Launch CodeLite and configure:'''
 +
##<code>Settings → Code Completion → General</code>:
 +
##*Add <code>;*.hps</code> at the end of the <code>Additional file extensions to parse</code> list.
 +
##*Enable <code>Keep function signature un-formatted.</code>
 +
##*Enable  <code>Re-parse on workspace loaded</code>.
 +
##<code>Settings → Code Completion → Colouring</code>: Enable <code>Apply context aware colouring</code>.
 +
##<code>Settings → Code Completion → CTags → Search Paths</code>: Click <code>Add...</code>, navigate to the game folder and select the <code>script</code> folder.
 +
##<code>Settings → Colours and Fonts...</code>: Click on <code>Import settings from a zip archive</code> and select the <code>CodeLiteColorSettings.zip</code> file.
 +
##Configure the rest of CodeLite to your liking.
 +
#'''Create a new workspace:''' Create a folder inside your game directory and name it <code>_src</code>. Go to the <code>Workspace</code> menu and click on <code>New Workspace...</code>. Save the workspace inside the <code>_src</code> folder.
 +
#'''Create a new project:''' <code>Right click on the workspace → New → New Project</code>. Select <code>Others → Non-code project</code>. Give the project a name (For example: "soma"). Leave the rest as default.
 +
#'''Add a folder to the project:''' Right-click on the project and choose <code>New Virtual Folder</code>. Name it <code>_api</code>.
 +
#'''Add the game script files:'''
 +
##Right-click on <code>_api → Add An Existing File...</code>, add the file <code>hps_api.hps</code> from the game folder (If the file does not appear in your game folder, launch the game, and the file will appear).
 +
##Right-click on the project and choose <code>Import Files From Directory</code>. Navigate to the game folder and select it. In the next window, check the boxes for the folders: <code>maps, script, mods</code> and click ok.
  
−
In addition, you should download the zip file that can be found in this page, it contains some additional themes, colors and keywords, which will result in a better display of  the script files.
+
'''Lastly, go to <code>Workspace</code> and click on <code>Parse Workspace</code>.'''
  
−
== Setting-up CodeLite ==
+
That should be it, you should now have three top folders in your project and a lot of sub-folders with various script files.
−
# [https://downloads.codelite.org/ReleaseArchive.php Download CodeLite version 12.0.0 or lower from here.]
+
Start typing something, for example <code>Entity_</code> and a list should appear showing all the functions that begin with <code>Entity_</code> and the documentation for each selected function.
−
# Launch CodeLite and configure:
 
−
## Settings→Code Completion→Display and Behavior: Activate "Keep function signature un-formated".
 
−
## Settings→Code Completion→ctags→Search Paths: Click Add.. and navigate to the SOMA game folder and select the script/ folder.
 
−
## Settings→Code Completion→Colouring: Enable colour local variables.
 
−
## (optional) Settings→Code Completion→Colouring: Enable colour workspace tags, also enable enumerator but leave the rest with default setting.
 
−
## (optional) Settings→Code Completion: Configure the rest to your liking. For example, auto-show & case sensitive enabled.
 
−
## Settings→Colours and Fonts→Customize, select C++ and in Global Settings add <nowiki> *</nowiki>.hps to the File Extension list.
 
−
# Create a new workspace. Do this by going to Workspace menu and select "New Workspace…". Pick C++ Workspace. Name is as you like and set the workspace path as you like '''as long as it is on the same drive as SOMA.'''
 
−
# Create a new project in the workspace. Do this by right-clicking on the workspace in the list to the left and choose the Create New Project option. Select others → Non-code project. Name as you like and leave rest as default.
 
−
# Add one folder to the project. Right-click on the project folder and choose New Virtual Folder. Name it _api (you can create others later when you know more).
 
−
# Time to add files to the project.
 
−
## Right-click on _api and Add An Existing File, add the file "SOMA GAME FOLDER LOCATION/hps_api.hps" (might need to launch the game executable one time to have this file created).
 
−
## Right-click on the project in the list to the left, pick Import Files From Directory. Navigate to the SOMA GAME FOLDER and select it. In the next window, check the boxes for maps and scripts and make sure that the <nowiki>*</nowiki>.hps file extension is present in the list of extentions to import. Click OK.
 
  
−
That should be it, you should now have three top folders in your project and a lot of sub-folders with various script files. Hps files should be color coded and parsed for completion as you open them in the project. If they do not, you can re-tag the workspace, project or the single file to see if it helps.
+
{{note|If the list disappears, you can make it re-appear again by pressing <code>ctrl-space</code>. If you want to bring up hints when inside the () of a function, press <code>ctrl-shift-space</code>.}}
 +
<br>
 +
{{warning|CodeLite won't update automatically the location of workspace files. If you moved them outside of CodeLite, you will need to re-add  them. The same goes for creating new file after setting up a workspace}}
  
−
Start typing something, for example Entity (depending on configuration this can be case sensitive!) and a drop down should appear showing all the functions that begin with Entity and the documentation for each selected function. You can force things to appear using these shortcuts:
+
==Launching the Game From CodeLite==
  
−
*ctrl-space will bring up the completion drop down.
+
One additional thing you can do is to launch the game or your mod in dev mode through CodeLite itself.  
−
*ctrl-shift-space will bring up hints when inside the () of a function.
 
  
−
==Issues & Info==
+
To do this, right click on your project and go to settings. Then Click on <code>Customize → Custom Build</code>.
 +
Turn on <code>Enable Custom Build</code>. In the working directory, select the game folder.
  
−
*Write Class@ object and not Class @object, the later will screw up coloring.
+
Now you will need to add the command that launches the game or the mod. For example, a command that launches the main game of SOMA in dev mode will look like this:
−
*If you loose all coloring and can't get it back, just re-tag the workspace.
+
<pre>Soma.exe -user Dev -cfg config/main_init_dev.cfg</pre>
−
*Parameters with &in will break coloring of parameter, but will have no other side-effects.
 
  
−
===Extra Info===
+
Add the command to the <code>Build</code> section in the table.
 +
[[File:Codelite custom build.png|thumb|SOMA workspace with custom build command (click to view full size).|alt=|left]] {{clr}}
  
−
Info about Settings→Colours and Fonts→Customize→Styles→Edit Lexer keyword sets, Set 0 to Set 4:
+
For more information about available commands, visit the [[HPL3/Developer_Commands|Developer Commands]] article.
  
−
*Set 0 User configured list of keywords not already parsed. Can be edited.
+
'''Now, all you need to do is to press F7, and the game will run!'''
−
*Set 1 Unknown.
 
−
*Set 2 Doxygen keywords, words here will be colored in comments using /<nowiki>*</nowiki><nowiki>*</nowiki> codeblocks when prepended with @ ie @var int myInt. Can be edited.
 
−
*Set 3 Used for the setting "Colour workspace tags", automatically created (not visibly). Can NOT be edited.
 
−
*Set 4 Used for the setting "Colour local variables", automatically created (not visibly). Can NOT be edited.
 
  
 +
==Issues & Info==
  
 +
*Write <code>Class@ object</code>  and not <code>Class @object</code>, the latter will screw up coloring.
 +
*If you lose coloring / code completion and can't get it back, re-parse the workspace: <code>Parse Workspace</code>.
 +
*Parameters with <code>&in</code> might break the coloring of function parameters, but will have no other side-effects.
  
−
{{NavBar|HPL3/Scripting/What is scripting in HPL3?|What is scripting in HPL3?|HPL3/Scripting/HPL3 Scripting Guide|HPL3 Scripting Guide|HPL3/Scripting/Launching the Game from CodeLite|Launching the Game from CodeLite}}
+
{{NavBar|HPL3/Scripting/Scripting_Guide/What is scripting in HPL3?|What is scripting in HPL3?|HPL3/Scripting/HPL3 Scripting Guide|HPL3 Scripting Guide|HPL3/Scripting/Scripting_Guide/Scripting Workflow and Structure|Scripting Workflow and Structure}}
  
 
[[Category:HPL3 Scripting]]
 
[[Category:HPL3 Scripting]]
 
[[Category:English]]
 
[[Category:English]]

Latest revision as of 00:42, 15 August 2020

  1. The Basics - Introduction
  2. What is scripting in HPL3?
  3. Setting up CodeLite - Scripting Tool
  4. Scripting Workflow and Structure
  5. Hello World
  6. Calling Functions and Function Callbacks
  7. Helper Files
  8. The OnAction method
  9. The Update method
  10. Timers
  11. Sequences
  12. Local and Global Variables
  13. Enums
  14. Conclusion

This is a quick guide on how to set-up the third party scripting tool - CodeLite.

CodeLite - Introduction

As mentioned, scripting in HPL3 can look a lot like regular programming, but less complicated.

Because of that, we need tools that will be able to aid us when we write our code. For HPL2, Notepad++ or even Notepad were enough for that. This time around, something more powerful is needed.

CodeLite is very much like a text editor, but much more programming-oriented than Notepad++. It is the tool used officially by Frictional Games to develop their HPL3 games. Here are some of the relevant features of CodeLite:

  • Code documentation on the fly
  • Code autocompletion and smart code suggestion
  • Fast and easy way to navitgate through large script files
  • The ability to run the game from CodeLite

For the scripting guide, CodeLite 12.0.0 will be used, which is the latest stable release that can work with HPL3 without any errors or bugs.

CodeLite with a scripting workspace for SOMA (click to view full size).

Setting-up CodeLite

This section explains how to configure CodeLite so it can be suitable for HPL3 scripting, how to create a workspace and a project, and how to import the script files.

Note icon.png You must install CodeLite on the same disk as the game you want to mod. For example, if Amnesia: Rebirth is installed on disk C:, you have to install CodeLite on C: as well.
  1. Download the optimized color theme
  2. Download and install CodeLite version 12.0.0.
  3. Launch CodeLite and configure:
    1. Settings → Code Completion → General:
      • Add ;*.hps at the end of the Additional file extensions to parse list.
      • Enable Keep function signature un-formatted.
      • Enable Re-parse on workspace loaded.
    2. Settings → Code Completion → Colouring: Enable Apply context aware colouring.
    3. Settings → Code Completion → CTags → Search Paths: Click Add..., navigate to the game folder and select the script folder.
    4. Settings → Colours and Fonts...: Click on Import settings from a zip archive and select the CodeLiteColorSettings.zip file.
    5. Configure the rest of CodeLite to your liking.
  4. Create a new workspace: Create a folder inside your game directory and name it _src. Go to the Workspace menu and click on New Workspace.... Save the workspace inside the _src folder.
  5. Create a new project: Right click on the workspace → New → New Project. Select Others → Non-code project. Give the project a name (For example: "soma"). Leave the rest as default.
  6. Add a folder to the project: Right-click on the project and choose New Virtual Folder. Name it _api.
  7. Add the game script files:
    1. Right-click on _api → Add An Existing File..., add the file hps_api.hps from the game folder (If the file does not appear in your game folder, launch the game, and the file will appear).
    2. Right-click on the project and choose Import Files From Directory. Navigate to the game folder and select it. In the next window, check the boxes for the folders: maps, script, mods and click ok.

Lastly, go to Workspace and click on Parse Workspace.

That should be it, you should now have three top folders in your project and a lot of sub-folders with various script files. Start typing something, for example Entity_ and a list should appear showing all the functions that begin with Entity_ and the documentation for each selected function.

Note icon.png If the list disappears, you can make it re-appear again by pressing ctrl-space. If you want to bring up hints when inside the () of a function, press ctrl-shift-space.


Alert icon.png Warning: CodeLite won't update automatically the location of workspace files. If you moved them outside of CodeLite, you will need to re-add them. The same goes for creating new file after setting up a workspace

Launching the Game From CodeLite

One additional thing you can do is to launch the game or your mod in dev mode through CodeLite itself.

To do this, right click on your project and go to settings. Then Click on Customize → Custom Build. Turn on Enable Custom Build. In the working directory, select the game folder.

Now you will need to add the command that launches the game or the mod. For example, a command that launches the main game of SOMA in dev mode will look like this: 

Soma.exe -user Dev -cfg config/main_init_dev.cfg

Add the command to the Build section in the table.

SOMA workspace with custom build command (click to view full size).

For more information about available commands, visit the Developer Commands article.

Now, all you need to do is to press F7, and the game will run!

Issues & Info

  • Write Class@ object and not Class @object, the latter will screw up coloring.
  • If you lose coloring / code completion and can't get it back, re-parse the workspace: Parse Workspace.
  • Parameters with &in might break the coloring of function parameters, but will have no other side-effects.
Retrieved from "https://wiki.frictionalgames.com/page?title=HPL3/Scripting/Scripting_Guide/Setting_up_CodeLite&oldid=4361"