Table of Contents

Create a File-Based App

A .NET 10 file-based app is a single .cs file with no .csproj: the packages it needs are declared at the top of the file with #: directives, and dotnet run Program.cs builds and runs it. It is the shortest route from an empty folder to a Stride window with a scene, and suits experiments, teaching snippets and bug reproductions.

The regular Create Project steps still apply when you want a .csproj - an IDE solution, several files, content that needs copying to the output. dotnet project convert turns a file-based app into that project; see Growing into a project.

Note

Requires the .NET 10 SDK. Visual Studio does not build file-based apps; run them from the command line or the Visual Studio Code terminal. Everything else in Getting Started applies.

C# only. File-based apps are a C# compiler feature - dotnet run Program.fs does not recognise the file, and an F# script under dotnet fsi cannot run Stride because the asset compiler only runs as part of a project build. For F# and Visual Basic create a project as in Create Project; the F# examples and VB examples show the code.

Steps

  1. Create a folder for the app and go into it. One app per folder - the reason is below.

    mkdir MyStrideApp
    cd MyStrideApp
    
  2. Create Program.cs with the directives and the scene:

    #:package Stride.CommunityToolkit@1.0.0-preview.69
    #:package Stride.CommunityToolkit.Bepu@1.0.0-preview.69
    #:package Stride.CommunityToolkit.Skyboxes@1.0.0-preview.69
    #:property PublishAot=false
    
    using Stride.CommunityToolkit.Bepu;
    using Stride.CommunityToolkit.Engine;
    using Stride.CommunityToolkit.Rendering.ProceduralModels;
    using Stride.CommunityToolkit.Skyboxes;
    using Stride.Core.Mathematics;
    using Stride.Engine;
    
    using var game = new Game();
    
    game.Run(new SceneSetup3D().UseBepu().UseSkybox(), start: Start);
    
    void Start(Scene rootScene)
    {
        var entity = game.CreatePrimitive(Primitive3D.Capsule());
        entity.Transform.Position = new Vector3(0, 8, 0);
        entity.Scene = rootScene;
    }
    

    Use the toolkit version that matches your Stride - see the table in Getting Started.

  3. Run it:

    dotnet run Program.cs
    

    The first run restores the packages and compiles the engine's shaders, so it takes a while; later runs are quick.

The scene is the same one the Create Project page walks through line by line.

What the directives do

Directive Meaning
#:package Name@Version A NuGet package reference. Stride.CommunityToolkit brings in Stride itself and the asset compiler; Bepu adds physics; Skyboxes adds the photographed sky, UseSkybox(). With a Linux distribution's own dotnet package, add Stride.CommunityToolkit.Linux as well; see the Linux tab of Create Project.
#:property Name=Value An MSBuild property, as if written in a .csproj. PublishAot=false is there because file-based apps publish as native AOT by default and Stride is not AOT-compatible; without it every build carries the trimming and AOT analyser warnings.
#:project ../path/To.csproj A project reference. The toolkit's own file-based example uses this to build against the toolkit source instead of a package.

One app per folder

Stride's asset compiler collects shaders and assets from the app's directory downwards. A file-based app sitting in a folder with other Stride code sees all of it as its own; in the toolkit's examples folder, for instance, it fails on two examples that ship shaders with the same name. Give each app its own folder.

Where the build output goes

There is no obj/ or bin/ next to the file: the SDK keeps them in its own temporary build cache, which is what keeps the folder to one file. To get the output next to the file - to inspect the compiled data/ folder, say - add two directives:

#:property BaseIntermediateOutputPath=obj\
#:property OutputPath=bin\

Growing into a project

dotnet project convert Program.cs

writes a .csproj next to the file with the same packages and properties, and removes the #: lines. From there it is a normal code-only project: open it in an IDE, add files, add it to a solution.

See it in the toolkit

examples/code-only/E01_3D_BasicScene_FileBasedApp/Program.cs is this scene as a file-based app, built against the toolkit source with #:project references; the example page describes it. Because it has no .csproj it is not part of the solution and is run from the command line; from the repository root use dotnet run --file <path>, because the root holds Stride.CommunityToolkit.ndproj, which dotnet run would otherwise take for the project.

ProgramEngineOnly.cs in the same folder is the scene with no toolkit package at all - see Create a File-Based App - Engine Only.