Set up development environment

Welcome to the Strawberry Game Engine! This guide will walk you through everything you need to start building your first game — from installing the required tools, to setting up your project, all the way to writing your first scene. By the end of this document, you will have a working project that launches a window with an empty scene rendered in a clear blue color.

1. Requirements

Before you can start developing with Strawberry, you need to set up your development environment. Strawberry is built on top of .NET 8.0, so the SDK is mandatory. You will also need a code editor — we recommend Visual Studio Code (VS Code) because it is lightweight, free, cross-platform, and has excellent C# support through extensions.

1.1 .NET 8.0 SDK

The .NET SDK provides the compiler, runtime, and command-line tools needed to build and run C# projects. Strawberry specifically targets .NET 8.0, so you must install this version (or a later compatible version).

Download Link: https://dotnet.microsoft.com/en-us/download/dotnet/8.0

After downloading and installing, open a terminal (Command Prompt, PowerShell, or any shell on Linux/macOS) and run:

dotnet --version

You should see a version number starting with 8. (e.g., 8.0.xxx). If you see an error or a different version, the SDK was not installed correctly — make sure you restart your terminal after installation, and verify that the dotnet command is on your system PATH.

1.2 Visual Studio Code

VS Code is the recommended editor for Strawberry development. It is free, open-source, and runs on Windows, macOS, and Linux. While you can use any editor or IDE (such as Visual Studio or JetBrains Rider), this guide assumes VS Code.

Download Link: https://code.visualstudio.com/

Necessary VS Code Extensions

After installing VS Code, you should install the C# Dev Kit extension, which provides:

• IntelliSense — auto-completion and code suggestions as you type
• Debugging — set breakpoints, inspect variables, and step through your code
• Project management — Solution Explorer panel for navigating your projects and files

To install it:

1. Open VS Code
2. Go to the Extensions panel (click the square icon on the left sidebar, or press Ctrl+Shift+X)
3. Search for "C# Dev Kit" (published by Microsoft)
4. Click Install

Optionally, you may also want to install:

• C# extension (by Microsoft) — if it is not already included with the Dev Kit
• NuGet Package Manager — for browsing and managing NuGet packages from within VS Code

2. Installation

Now that your environment is ready, let's create the project structure. Strawberry is distributed through a custom NuGet source, so we need to register it before we can install the engine packages.

2.1 Add the Custom NuGet Source

Strawberry packages are hosted on a private NuGet feed. You need to add this source to your NuGet configuration so that the dotnet CLI can find and restore the packages.

Run the following command in your terminal:

dotnet nuget add source https://nuget.sb-engine.ir/v3/index.json -n Strawberry

This command registers a new NuGet source named "Strawberry" pointing to nuget.sb-engine.ir. The -n flag gives it a friendly name so you can identify it later. After running this, any dotnet add package or dotnet restore command will also check this source for packages.

Note: If you ever need to verify your configured sources, run dotnet nuget list source.

2.2 Create the Solution and Projects

We will create a solution with two projects. This separation is intentional and follows a pattern commonly used in game development:

• MyFirstGame — This is your shared game logic project. It contains your game context, scenes, entities, components, and all gameplay code. By keeping this in a separate project (rather than putting it directly in the desktop app), you make it possible to reuse the same game logic across different platforms (Desktop, Android, WebAssembly, etc.).

• MyFirstGame.Desktop — This is the desktop launcher project. Its only job is to bootstrap and run your game on a desktop platform (Windows, macOS, or Linux). It references your game project and the desktop-specific Strawberry package.

Let's create everything step by step.

Step 1: Create a directory for your project

mkdir MyFirstGame
cd MyFirstGame

Step 2: Create a solution file

dotnet new sln -n MyFirstGame

This creates a file named MyFirstGame.sln in the current directory. The solution file acts as a container that groups your projects together.

Step 3: Create the shared game project

dotnet new classlib -n MyFirstGame

This creates a class library project called MyFirstGame. We use a class library (not a console app) because this project is not meant to be run on its own — it provides the game logic that will be consumed by platform-specific launcher projects.

Step 4: Create the desktop launcher project

