Skip to content
On this page

All configuration in rpg.toml

The configuration and properties of RPGJS are defined using a JSON schema, which can be used both server-side and client-side. These properties are then used in the rpg.toml configuration file to customize various aspects of your game.


. Below is an overview of the available configuration properties along with their descriptions and usage constraints.


Configuration properties related to the compiler.

  • compilerOptions

    • alias: (object) Aliases. Use aliases in Typescript imports
        "@" = "./src"
    • pwaEnabled: (boolean) Whether the PWA feature is enabled. (true by default)
    • outputDir: (string) Output directory for the build.
    • serverUrl: (string) Server URL.
  • vite: (object) All Vite configuration. Example:

      logLevel = "silent"

    You can insert this section after the vite section in your

    Please note that RPGJS contains certain configurations. You will therefore overwrite certain configurations (the basic file is in the sources).

  • express

Configuration properties related to the Express server.

  • static: (string) Specifies the directory from which to serve static files.

    only for final files put into production

  • port: (integer) The port number on which the Express server listens.


  static = 'public'
  port = 3000
  • express.json

Configuration properties for JSON middleware. Documentation: express.json


  limit = "100kb"
  • express.cors

Configuration properties for CORS middleware. Documentation: cors

  • express.socketIo

Configuration properties for SocketIO middleware. Documentation:

  • spritesheetDirectories: (array) Directories for spritesheets.


Configuration properties related to the server-side of the RPG.

  • start: (object) Information about the starting position.
    • map: (string) The map where the player starts.
    • graphic: (string) The graphic representation.
    • hitbox: (array) The hitbox coordinates.
  • api: (object) API settings. WIP
    • enabled: (boolean) Whether the API is enabled.
    • authSecret: (string) Authentication secret.


Configuration properties related to the client-side of the RPG.

  • shortName: (string) Short name of the game.

  • description: (string) Game description.

  • themeColor: (string) Theme color for the game.

  • icons: (array) Game icons.

  • themeCss: (string) Custom theme CSS.

  • matchMakerService: (string) Matchmaking service.

  • canvas: (object) Canvas configuration options.

    • transparent: (boolean) Whether the canvas should be transparent.
    • autoDensity: (boolean) Automatically adjust the canvas resolution to match the device's pixel ratio.
    • antialias: (boolean) Whether to use antialiasing for smoother graphics.
    • resolution: (number) The resolution of the canvas.
    • preserveDrawingBuffer: (boolean) Whether to preserve the drawing buffer.
    • backgroundColor: (number) Background color of the canvas.
  • selector: (string) Selector for the game container.

  • selectorGui: (string) Selector for the GUI container.

  • selectorCanvas: (string) Selector for the canvas container.

  • standalone: (boolean) Whether the game is standalone (not embedded).

  • drawMap: (boolean) Whether to draw the map. For unit tests

  • maxFps: (number) Maximum frames per second for rendering.

  • serverFps: (number) Server frames per second.

  • pwa: (object) : All Vite PWA configuration. If PWA is enabled.

Client and Server

General configuration properties that can apply globally.

  • inputs: (object) Input configurations.
    • Each input can be defined using an object with the following properties:
      • repeat: (boolean, default: false) Whether the input should be repeated when held.
      • bind: (string or array) The key or keys to bind the input to.
      • delay: (object) Delay settings for the input.
        • duration: (number, minimum: 0) The delay duration in milliseconds.
        • otherControls: (array) Array of other control names to disable during the delay.
  • name: (string) Name of the game.

Example Usage

Below is an example usage of the RPG configuration in TypeScript:

import { RpgServerEngine } from '@rpgjs/server';
import { RpgServer, RpgModule } from '@rpgjs/server';

    engine: {
        onStart(server: RpgServerEngine) {
export default class RpgServerModuleEngine {}


You can use the RPG configuration in your rpg.toml configuration file. Here's an example:

# will only be read by the client
shortName = "My RPG"
description = "A fantastic RPG adventure!"
themeColor = "#ff9900"

# will only be read by the server
    map = "starting_map"