How "options.ScriptingAPI.SystemReferences" actually works

Scripting
#1

From v1.7 there is a Tip added to Multithreading example code.

Add options.ScriptingAPI.SystemReferences.Add("System.Threading.ThreadPool"); in Setup function inside your Game.Build.cs to properly reference threading lib.

At first I thought it was like adding a GAC assembly reference to CS project like .net Framework, but it wasn’t. .Net 7’s project was already including System.Threading.Thread assembly in default,
and in Visual Studio main game csproj was built with no problem.

But in editor (hot reloading) CS0103 error occured-

[ 00:02:31.405 ]: [Info] Compiling Y:\MTTest\Binaries\GameEditorTarget\Windows\x64\Development\Game.CSharp.dll
[ 00:02:31.601 ]: [Info] Y:\MTTest\Source\Game\MTTest.cs(21,9,21,19): error CS0103: The name ‘ThreadPool’ does not exist in the current context
[ 00:02:31.606 ]: [Info] Task C:\Program Files\dotnet\dotnet.exe exec “C:\Program Files\dotnet\sdk\7.0.401\Roslyn\bincore\csc.dll” /noconfig /shared @“Y:\MTTest\Cache/Intermediate\GameEditorTarget\Windows\x64\Development\Game.CSharp.response” failed with exit code 1

1 task failed

and error disappeared successfully after adding options.ScriptingAPI.SystemReferences.Add(“System.Threading.ThreadPool”) just as manual said.

I examined Game.csproj project file but nothing was changed - so it is purely about engine specific compilation (cooker?).

What exactly options.ScriptingAPI.SystemReferences does with the engine? And how we know when to add, and which string to be added?

#2

SystemReferences gives the build tool info about which C# STD libs are used but the compiler. We could reference all of them but that would increase build times. Maybe in future, we could improve it, for now, you need to explicitly say which lib you’d like to use in your game code.

Also, Flax Game Cooker supports stripping unused C# libs from class library when building game (optional via Build Settings SkipUnusedDotnetLibsPackaging checkbox) which ships the game with C# DLLs that are actually used by Game, Plugins and Engine.

#3

Okay, then does SystemReferences list aquire the names of actual DLL files?

Because ThreadPool class of .Net 7 is inside of assembly (project reference) named as

System.Threading.Thread

and it is inside of DLL file named as

System.Threading.ThreadPool.dll

and Add method gets string of

Add(“System.Threading.ThreadPool”)

For in case of adding other standard libraries, I wanted to know this.

#4

Tested a little more with example of Can I use System.Data.DataTable in my C# scripts?…

ThreadPool :

  • namespace : System.Threading
  • Assembly file in MSDN : System.Threading.ThreadPool.dll
  • dll file also exists in .Net : System.Threading.dll
-> Proper SystemReference : options.ScriptingAPI.SystemReferences.Add("System.Threading.ThreadPool");
-> SystemReference creating Error : options.ScriptingAPI.SystemReferences.Add("System.Threading");

= Only assembly file name works

Datatable :

  • namespace : System.Data
  • Assembly file in MSDN : System.Data.Common.dll
  • dll file also exists in .Net : System.Data.dll
-> Proper SystemReference : options.ScriptingAPI.SystemReferences.Add("System.Data");

= Namespace string? or Alternative DLL filename?

So it is pretty confusing what string should be assigned for flax engine reference… It is not clear referring to MSDN.