Getting Started with C++ Scripting

Notice

This page is still work in progress and may contain inaccurate information.

%%INSERT API REFERENCE LINK/BUTTON HERE%%

To get started with C++ scripting, you'll first need to create a project.

Create a Project

This can be done by opening Guerilla or Sapien and, when the 'Select Project' dialog is displayed, choosing the 'New Project' button. You will be asked to provide some information about the project, and specify a project folder. When finished, the project will be displayed within the Select Project dialog upon opening Sapien or Guerilla in the future.

Setting up Tool

From here, you'll need to run a few commands within Tool, a general-purpose command-line utility included as part of the engine's Editing Kit. First, instruct tool to use your new project by running:

tool set-project-root <root>

You should see a message saying that the project root has been changed. If an error is displayed, ensure that you provided a valid directory path. Note that projects located on network shares are currently not supported and you may encounter errors.

Creating a Visual Studio Project and Solution

Next, you can use several tool commands to create the appropriate Visual Studio projects and solutions used by the project. First, create the project for your scripts by running:

tool generate-script-project

This should have created a Visual Studio solution and Visual C++ Project within the root of your project directory, with the same name as your project. This is the project you'll use to write game scripts and debug your game.

Next, however, you'll need to generate another Visual C++ project, which is used by tool to create your game executable. This project is stored in a separate directory and has no Visual Studio Solution associated with it, and generally should not be modified directly by the user - however it must be created in order to successfully build and run your game.

To build this project, run:

tool generate-stub-project

During this process, it will attempt to build your script library, as it needs to resolve certain file and directory paths for each configuration and platform combination. This will generate several text files that are read in by tool. If your script library has build errors, or has no source files, you may see errors from MSBuild - these are not a problem and will not impact this process.

After the executable project has been created, you should see a "finished" message before tool closes. From here, you are ready to build and run your game!

Debugging and Building

To debug your game, simply use the Local Windows Debugger option within Visual Studio after opening your script project. To build the game, you can either directly use Visual Studio to build the game, or you can use the following command within tool:

tool build <Configuration> <Platform>

It is generally reccommended that you build using Visual Studio, as this is both easier, and ensures that your script library is fully up-to-date. If you make changes to your scripts, and then run tool build without first building your script project, the resulting game executable will still be using outdated script code, or may fail to build entirely.