cloudscript-server

Playfab CloudScript Server

A command line program for running your cloudscript code locally

Has stack traces for Javascript and API errors
Listens to file changes and restarts the server to reflect the latest changes

Features

• Hot Reload: Automatically restarts server when files change
• Error Stack Traces: Detailed error reporting with file and line numbers
• TypeScript Support: Generate TypeScript typings for your CloudScript
• Minification: Support for minified compilation
• Remote Execution: Execute CloudScript on remote servers for better performance
• Verbose Logging: Detailed request/response logging
• Cache Management: Clear compilation and type generation cache
• Project Initialization: Initialize new CloudScript projects

Installation

First, install the package globally:

npm install -g cloudscript-server

Environment Variables

This service requires 2 environment variables:

• TITLE_ID = "your project title id"
• TITLE_SECRET = "your project developer secret"

You can use a .env file in the same cloudscript project folder for setting up the environment variables. Remember to add the .env file to the .gitignore file for your repository to avoid sensitive keys leaking.

Basic Usage

Run the program in your cloudscript project directory:

cloudscript-server  

The default port of the server is 8080, this can be changed by passing a -p or --port argument to the program.

You can also use a -d or --dir argument to point to your cloudscript project folder.

For testing in the editor you have to set in your PlafabSharedSettings.asset the ProductionEnvironmentUrl to http://127.0.0.1:8080.

Command Line Options

Server Options

• -p, --port <number>: Set server port (default: 8080)
• -d, --dir <path>: Set project directory (default: current directory)
• --minify: Use minified compilation
• --verbose: Enable verbose logging
• --verboseignore <functions>: Comma-separated list of functions to ignore in verbose logging
• --clear-cache, --clearCache: Clear compilation and type generation cache

Special Commands

• init: Initialize a new CloudScript project
• clear-cache: Clear all caches
• generate-typings, --auto-generate-typings: Generate TypeScript typings
• typings: Generate typings (legacy command)
• publish: Publish minified version to PlayFab
• remote: Run in remote mode (requires remote server setup)

Examples

# Run with custom port and directory
cloudscript-server -p 3000 -d ./my-cloudscript-project

# Run with verbose logging
cloudscript-server --verbose

# Run with minified compilation
cloudscript-server --minify

# Clear cache and run
cloudscript-server --clear-cache

# Initialize new project
cloudscript-server init

# Generate typings
cloudscript-server generate-typings

# Publish to PlayFab
cloudscript-server publish

File Watching

The server automatically watches for changes in .js and .ts files and restarts when changes are detected. Files in node_modules and typings/autogenerated/ directories are ignored.

Ignore Files

The CloudScript server supports several ignore files for different purposes:

.cloudscriptignore

Used during compilation and publishing to exclude files and directories. Uses the same format as .gitignore. Default ignored patterns:

node_modules
typings

.verboseignore

Used to exclude specific functions from verbose logging. Each function name should be on a separate line.

.dtsignore

Used to exclude files from TypeScript type generation.

Project Structure

When you initialize a new project with cloudscript-server init, the following structure is created:

your-project/
├── .env                    # Environment variables (copy from .env.template)
├── .cloudscriptignore     # Files to ignore during compilation
├── .verboseignore         # Functions to exclude from verbose logging
├── .dtsignore            # Files to exclude from type generation
├── tsconfig.json         # TypeScript configuration
├── ServerUtils.ts        # Server utilities and initialization
└── typings/             # TypeScript type definitions
    └── globals/
        ├── node/
        └── playfab/

Verbose Logging

Enable verbose logging with --verbose to see detailed request and response information. You can create a .verboseignore file in your project directory to specify functions that should be excluded from verbose logging.

TypeScript Support

Generate TypeScript typings for your CloudScript:

cloudscript-server generate-typings

This creates type definitions that can be used in your IDE for better development experience.

Publishing

Publish your CloudScript directly to PlayFab:

cloudscript-server publish

Use a .cloudscriptignore file for ignoring files during the publishing process. This file uses the same format as a .gitignore file.

Remote Server

Server Setup

This package allows running a WebSocket server to execute the CloudScript file in a remote location for faster responses if the server is located closer to the PlayFab servers (currently: Azure US West 2).

Server configuration instructions:

• Install docker and docker-compose

• Clone this repository in your server

• Create a .env file in the same cloudscript-server folder with the following variables:

  REMOTE_SERVER_DOMAIN = {your_domain}  
  REMOTE_SERVER_AUTH = {a_secret_password}  
  REMOTE_SERVER_PORT = {your_port}  
  

• Run the following commands:

  docker-compose build  
  docker-compose up -d  
  

• Open the port declared above on your server to the internet.

This is a complex feature and can have bugs. If you find any, please report them.
Do not, for any reason, run this server in any place where you have sensitive data or any sensitive services due to the nature of remote code execution.

Connecting to the Remote Server

In your CloudScript project folder, add the following variables to your .env file:

REMOTE_SERVER_URL = wss://{your_domain}:{your_port}  
REMOTE_SERVER_AUTH = {your_password}  

Then run:

cloudscript-server remote

API Endpoints

The server provides the following endpoints:

• POST /Client/ExecuteCloudScript: Execute CloudScript functions (client-side)
• POST /Server/ExecuteCloudScript: Execute CloudScript functions (server-side)
• *: Proxy all other requests to PlayFab API

Error Handling

The server provides detailed error information including:

• JavaScript exceptions with stack traces
• PlayFab API errors
• Compilation errors
• Network errors

All errors are logged with colored output for better readability.

Performance Monitoring

The server tracks:

• API request count
• HTTP request count
• Execution time
• Function logs

This information is included in the response for debugging purposes.

Disclaimer

This server should not be used in production. It will not work properly because the currentPlayerId is set as a global variable. If a new request arrives while another request is processing, the currentPlayerId will be changed and things will break. In fact, only one user can use this server at a time because of this limitation.

Important: When using TypeScript and importing modules, do not use import aliases (like import {foo as bar} from "module"). You must use the original variable names in your imports (like import {foo} from "module"). Import aliases are not supported during compilation.

Depending on your location and the number of API requests in your handler, this server can be slow due to the higher latency between your location and the PlayFab servers (currently Quincy, Washington).

This package is arriving a little late; it should have been done by PlayFab ages ago, but better late than never...