Papaltine.FluxSDK 0.17.0-beta

Flux SDK

An ecosystem to make creating and editing ProtoFlux in and out of Resonite faster and more maintainable.

Components of the SDK:

• 🛠️ ProtoGraph: Intuitive text based language for writing code that is analogous to ProtoFlux
• ✅ Tool(s) to compile ProtoGraph to a Resonite record that can be imported
• ✅ Tool in game for linking imported flux to game refs/drives
• ✅ Tool to format ProtoFlux nodes
• 📋 Tool to optimize the performance of ProtoFlux programs
• 📋 Tool to parse Resonite ProtoFlux into an IL for optimization
• 📋 LSP support for ProtoGraph
• 📋 Tool to simulate/run/test/debug Flux in an IDE

Project-wide Requirements:

• It should be flexible enough to adapt to changes and new features in the Froox engine.
• If the user writes code that comiles, the toolchain should produce semantically correct Resonite files with nice looking ProtoFlux.
• Integration among tools. Either use compatible runtime (.NET) or use well defined APIs between tools (ex: protobuf).
• While not a component itself, a common IL needs to be agreed upon that can work as an intermediary for the other tools. This is likely to be a digraph of some similar to what kittysquirrel has done with the formatter.

Setup

Running

• Install the dotnet (.NET 9) runtime environment to be able to run the program. You can run dontnet --info to verify that you have a .NET 9.X runtime installed.
• Install the dotnet tool Papaltine.FluxSDK: dotnet tool install --global --version <version_number> Papaltine.FluxSDK
  • If you want to install it manually, download the zipped bundle from the current FluxSDK release and unzip it into a directory on your computer. There should be a bunch of .dll files including the flux-sdk.dll which is the dotnet executable program.
• Find the Resonite DLL folder. There are several ways you can point to it:
  • If it is in a default path, flux-sdk may be able to find it automatically! If it is unable to find the DLLs when you run the compiler then you can do one of the following...
  • Set the RESONITE_MANAGED_DATA_PATH environment variable to the directory of the Resonite managed data
  • Use the -L flag at runtime to specify the path to the DLLs
  • Copy the .dll files from your Resonite folder (Resonite) into the same directory where you unzipped the bundle.
• Run the compiler using flux-sdk
  • To build a ProtoGraph file, your CLI command should look like flux-sdk build <path_to_protograph_file>
  • see the --help for information on each of the arguments.
• Other commands exist to convert Resonite record documents to JSON and generate a YAML file with the nodes available in ProtoGraph.
• Report issues here or contact Papaltine through Resonite with feedback, bugs, and requests.

Coding ProtoGrap(λ) (VSCode)

A basic extension for ProtoGraph (syntax highlighting) is provided in the protograph directory. While it is in development or to get the latest features, you can install the extension by installing the VSIX extension available to download from the releases page.

Read the ProtoGraph documentation to learn how ProtoGraph works and how to program in it.

Build & Develop from Source

These are instructions for building from source for contributors. If you just want to use Flux SDK to write and build ProtoGraph, the see the above sections.

• Clone the repository
• Open with an IDE or editor. I recommend something that works well with .NET projects like Rider, Visual Studio, or VSCode.
• Install any additional tooling/plugins that you need for F#/C# development
• Copy the Resonite dynamically linked libraries to a new folder in the project root called FrooxDll. They should be added as assembly references to the FrooxNodes project.
• When debugging, add the -L <Path_to_Froox_Dll> and -t <template> arguments to your command line arguments so that they are found at runtime correctly.

Contributing

Contact Papaltine on Resonite in game or on the Discord if you are interested in contributing.

Why?

ProtoFlux has many unique features as a language such as a good visual representation, real-time collaborative editing, and a relatively small barrier to entry; however, it has some limitations that could be mitigated with a good text based counterpart and related programming tooling. This would be most effective if the SDK were built to be flexible and complement planned features for ProtoFlux.

The first is maintainability. As ProtoFlux programs become larger, they become dramatically harder to navigate and update. A text based language can offer IDE tooling to provide the assistance that developers have come to expect when working on anything complex. Some future features like collections, nested nodes/functions, and especially wasm integration will partially address this issue from different perspectives.

Collections and functions will bring ProtoFlux closer to parity with other languages, but it will still lack the tooling that is needed for complex programs. Not to mention that some people prefer to read/write text based code sometimes and use a visual representation others.

WASM will work from the other direction by allowing people to bring all the goodies and performance from other ecosystems to ProtoFlux, but this will be mediated through an API that will add mental overhead and restrictions on what can be done from the source language. A good comparison is with the web: even though many things will be written in wasm and distributed to browsers, JS will certainly still be prevalent throughout as a glue language. WASM code also has the limitation that when running in Resonite, it will be difficult/impossible to debug and modify the code in a session with others in a way that is as integrated as ProtoFlux.

Repository Structure

• FluxSDK.[ProjectName]: Project relating to a specific function of the SDK. An additional .C/.F is added at the end if the code for that project is split between F# and C# code (they cannot exist in the same .NET project).
• Test.[ProjectName]: Unit tests for the relevant project
• Examples/*: A collection of example ProtoGraph programs
• protograph: VSCode extension folder. A subproject for providing basic IDE support.
• Wiki/Documentation: The wiki is actually a 'separate' repository that can be viewed here. Clone it locally from https://git.samsmucny.com/ssmucny/Flux-SDK.wiki.git.

Helpful Resources

• Elm: Compiler errors for humans and compilers as assistants
• History of Programming Languages: LabVIEW
• Boundaries of Language Design
• Things to Steal from Unison
• F# language spec see appendix A for summary of grammar
• Modern Compiler Construction (LSP/Rosyln/Microsoft Research)
• Modernizing Compiler Design for Carbon Toolchain - Chandler Carruth
• Gradual typing for Ruby at Scale with Sorbet - Dmitry Petrashko
• Notes on GHC (Haskell compiler)
• Understanding parser combinators: a deep dive - Scott Wlaschin
• F# for C# programmers - Scott Wlaschin
• F# async expressions (composable async/await)

Because Resonite is in .NET, a lot of the conventions and oddities from the ecosystem bleed into ProtoFlux

• F# style guide on names
• C# style guide on names