Getting Started

Welcome to xs! This guide will help you create your first extra small game. It will also explain the basics of the engine and how to use it.

---

Installation

First, grab the latest version of xs from the itch.io page or you can build it from source. There is not installer for xs yet, so just unzip the archive in your desired location.

Running xs

The preferred way of running xs is from the command line (terminal), so you can provide commands to it and read the debug output. Open your command line/terminal application and cd to the xs folder. Run the executable by providing run command and a path to a game folder. For example: xs.exe run samples/hello on Windows or ./xs run samples/hello on macOS. You should get output in the command line. Even better, use Visual Studio Code with the built-in terminal.

The "hello" sample looks like the image below and should run without errors.

Great, xs is up and running!

---

Working with the xs Visual Studio Code Extension

xs is a code-first game engine, so using a code editor with good Wren support helps a lot. The xs Visual Studio Code extension provides integrated development features such launch commands/buttons, an animation editor, a package inspector and launch templates to enhance your game development experience.

Creating a New Project

Creating a new project in xs is quite simple. An xs project is just a folder, with a project.json file in it that contains the project settings, most important one being the path to the game code in the Main field. You main class file should be a Wren file located in the same folder or a subfolder.

The Game class needs to have three static methods:

• initialize - Called as soon as all systems have been created
• update - Called once per tick (frame)
• render - Called once per tick, right after update

This is the a minimal example:

import "xs" for Render, Data
class Game {
    static initialize() { /* Initialize your game state here */ }
    static update(dt) { /* Update your game state here */ }
    static render() { /* Render your game here */  }
}

Next, just put your awesome art and code in the folder and you have yourself a game!

---

Setting Up Your Environment

Wren is a lovely modern scripting language and there are a handful of Visual Studio Code extensions to make working with it nicer.

xs can be instructed (from the system.json) to run on top of other windows. This can be useful when developing or debugging with it. Running xs from the built-in terminal in VS Code will give a "single window"-like experience.

---

Wren Modules

A module in Wren is usually another .wren file that you can import into your code. xs ships with a few modules that let you interact with the engine:

• xs - Core API for rendering, audio, input, and more
• xs_math - 2D vector math, colors, and bit operations
• xs_ec - Simple Entity-Component framework
• xs_components - Pre-built components for common game functionality

The "hello" example starts with importing functionality:

import "xs" for Render, Data

These modules are located in the assets/modules/ folder, so feel free to explore their contents.

Built-in Wren Modules

From the language itself (learn more):

• Core classes - Numbers, lists, maps, etc. (automatically imported)
• random - Random number generation

---

Working with Paths

Paths in xs are relative and should start with one of the wildcards. For example, you can use the [game] wildcard to access asset files in your game:

var image = Render.loadImage("[game]/images/cat.png")

---

Supported Assets

xs supports .png images and a variety of sound files, with .flac being the preferred format.

---

Next Steps

Now that you're set up, check out the API Reference to learn about all the available modules and functions!