dotnet new console -n MyFirstGame.Desktop

This creates a console application project called MyFirstGame.Desktop. This will serve as the entry point that launches your game on desktop platforms.

Step 5: Add both projects to the solution

dotnet sln add MyFirstGame/MyFirstGame.csproj
dotnet sln add MyFirstGame.Desktop/MyFirstGame.Desktop.csproj

Step 6: Add the Strawberry package to MyFirstGame

cd MyFirstGame
dotnet add package Strawberry
cd ..

This adds the core Strawberry package to your shared game project. This package contains all the fundamental types: Game, GameContext, Scene, Entity, Component, graphics, physics, sound, and more.

Step 7: Add Strawberry.Desktop and a reference to MyFirstGame in the desktop project

cd MyFirstGame.Desktop
dotnet add package Strawberry.Desktop
dotnet add reference ../MyFirstGame/MyFirstGame.csproj
cd ..

The Strawberry.Desktop package contains the platform-specific backend for desktop operating systems — it handles window creation, input processing, OpenGL context setup, and the game loop for Windows, macOS, and Linux. The project reference to MyFirstGame allows the desktop project to access your game context class and all the game logic you write.

2.3 Final Project Structure

After completing all the steps above, your directory should look like this:

MyFirstGame/
├── MyFirstGame.sln
├── MyFirstGame/
│   ├── MyFirstGame.csproj
│   └── Class1.cs
└── MyFirstGame.Desktop/
    ├── MyFirstGame.Desktop.csproj
    └── Program.cs

3. Implementation

Now comes the exciting part — writing your first game code! We will create a minimal game that opens a window and displays an empty scene with a background color. This is the simplest possible Strawberry game, and it serves as the foundation you will build upon.

3.1 MyFirstGame — The Game Context

In Strawberry, the game context is the heart of your game. It defines how your game is initialized, updated, and rendered. You create a class that inherits from StdGameContext and override its methods to set up your scenes, entities, and systems.

Open the MyFirstGame project and delete the auto-generated Class1.cs file — we don't need it. Then create a new file called MyGameContext.cs inside the MyFirstGame project directory with the following content:

using Strawberry.Components;
using Strawberry.Core;
using Strawberry.Graphics;
using Strawberry.Graphics.Layers;
using Strawberry.Graphics.ParticleSystem;
using Strawberry.Graphics.Text;
using Strawberry.Math;
using Strawberry.Sound;
using Strawberry.Sound.Midi;
using Color = Strawberry.Graphics.Color;

namespace Strawberry.Test
{
    public class MyGameContext : StdGameContext
    {
        public const float ppm = 32f;

        public MyGameContext() : base(1280, 720)
        {

        }

        public override void OnInitialize(IGameLauncher laucnher)
        {
            base.OnInitialize(laucnher);

            var size = GraphicsContext.GetScreenSize();
            Viewport viewport = new Viewport("Default", new Vector2(), size, new Vector2(), new Vector2(1280, 720));

            Scene scene = new Scene("Main", 1280, 720);
            scene.ClearColor = Color.CornflowerBlue;
            AddScene(scene);
            SetScene("Main");
            scene.Viewports[0] = viewport;
        }
    }
}

Let's break down what each part does:

Constructor — base(1280, 720)

public MyGameContext() : base(1280, 720)

The base constructor of StdGameContext takes two integers representing the virtual resolution of your game — in this case, 1280 pixels wide and 720 pixels tall. This is the coordinate space your game logic operates in, regardless of the actual window size on screen. Strawberry will automatically scale the rendering to fit the real window while maintaining the aspect ratio defined by this virtual resolution.

ppm — Pixels Per Meter

public const float ppm = 32f;

This constant defines how many pixels correspond to one meter in the physics world. A value of 32 means 32 pixels = 1 meter. This is used by the physics system to convert between pixel coordinates and physical units. While we are not using physics in this minimal example, it is a good practice to define this constant early.

OnInitialize — Game Setup

The OnInitialize method is called once when the game starts. This is where you create your scenes, viewports, layers, entities, and everything else your game needs. Let's look at each line:

