Yotsuba ShaderLearn

Plugins

2 min read

Install, update and use the plugins that add engine formats to the compiler.

The compiler ships with SPIR-V, GLSL, GLSL ES, HLSL, Metal and C++. Every other format is a plugin: a small NuGet package that teaches the CLI one more output. The plugins for MonoGame, KNI, FNA and Godot are available today.

A plugin is used only by the CLI, while it compiles. Your game does not reference it.

Using a plugin#

Ask for it with --target. The CLI downloads it the first time and checks for a newer version every time it runs:

dotnet yotsuba add MyShaders/MyShaders.csproj --target spirv --target monogame

Without internet, the CLI warns that it could not look for updates and uses the installed copy. If the plugin was never installed, the command fails.

The plugin command#

yotsuba plugin list | install <name> | update [name] | remove <name>
CommandWhat it does
plugin listPrints the plugins of the catalog and whether each one is installed and in which version.
plugin install <name>Downloads the latest version of the plugin before you need it. Does nothing if it is already the latest.
plugin update <name>The same as install: fetches the latest version.
plugin updateUpdates every plugin that is installed.
plugin remove <name>Deletes the installed plugin.

Exit codes: 0 on success, 1 when the plugin or the network fails, 2 for wrong arguments.

The catalog#

Plugin--targetNuGet packageOutputMethod generated by add
monogamemonogame (or mgfx)YotsubaShader.Extensions.MonoGame.mgfx, one per platformToMGFX(MonoGamePlatform)
knikni (or kni-webgl)YotsubaShader.Extensions.KNI.knifxToKNIWebGL_FX()
fnafnaYotsubaShader.Extensions.FNA.fxbToFNA_FX()
godotgodot (or gdshader)YotsubaShader.Extensions.Godot.gdshader, one per type (Spatial, CanvasItem)ToGodotShader(GodotShaderType)

Each entry of the catalog declares its name, description, package, extension, the method add generates, and optionally an options enum with its values and whether the result is text. add and compile read that entry to decide what to write.

Where things live#

WhatDefaultHow to change it
Installed plugins~/.yotsuba/plugins/<name>Set YOTSUBA_HOME to another folder.
Cataloghttps://yotsubashader.com/plugins.jsonSet YOTSUBA_PLUGINS_URL to a URL or a file path. The CLI keeps a copy in YOTSUBA_HOME and uses it when there is no connection.
NuGet feedhttps://api.nuget.org/v3-flatcontainer/Set YOTSUBA_NUGET_SOURCE to a private or test feed.

What a plugin is made of#

A plugin package contains an assembly with a class that implements IShaderTargetBackend. The CLI loads it in its own context, creates the class and calls its Compile method once per shader (and once per option, when the plugin has options). Compile receives the compiled shader and the numeric value of the option, and returns the bytes of the file. For text formats, those bytes are UTF-8 text.

For the engine-specific details of each plugin (how the engine loads what it generates, vertex data, uniforms), see MonoGame, KNI, FNA and Godot.

The commands that use plugins are 0 and 1.