How to edit/debug the Stride Engine code?

[jasonswearingen]

UPDATE: SEE METHOD 3 FOR "BEST" SOLUTION #1116 (comment)

Method 1: add your game to Stride.sln

Steps I have taken that works

1. Add a game project to Stride.sln
2. In the solution properties, Add the Stride.GameStudio project to your game dependencies (build order). So the Stride engine builds fully before your game gets built
3. Make sure your game project build/runs properly within the Stride.SLN
4. Set Nuget PackageManager Settings to PackageRestore "Allow download Missing" + "Auto check missing during build".
   • a lot of my build problems came from Clean-->Rebuild.
   • IMPORTANT NOTE The exact detail here is a bit uncertain. You need the nuget reference in the project (so your game project will compile) but those nuget dll's should not be in the \bin\Debug\netstandard2.0 output folder otherwise those dll's will be used at runtime. (If those arn't there, it seems visual studio is smart enough to use the Stride projects at runtime). Again, not exactly sure the steps here, but this is close.....
5. Ensure that the game project nuget references point to the same version that the Stride.sln builds.
   • The best way to ensure this is to run the Stride.GameStudio project from the Stride.sln and use that to create a game project.
   • Use that newly created game project as your starting point, as you can be sure it will reference the same versions built by Stride.

Using this method, you can:

• Debug into the Stride engine source
• modify stride engine source and it's used by the game. (this includes hot reload)
• set a breakpoint in the stride source and it will work

Using this method, you can not:

• You can not navigate to the engine source from your source code. It will show decompiled Nuget sources.
  • HOWEVER If you install Resharper, it can properly navigate to the sources. I had to choose "go to implementation" for it to kick in. (Tested using Resharper EAP for VS2022)

Known issues:

1. The build process is brittle. sometimes the build will start failing, seemingly for no reason. I have found this to be caused by:
   • some build system executables to be hung. I have found VBCSCompiler.exe hanging often. Close Visual Studio, Open task manager and terminate anything msbuild* vs*.
   • If that doesn't work, try deleting the repo files (to clear temp build artifacts) then reset your repo to the last checked in files.
     • update: lately I've been using git clean -fx -d to great success solving build errors. That deletes all untracked files from your repo.
   • If that doesn't work, try restarting the computer
2. Your game project build fails, but engine project builds fine. I think I ran into this issue by not setting Project build order properly (now listed in the above steps). I worked around this by:
   • unload game projects
   • build engine
   • load game projects
   • build the game library project
   • build the game entrypoint project

Method 2: Stride.sln side-by-side

see Tebjan reply below. Also see https://www.youtube.com/watch?v=bXSC9o-EaR8

What does not work

1. Replacing the Nuget references with project references to the Stride Engine projects. The Stride build system changes the output locations and Visual Studio project references can not find the binaries properly

Wish list

1. Simple windows-only Stride engine build that does not include the complicated build system.
   • much easier intro to the engine. would greatly simplify things for potential contributors
2. Ability to reference Engine source Projects.
   • allow easier code navigation from game source

Additional Resources

I didn't find these helpful but maybe you will....

• https://github.com/stride3d/stride/wiki/SettingUpSourceDebugging

[tebjan]

Thanks for starting this discussion, it's definitely asked frequently.

From an engineering standpoint, you shouldn't modify the Stride solution to debug it.

The clean approach is:

• build Stride locally
• reference that version in a game project
• open the game project in a second instance of visual studio

Now you can step into each method with F11 while you are debugging. Visual studio should automatically find the Stride source files.

If you want to hit a specific breakpoint in the Stride solution, start the game without a debugger and attach the visual studio instance with the Stride solution to the running game.

So you need a local build of stride and then you can set the stride version of any game to that version to compile with the local build of stride. Just make sure that you have started game studio one time so the nuget restore of game studio did happen.

This is how we do it in our workflow and as far as I know, the original authors of Stride too.

Hope that helps...

[najak3d]

@tebjan : You say "adjust in AssemblyInfo.cs" of which there are about 100 files named this. Do you mean "sources/shared/SharedAssemblyInfo.cs" for the line that reads:

 public const string PublicVersion = "4.1.0.1";

This is what I'm going to try first.

[najak3d]

When I edited that to 4.1.0.2 -- I got all sorts of issues form Stride3D Game Studio when I started it up. Nuget resolver issues.

So I put it back to 4.1.0.1 - -and it compiles/runs fine, and Source Link lets me step into the code. (However "Go to Definition" when not debugging does not work.)

For setting a breakpoint on "startup" from Stride solution, is that possible here? I think not, since it requires me to "start it outside of VS2022 stride solution" and then use "Attach to process" to debug it -- at which point, It's too late.

I can get around this though, by stepping into the code manually via F11 -- and then it does allow me to set BP's at that point -- but I have to manually F11 to the right place ONCE first, for this to work. I'm unsure of other workarounds for this (but this only really applies to startup debugging, nothing else).

[XiaochaoYan]

Thanks for starting this discussion, it's definitely asked frequently.

From an engineering standpoint, you shouldn't modify the Stride solution to debug it.

The clean approach is:

• build Stride locally
• reference that version in a game project
• open the game project in a second instance of visual studio

Now you can step into each method with F11 while you are debugging. Visual studio should automatically find the Stride source files.

If you want to hit a specific breakpoint in the Stride solution, start the game without a debugger and attach the visual studio instance with the Stride solution to the running game.

So you need a local build of stride and then you can set the stride version of any game to that version to compile with the local build of stride. Just make sure that you have started game studio one time so the nuget restore of game studio did happen.

This is how we do it in our workflow and as far as I know, the original authors of Stride too.

Hope that helps...

Regarding the step 2 "reference that version in a game project", I not sure about what files should I add to my own game soltuion. VisualStudio 2022 seems to only support adding another project but not soltuion (.sln) files to exisiting soluion.

[jasonswearingen]

Method 3: Stride.Runtime.sln in your game solution

Note: You still want to follow Method1 steps 4 and 5 before doing this.

It turns out that my outlined 'method 1' works only for debugging, not for editing engine code. When you edit engine code the nuget build/deployment process part of the build system gets confused when you add a game project to Stride.sln and your game project will get errors like Package Stride can not be found even though you don't reference a Stride nuget or project in your game. (Your game has nuget references things like Stride.Engine instead)

The work around is to add Stride to your game project. Steps:

• Open YourGameProject.sln
• choose add project, and add Stride/Build/Stride.Runtime.sln
  • This will add all the stride runtime projects into your game solution
• Open your solution configuration manager, and set all the stride projects to not build

The above steps lets you set breakpoints and setp into the engine code. To modify you should open either Stride.sln or Stride.Runtime.sln in a seperate VS instance and edit/build there, then after that finishes building be sure to REBUILD your game solution. Failing to do so will not update the stride engine nuget packages properly.

[TheKeyblader]

Since a certain version of VS2019, vs doesn't allow you to select sln file in add project dialog.

[tebjan]

I would also not advise that.

[TheKeyblader]

Method 4: Local NuGet package sources.

I use this method mostly to edit stride source code.

When Stride is built you get a folder packages at Stride repo root/bin/packages.
This package contains all nugets of stride with your edited code.

To use these NuGets.

1. Add new package source named stride.local that point to this folder with
   • Tools > Options > NuGet Package Manager > Package Sources
   • nuget.config
2. Add or edit nuget.config file with

<?xml version="1.0" encoding="utf-8"?>
<configuration>
	<packageSourceMapping>
		<!-- key value for <packageSource> should match key values from <packageSources> element -->
		<packageSource key="nuget.org">
			<package pattern="*" />
		</packageSource>
		<packageSource key="stride.local">
                        <package pattern="Stride" />
			<package pattern="Stride.*" />
		</packageSource>
	</packageSourceMapping>
</configuration>

3. Don't forget to have the same version references of the packages folder.

This config file will map Stride NuGet to the local folder.

When you edit stride source just generate to update local NuGets and rebuild your project to refresh visual studio cache.

I haven't tested debugging. I think attaching to process with Stride solution should be ok.

[najak3d]

Which of these 5 methods posted here is the best? (or which is the best for each context type?)

[tebjan]

The one in my answer from Aug 19 '21 is the "official" way to do it. It is the least intrusive: #1116 (comment)