var size = GraphicsContext.GetScreenSize();

This retrieves the actual screen size (or window size) from the graphics context. We use this to size our viewport appropriately.

Viewport viewport = new Viewport("Default", new Vector2(), size, new Vector2(), new Vector2(1280, 720));

A Viewport defines a rectangular region of the screen where a scene is rendered. The constructor takes five parameters:

Scene scene = new Scene("Main", 1280, 720);

A Scene is a container for all the objects in your game — entities, layers, physics, and viewports. The constructor takes a name and the virtual resolution. You can have multiple scenes (e.g., a menu scene, a gameplay scene, a credits scene) and switch between them.

scene.ClearColor = Color.CornflowerBlue;

The clear color is the background color that fills the screen every frame before any objects are drawn. Color.CornflowerBlue is a pleasant light blue — a classic choice for game backgrounds. You can set this to any color you like.

AddScene(scene);
SetScene("Main");

AddScene registers the scene with the game context. SetScene tells the engine which scene should be active and rendered. In this case, we set "Main" as the active scene immediately.

scene.Viewports[0] = viewport;

Every scene has a collection of viewports. By assigning our viewport to index 0, we make it the primary (and in this case, only) viewport for this scene. The scene will render through this viewport.

3.2 MyFirstGame.Desktop — The Entry Point

Now let's set up the desktop launcher. Open MyFirstGame.Desktop/Program.cs and replace its contents with the following:

using Strawberry.Test;

namespace Strawberry.Desktop.Test
{
    internal static class Program
    {
        /// <summary>
        ///  The main entry point for the application.
        /// </summary>
        [STAThread]
        static void Main()
        {
            MyGameContext gameContext = new MyGameContext();
            Game game = new Game();
            game.Run(gameContext, new GameLauncher(false));
        }
    }
}

Here is what each part does:

[STAThread]

This attribute marks the main thread as a Single-Threaded Apartment thread, which is required by some desktop windowing systems (particularly on Windows). It ensures that the COM components used by the windowing and rendering subsystems work correctly. Always keep this attribute on your Main method in desktop projects.

MyGameContext gameContext = new MyGameContext()

We create an instance of our game context — the class we defined earlier. This object contains all our scene setup, initialization logic, and update logic.

Game game = new Game()

The Game class is the engine's main runtime. It manages the game loop, timing, and coordinates between the game context and the platform-specific backend.

game.Run(gameContext, new GameLauncher(false))

This starts the game. It takes two parameters:

• gameContext — our game context, which tells the engine how to initialize and update the game
• new GameLauncher(false) — a GameLauncher instance configured for desktop. The false parameter means the game will not run in headless mode — it will open a visible window with full rendering. A headless mode (true) would run without a window, which is useful for automated tests or server-side simulations.

3.3 Important: Platform-Specific Launchers

The code above uses GameLauncher, which is the desktop-specific launcher. It creates a native window, sets up an OpenGL context, and processes desktop input (keyboard, mouse, gamepads). This launcher will only work on Desktop platforms (Windows, macOS, and Linux).

Strawberry supports multiple platforms, and each platform has its own launcher type:

To target a different platform, you would create a separate launcher project (similar to MyFirstGame.Desktop) that references the same MyFirstGame shared project but uses the platform-specific launcher. For example:

• MyFirstGame.Android — would use AndroidLauncher and build as an Android application
• MyFirstGame.Web — would use WebLauncher and compile to WebAssembly

This separation of concerns — keeping your game logic in a shared project and platform bootstrapping in separate launcher projects — is a key architectural pattern in Strawberry. It allows you to write your game once and deploy it to multiple platforms with minimal changes.

3.4 Running the Game

To build and run your game, open a terminal in the MyFirstGame root directory (where the .sln file is) and run:

dotnet run --project MyFirstGame.Desktop

If everything is set up correctly, you should see a window open displaying a cornflower blue screen. Congratulations — you've just built and run your first Strawberry game!

From here, you can start adding entities, components, sprites, physics, sound, and all the other features Strawberry provides to build your game. Check the rest of the documentation for guides on each system.

Happy game development with Strawberry!