01 Development Environment Setup

This chapter sets up the development environment used throughout the guide.

This guide assumes some Python experience, basic knowledge of Git, and familiarity with running commands in a terminal. Make sure Git is installed before starting.

Repository

The source code used in this guide is available on GitHub.

The template branch contains the initial setup used at the start of the guide. The main branch contains the finished project.

To follow along from the beginning, open a terminal and run these commands to clone the repository and switch to the template branch:

git clone https://github.com/qwewqa/wiki-sonolus.py-guide-code.git
cd wiki-sonolus.py-guide-code
git switch template

Unless a chapter says otherwise, run the remaining commands from the wiki-sonolus.py-guide-code directory.

Installing uv

uv manages the project's Python environment and dependencies and runs tools in that environment. Install it by following the instructions for your operating system, then verify the installation:

uv --version

If the command prints a version number, you are ready to continue.

Initializing the Project

The guide repository already contains a pyproject.toml, the initial Python package, and a development level for testing the engine.

Starting the Development Server

Run this command in the project directory:

uv run sonolus-py dev

Leave this command running. The server prints the addresses you can use to connect from the Sonolus app.

In Sonolus Settings, you should:

• Under Cache, turn on Always Revalidate.
• Under Developer, turn on Debug Mode.

Open the development level. If it starts, the setup is complete. Keep the server running while you follow the guide, and reopen the development level after each change to test the latest code. Load changes into the development server by typing r into the console and pressing Enter.