dev.UsingMainBranch - tooll3/t3 GitHub Wiki

Switching from dev to main-branch might come with some hickups.

• Switch branch with Rider or Fork
• Pull with rebase
• Rider -> Build -> Clean Solution
• Clear all obsolete compilation directories (e.g. bin/ or obj/)

when trying to build you get the following build warning:

CONSOLE: A compatible .NET SDK was not found.
CONSOLE: Requested SDK version: 8.0.204
CONSOLE: global.json file: C:\Users\pixtur\dev\tooll\t3\global.json
CONSOLE: Installed SDKs:
CONSOLE: Install the [8.0.204] .NET SDK or update [C:\Users\pixtur\dev\tooll\t3\global.json] to match an installed SDK.
CONSOLE: Learn about SDK resolution:
CONSOLE: https://aka.ms/dotnet/sdk-not-found

1>ImguiWindows.csproj: Warning  : Unable to locate the .NET SDK version '8.0.0' as specified by global.json, please check that the specified version is installed.
1>Microsoft.NET.Sdk.DefaultItems.targets(128,5): Error NETSDK1141 : Unable to resolve the .NET SDK version as specified in the global.json located at C:\Users\pixtur\dev\tooll\t3\global.json.

As the error explains this is probably because you do not have .NET 8's SDK installed. You can list the installed versions by opening a command prompt (e.g. tapping WIN-key and search cmd) and running the following command:

dotnet --list-sdks

If the output does not show a .NET version 8.0.0 or higher as it does below, follow the hyperlink above to install it. You may need to restart your IDE or t3 once you've done so.

C:\Users\pixtur>dotnet --list-sdks
5.0.302 [C:\Program Files\dotnet\sdk]
6.0.302 [C:\Program Files\dotnet\sdk]
6.0.401 [C:\Program Files\dotnet\sdk]
8.0.201 [C:\Program Files\dotnet\sdk]
8.0.300 [C:\Program Files\dotnet\sdk]

Switching between branches can be surprisingly difficult because there are hidden untracked and ignored files that will not show up in Fork's local changes list.

The simplest solution for this is a clean clone into a new folder. (or keeping both branches in separate folders).

Otherwise you'll have to...

• Remove all folders called obj and bin (use Total Commander or other file managers)
• In Fork enable "Show ignore files" with the icon in the right corner of the Unstaged Files panel
• Rider -> Build -> Clean Solution
• run Install/install.bat script
• Rider -> Tools -> Nuget -> Restore Package
• Build solution release to initialize Player.exe
• Build debug solution

Basically every project has the following subdirectories:

• Project/dependencies -> native dependencies, mostly unused
• Project/Resources - that project's resources of course, referenced via:

(in shaders it might need to be `\projectname/relativepath"

• Project/bin and Project/obj - .NET build directories, you can probably ignore these1
• Project/anything else is all folders relative to the project's RootNamespace

There are a few ways to use resources in T3 now. File paths work exactly the same in both typical operator slots and shader #include statements.

• relative path (not recommended - support will likely be removed) -> myShaders/pretty.hlsl
• "absolute" path /projectname/myShaders/pretty.hlsl
  • recommended to resolve file conflicts between projects with resources of the same name
  • safest by default
• ABSOLUTE path C:/Users/etc/pretty.hlsl
  • should be avoided, as you lose the benefits of project portability and certain file-related conveniences may not be supported

It is recommended to use VSCode's HlslTools extension. We have a json-generation system that directly complies with HlslTools to give you accurate syntax highlighting with our unique resource directory layout. Please let us know if this also works with Visual Studio's HlslTools extension if you have tried it!

Internally, the application works primarily in relative paths. These paths differ substantially to how resources worked before in the following ways:

• Paths are now relative to your project, not the t3 application directory
• It is no longer required (in fact, it is discouraged) to prefix relative paths with the term "Resources". This will still work for the sake of backwards compatibility, but this is only temporary
• Resources are now scoped (more on this later), which means your projects eill only have access to resourcrs it is permitted to.

Internally, resource paths are resolved on an instance-by-instance basis. By default, any given operator can have access to resources of the package it belongs to, and those of any of its parents' packages.

An operator can also access the resources of any package you have installed - be it your projects, a (future) nuget package, or built-in t3 packages, provided those packages have enabled Resource Sharing when they were created. Shaders are an exception to this rule - they are always shared.

Using resources from other packages will create dependencies on those packages in a future release.

With relative pathing, you run the risk of running into file conflicts. This is why, by default, the file path type-in uses the fully qualified relative path as referenced above (e.g. /lib/shaders/point.hlsl, as opposed to shaders/point.hlsl).

As best-practice, fully-relative file paths in the latter fashion should be reserved for resources within your own project, though for convenience this is not required.

Old-style file references, such as Resources/user/pixtur/shaders/myCoolShader.hlsl, still work for the sake of updating old projects. This will be removed in a future version of Tooll. Internally, the necessary conversion is done via a specific function in the ResourceManager class in a non-destructive way. Wherever possible, it is recommended to update these references to the new path style.

In your Operator script, there is a base class method:

protected bool TryGetFilePath(string relativePath, out string absolutePath, bool isFolder = false);

Use this method to resolve any paths written into your slot - you can do whatever you like with the resolved file path (though writing to the file is STRONGLY discouraged and will cause problems).

As an example:

internal class MyOperator : Instance<MyOperator>
{
    [Input(Guid = "C4E0FC8B-E017-4186-80AD-78A007ED1EF5")]
    public readonly InputSlot<string> Path = new();
    
    public MyOperator()
    {
        Path.UpdateAction = UpdatePath;
    }
    
    private void UpdatePath(EvaluationContext context)
    {
        if (!path.IsDirty)
            return;
        
        var path = Path.GetValue(context);
        
        if(!TryGetFilePath(path, out var absolutePath))
        {
            Log.Error($"File not found: {path}", this);
            return;
        }
        
        var fileText = File.ReadAllText(absolutePath);
    }
}