Live Scripting - Pt1 - Basics

Live Scripting - Pt1 - Basics#

Xsolla Backend Script Manager#

Welcome to the first article in a five-part series on custom scripting with Xsolla Backend! In this part, we will introduce you to the Xsolla Backend Script Manager, a Visual Studio Code extension designed to streamline script management with your Xsolla Backend cluster.

Features of the Script Manager#

The Xsolla Backend Script Manager provides several key features:

  • Checkout scripts from an Xsolla Backend cluster.

  • Generate a package.json with required dependencies.

  • Add, modify, or delete service scripts locally in your workspace.

  • Commit local changes to the remote server as unpublished.

  • View and diff local and remote changes.

  • Publish or delete unpublished remote script changes.

Step 1: Installing the Xsolla Backend Script Manager#

Creating a Workspace Folder#

  1. Create an empty folder for your workspace, name it something like xbe-scripts.

  2. Open a new Visual Studio Code window and open your folder via File -> Open Folder…

  3. Save a new workspace file (e.g. xbe-scripts.code-workspace) to your folder via File -> Save Workspace As…

Installing the Extension#

  1. Navigate to the Extensions panel (or press Ctrl+Shift+X).

  2. In the search bar, type Xsolla Backend and select the Xsolla Backend Script Manager.

  3. Click the Install button to add the extension to Visual Studio Code.

Now that you’ve installed the extension and created your project folder, you’re ready to set up your workspace and synchronize scripts from your Xsolla Backend cluster.

Step 2: Checking Out Scripts from Your Xsolla Backend Cluster#

Viewing Extension Output#

It can be helpful to view the extension output to monitor the synchronization process:

  1. Open the Output panel in Visual Studio Code (Ctrl+Shift+U).

  2. In the dropdown menu, select Xsolla Backend to view extension output:

Output Select

Synchronizing Scripts from Your AXR Cluster#

Once your workspace is set up, you can synchronize scripts from your Xsolla Backend cluster:

  1. Open the Command Palette (Ctrl+Shift+P).

  2. In the input prompt, type xbe: checkout and press Enter.

  3. You will be prompted for:

    • Host: This is the base API URL of your Xsolla Backend cluster (e.g. https://api.demo.xbe.goxbe.cloud/v1).

    • Service: Select one of the available live scripting services from the list shown.

    • Username: Enter the username of an account with admin role.

    • Password: Enter the account password.

    • Dependencies: Choose whether to write a package.json file.

Once synchronization is complete, you’ll notice several new files and folders in your workspace. This includes your scripts and configuration files downloaded from the selected service, a .vscode folder containing your service settings, and if specified, a package.json file containing the relevant dependencies:

checkout

Connection settings are stored in your workspace file (such as xbe-scripts.code-workspace) under settings. These consist of your cluster API base URL as well as your cached authentication token, which will be used to reconnect to the cluster as needed. If your token expires you will be prompted for a username and password once again and a new token will replace it. Your workspace file should look similar to this:

{
  "folders": [
    {
      "path": "."
    }
  ],
  "settings": {
    "xbe.host": "https://api.demo.xbe.goxbe.cloud/v1",
    "xbe.token": "..."
  }
}

Service-specific settings are stored in the .vscode/settings.json file in your workspace. These include the service name and install dependencies selections you entered, for example:

{
  "xbe.service": "scripting-services",
  "xbe.installDependencies": true
}

Step 3: Modify and Revert Local Script Changes#

Editing a Script#

  1. Open MetricsCollector.ts from the jobs folder.

  2. Make an edit to the script and save the file.

  3. Notice that the Source Control icon now shows one pending change.

Viewing Changes#

  • Click the Source Control icon to see two categories: Changed Local Scripts and Unpublished Remote Scripts.

  • The Changed Local Scripts category shows locally modified scripts, allowing you to view diffs between your local version and the remote server version:

changes

Discarding Local Changes#

  1. In the Source Control panel, locate the MetricsCollector.ts file under the Changed Local Scripts section.

  2. Click on the Discard Local Changes button next to the file name.

    • This will discard any local modifications and restore the file to its original state as it exists on the remote server.

  3. The pending change indicator will be cleared, confirming that your local changes have been successfully reverted:

discard-local

Step 4: Committing Changes to the Remote Server#

Creating a New Script#

  1. In your workspace, create a new file called TestScript.ts.

  2. Add the following code to TestScript.ts as an example:

    const testNumber: number = 5;

  3. Save the file, and you will see that the Source Control icon shows one pending change.

Committing Changes#

  1. Open the Source Control panel by clicking on the Source Control icon in the left sidebar.

  2. You will see TestScript.ts listed under the Changed Local Scripts section.

  3. Click the Commit Local Changes button next to TestScript.ts to commit the file.

  4. You will be prompted to enter a commit message.

  5. Press Enter to save the changes to the remote server.

Once the commit operation is successful, the script will move from the Changed Local Scripts section to the Unpublished Remote Scripts section, indicating that it has been saved to the remote server but is not yet live:

commit

Editing Unpublished Remote Scripts#

  • If you wish to make further changes to an unpublished script prior to publishing, simply edit it in your workspace commit it again. The updated version will replace the previous unpublished version.

Committing All Local Changes#

  • You can commit all local changes at once by clicking the Commit All Local Changes button in the Source Control panel. This will commit all pending changes in the Changed Local Scripts section to the remote server.

Step 5: Publishing or Discarding Unpublished Remote Changes#

  1. If you are ready to make the script live, click the Publish Committed Changes button.

    • This action publishes the script to the Xsolla Backend cluster, making it live and executable once the server restarts.

    • If your server is configured to restart on publish, the server will restart immediately after a configured timeout.

    publish

  2. If you decide that you no longer want to keep the unpublished changes, you can delete the script instead of publishing it by clicking Discard Committed Changes button.

    • Note: Discarding an unpublished script will not affect the published version that is currently live on the server.

discard-remote

Step 6: Deleting Scripts#

In this step, we will delete the TestScript.ts file locally, commit the deletion, and publish the change to remove it from the remote server.

Deleting a Script#

Deletion of a script is treated like any other change in the Xsolla Backend Script Manager. Let’s walk through the process:

  1. In your workspace, delete the file TestScript.ts and open the Source Control panel.

    • You will notice that TestScript.ts appears crossed out under the Changed Local Scripts section, indicating that it has been deleted locally.

  2. In the Source Control panel, Commit your local changes to TestScript.ts.

    • After committing the deletion, TestScript.ts will move to the Unpublished Remote Scripts section.

  3. To finalize the deletion click Publish Committed Changes.

    • This will publish the deletion of TestScript.ts from the Xsolla Backend cluster, and it will no longer be loaded.

delete

Conclusion#

In this part of the series, we explored the basics of the Xsolla Backend Script Manager and learned how to manage scripts using Visual Studio Code. You should now be comfortable with:

  • Installing the Xsolla Backend Script Manager extension and setting up a workspace.

  • Syncing scripts from your Xsolla Backend cluster.

  • Modifying, committing, and publishing scripts.

  • Reverting changes and deleting scripts when necessary.

These skills form the foundation for managing scripts in your Xsolla Backend environment, allowing you to create, modify, and deploy scripts efficiently.

In the next part of the series, we will dive deeper into customizing your backend by defining and implementing REST API endpoints for your cluster. Stay tuned for more advanced scripting techniques and best practices!