> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/flatredball2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/flatredball2/flatredball-2/readme.md). # Setup This page covers everything needed to get a FlatRedBall2 project running: prerequisites, the supported quick-start path, and a manual reference for wiring the engine into an existing project. ## Prerequisites FlatRedBall2 requires the **.NET 10 SDK**. Before running any `dotnet` command below, verify it is installed and on your PATH: ``` dotnet --version ``` You should see a version starting with `10.` (e.g. `10.0.100`). If you instead see: * `'dotnet' is not recognized as the name of a cmdlet...` (PowerShell) or `dotnet: command not found` (bash) — the SDK is not installed, or its install directory is not on your PATH. * A version older than `10.` — you have an older SDK; install .NET 10 alongside it (side-by-side installs are supported). See [Installing .NET 10](#installing-net-10) below for platform-specific instructions. ### Installing .NET 10 FlatRedBall2 requires the **.NET 10 SDK**. If `dotnet --version` isn't found or shows an older version, install it: **Windows** — installer from , or via winget: ``` winget install Microsoft.DotNet.SDK.10 ``` **macOS** — same download page, or via Homebrew: ``` brew install --cask dotnet-sdk ``` **Linux** — Microsoft's install script (works on any distro): ``` curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0 ``` Or follow distro-specific instructions at . > **Restart your terminal after installing** — installers add `dotnet` to PATH, but existing terminal sessions won't see it. Close and reopen your terminal (or restart the editor if using VS Code / Rider). Then run `dotnet --version` to confirm `10.x`. ## Quick Start ### Step 1 — Install the project template Run this once (and again before any new project to pick up template updates): ``` dotnet new install FlatRedBall2.Templates ``` ### Step 2 — Create your game Pick a name and run from the directory where you want the project folder created: ``` dotnet new frb2-desktop -n YourGameName ``` This creates a `YourGameName/` folder with two projects inside: * `YourGameName.Common/` — your game code (screens, entities), shared across all targets. * `YourGameName.Desktop/` — the desktop entry point that references `Common` (KNI, SDL2/OpenGL). > **Targeting the browser too?** Use `frb2-multiplatform` instead of `frb2-desktop`. See [Multi-platform (Desktop + Web)](#multi-platform-desktop--web) below. The new project's `Content/` folder is pre-populated with starter assets (animation chains, a base `.tmx` map and `StandardTileset`, and platformer/topdown JSON configs). To start with an empty `Content/` folder instead: ``` dotnet new frb2-desktop -n YourGameName --IncludeStarterContent false ``` The project name (`-n`) also sets the root C# namespace (the `RootNamespace` in each `.csproj`) by default. Pass `--namespace` to set a different one, e.g. if your studio name should be the namespace instead of the game's working title: ``` dotnet new frb2-desktop -n YourGameName --namespace MyStudio ``` ### Repo setup (`.gitignore`) Use `frb2-desktop` or `frb2-multiplatform` templates — they already include the recommended `.gitignore`. Manual baseline: ``` bin/ obj/ Content/obj/ .vs/ *.user *.suo ``` For web projects, keep the template's `wwwroot/Content/.gitignore` (that folder is build output). ### Step 3 — Build and run ``` cd YourGameName/YourGameName.Desktop dotnet run ``` A window opens showing "Hello from FlatRedBall 2" centered on a black background. If you see that, everything works. ### Step 4 — Start building Open `YourGameName.Common/Screens/GameScreen.cs`. The template creates a centered label to confirm rendering works — delete that block and replace it with your own code. **Core concepts:** * **Screen** — a game state (level, menu, game-over). `GameScreen` is your first one. * **Entity** — a game object (player, enemy, bullet). Create them through `Factory(this)` — never `new T()` directly. The engine handles rendering, physics, and collision automatically. Override `CustomInitialize` for one-time setup (factories, content, collision wiring) and `CustomActivity(FrameTime time)` for per-frame logic. For complete lifecycle rules see [`frb-skills/engine-overview/SKILL.md`](https://github.com/vchelaru/FlatRedBall2/tree/main/frb-skills/engine-overview/SKILL.md). Browse the [`samples/`](https://github.com/vchelaru/FlatRedBall2/tree/main/samples/README.md) directory for complete games. See [`frb-skills/`](https://github.com/vchelaru/FlatRedBall2/tree/main/frb-skills/README.md) for task-specific guides (entities, collision, animation, physics, and more). ### Multi-platform (Desktop + Web) ``` dotnet new frb2-multiplatform -n YourGameName ``` Same `--namespace` override as `frb2-desktop` above applies here too. This produces three projects sharing one `Common`: * `YourGameName.Common/` — game code (`net10.0`), shared by both heads. * `YourGameName.Desktop/` — desktop entry point (KNI SDL2/OpenGL, `net10.0`). * `YourGameName.BlazorGL/` — Blazor WebAssembly entry point (KNI, `net10.0`). Contains its own `App.razor`, `Pages/Index.razor`, `wwwroot/frb-host.js`, etc. — edit them freely; they're yours. Run the desktop head as before. To run the web head: ``` cd YourGameName/YourGameName.BlazorGL dotnet run ``` This launches a local dev server (default `https://localhost:5001`) — open the URL and the game runs in the browser canvas. Apos.Shapes' shader is embedded directly in the package assembly, so neither Wine nor a shader compiler is needed on macOS/Linux. `Game1.cs` is identical on both heads (it sets `GraphicsProfile.FL10_0`). Code that differs between desktop and web can branch at runtime on `OperatingSystem.IsBrowser()`. Browsers have no filesystem, so route save data through `Engine.Storage` and content reads through `TitleContainer` rather than `System.IO.File`. ### Building against a local engine checkout To build your game against FlatRedBall2 source instead of the NuGet packages (for example to debug into the engine or try an unreleased fix), clone the engine and pass its relative path when you create the project: ``` git clone https://github.com/vchelaru/FlatRedBall2.git dotnet new frb2-desktop -n YourGameName --EnginePath ../FlatRedBall2 ``` `--EnginePath` must be a path relative to the new `YourGameName/` solution folder, so `../FlatRedBall2` is a clone sitting next to it. Absolute paths are not supported: the template cannot reject them, and they produce references that do not resolve. The same parameter works with `frb2-multiplatform`. The generated `.csproj` files then use a `ProjectReference` to the engine's `src/FlatRedBall2.csproj` in place of the `FlatRedBall2.Kni` `PackageReference`, and the generated `.slnx` lists the engine projects. Without the parameter, the output is the NuGet-based project described above. To switch an existing project, edit it by hand. In `YourGameName.Common.csproj`, replace ```xml ``` with a `ProjectReference` whose path is relative to that `.csproj`: ```xml ``` Then add the engine projects (including `src\AnimationChain.Common\AnimationChain.Common.csproj`) to your `.slnx` so Visual Studio can restore them. If the project lives in a shared repository, the team must agree on where the engine clone lives, because the path is committed in the `.csproj` files. ## Manual setup (reference) The template above is the supported install path. If you have a reason to wire FlatRedBall2 into an existing project (e.g. you're integrating with a KNI or XNA-style project you already have), here's the minimum API surface — but note this snippet alone is **not** a complete working setup. You'll also need a configured KNI desktop project (SDL2.GL platform package, `Content/` folder, etc.) which the template handles for you. Inside an existing .NET project directory (one that already contains a `.csproj`): 1. Install the NuGet package: ``` dotnet add package FlatRedBall2.Kni # desktop and browser / Blazor WASM (.NET 10) ``` > Running `dotnet add package` outside a project folder fails with `Could not find any project in ` — it needs a `.csproj` in the working directory. 2. Set up `Game1.cs`: ```csharp using FlatRedBall2; using Microsoft.Xna.Framework; using Microsoft.Xna.Framework.Input; public class Game1 : Game { private readonly GraphicsDeviceManager _graphics; public Game1() { _graphics = new GraphicsDeviceManager(this); Content.RootDirectory = "Content"; FlatRedBallService.Default.PrepareWindow(_graphics); } protected override void Initialize() { base.Initialize(); FlatRedBallService.Default.Initialize(this); FlatRedBallService.Default.Start(); } protected override void Update(GameTime gameTime) { if (Keyboard.GetState().IsKeyDown(Keys.Escape)) Exit(); FlatRedBallService.Default.Update(gameTime); base.Update(gameTime); } protected override void Draw(GameTime gameTime) { FlatRedBallService.Default.Draw(); base.Draw(gameTime); } } ``` 3. Create a `GameScreen` class: ```csharp using FlatRedBall2; public class GameScreen : Screen { public override void CustomInitialize() { // set up your entities and shapes here } public override void CustomActivity(FrameTime time) { // called every frame; put game logic here } public override void CustomDestroy() { // called when the screen is removed } } ``` See the `samples/` directory for complete working examples. ## Troubleshooting **`FileNotFoundException: Could not load file or assembly 'Xna.Framework...'`** — usually a stale package restore where a referenced project resolved a different KNI version than what's copied to the output folder. Try this first: ``` dotnet clean dotnet restore ``` If it persists, delete `bin/` and `obj/` in both the failing project and any project it references, then rebuild. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flatredball.com/flatredball2/flatredball-2/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.