BorrowedTorch.Drivers 1.2.0

Prefix Reserved
dotnet add package BorrowedTorch.Drivers --version 1.2.0
                    
NuGet\Install-Package BorrowedTorch.Drivers -Version 1.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BorrowedTorch.Drivers" Version="1.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="BorrowedTorch.Drivers" Version="1.2.0" />
                    
Directory.Packages.props
<PackageReference Include="BorrowedTorch.Drivers" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add BorrowedTorch.Drivers --version 1.2.0
                    
#r "nuget: BorrowedTorch.Drivers, 1.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package BorrowedTorch.Drivers@1.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=BorrowedTorch.Drivers&version=1.2.0
                    
Install as a Cake Addin
#tool nuget:?package=BorrowedTorch.Drivers&version=1.2.0
                    
Install as a Cake Tool

BorrowedTorch.Drivers

Drivers for MonoGame: a value worked out every frame by a graph of nodes - inputs, logic, maths, memory and timers, and animations started, reversed and stopped by pulses. A lamp brighter as the player comes near, a door that opens when a plate is stood on and closes two seconds after it is left, a counter of switches pressed: each is one graph whose Output is the value it drives.

Install

dotnet add package BorrowedTorch.Drivers

Targets net10.0. Depends on BorrowedTorch.Animations 1.1.0 (the Animation node's clip and time line). It is compiled against MonoGame 3.8.1.303 without depending on it: the game brings its own MonoGame - DesktopGL, WindowsDX or BorrowedTorch's compute fork, 3.8.1.303 or newer - whose Vector4 the values are.

Quick start

using BorrowedTorch.Drivers;

// A lamp's intensity: 20 at 2 m from the player, 0 from 10 m on - only while a plate is stood on or a lever is down.
var library = DriverNodeLibrary<Entity>.CreateWithBuiltIns().Add(myDistanceKind).Add(myTriggerKind);

var graph = DriverGraph<Entity>.Empty
    .With(library.CreateNode("Distance", 1, new Vector2(0, 0)) with { References = [player] })
    .With(library.CreateNode(DriverKinds.Remap, 2, new Vector2(200, 0)) with { Values = [new(0), new(2), new(10), new(20), new(0)] })
    .With(library.CreateNode(DriverKinds.Output, 3, new Vector2(400, 0)))
    .Connect(new DriverWire(1, 0, 2, 0))
    .Connect(new DriverWire(2, 0, 3, 0));

var program = DriverProgram<Entity>.Compile(graph, library, DriverType.Number);
var run = program.CreateRun();

run.Start(); // as the game starts

// Update, once per frame:
var value = run.Evaluate(new DriverFrame<Entity>(elapsedSeconds, isPlaying, ownValue, lamp));

if (run.IsHolding) lamp.Intensity = value.X;

Values

Every wire carries a Vector4, of one of four DriverTypes: yes/no (X: 1 or 0), number (X), vector (X, Y, Z) and color (X, Y, Z, W - red, green, blue, alpha). A pulse is a yes for one frame - a trigger entered, an Edge, an animation finished.

A value goes into a port of another type by itself where it can: a yes is 1 and a no 0, a number above 0.5 is yes, a number is spread to every part of a vector or of a color (its alpha 1), a vector becomes a color of alpha 1 and a color a vector without its alpha. A vector or a color into a number takes a Split or a Length - wired straight in, it is an error. A port of Any type takes the widest of what is wired into it (a yes/no counted as a number for maths); an unwired one takes a number of its own, spread to that type.

Graph, program, run

  • DriverGraph<TRef> is the driver as data: its nodes and wires, immutable, so it is shared, compared and swapped whole - an edit (With, Without, Connect, Disconnect) makes a new one. Every node has the same fields - Kind, Position, Values (each unwired input's own value), Option, Flag, Inputs (a growing node's), References and Name (what a host's node reads), Clip (an animation's) - so a graph is saved and read as plain data. TRef is what the host's nodes name things by: the engine's entities.
  • DriverProgram<TRef>.Compile(graph, library, drivenType) works it out once: each node after what is wired into it, each port's type, a slot for every value, and Diagnostics - a node of no known kind, a type that can't go where it is wired, a loop (only through a Last frame may a value come round), two Outputs. A graph with an error drives nothing.
  • DriverRun<TRef> runs it for one driven value: Evaluate(frame) once a frame, allocating nothing; Start() as the game starts (its state reset, the animations that play on start started); Command(Play / Pause / Stop) for a tool's preview, Command(Forward / Reverse) for what plays it as its own pulses would - an action elsewhere; ValueOf(node, output) for an editor's live values. Made again as its graph is edited (program.CreateRun(previous)), it carries over the state of every node still there: an animation goes on playing.
  • IsHolding: whether the run drove the value as it was last worked out - its Output gave something other than the own value it was handed, or an animation of it is not stopped. Otherwise the value is its own: a door's closed turn can be edited while its animation stands at the start. A host writes the value only while it is held, and puts the own value back as the run lets go.

Nodes

Group Nodes
Inputs Own value (the driven value's own), Time (seconds since the game started), Playing, Constant
Animation Animation: an AnimationClip<Vector4> played from the own value. Play runs it on from where it is (one at its end stays there), Reverse back toward the start, Pause holds it, Stop puts it back; Stop and Play together start it over. Plays on start, unless switched off. Gives Value, Running, Finished (a pulse) and Progress
Generators Wave: sine, triangle, square or saw from 0 to 1, by period and phase; Noise: wanders smoothly between 0 and 1, by speed and seed
Logic And, Or (growing), Xor, Not, Compare (> ≥ < ≤ = ≠, within a tolerance), In range, Select
Math Add, Multiply (growing), Subtract, Divide (0 by 0), Negate, Abs, Min, Max, Clamp, Remap (clamped or not), Lerp, Round (round, floor, ceiling, to a step), Wrap, Power, Square root - part by part; Curve: a value 0 to 1 through a shaping function (DriverNode.Curve)
Vector Split, Combine (a vector or a color), Length, Dot, Normalize
Memory Edge (a pulse as its input turns on, off or either), Toggle, Latch (Set, Reset), Counter (up, down, reset, within a range or wrapping), Pulse (on for some seconds), Delay, Stay on, Smooth (easing, or at a speed), Last frame, Integrate (its input added up over time, Reset), Sample (its input taken on a pulse)
Output Output: what the graph drives
Subgraphs Subgraph input (a name, a type, a default), Subgraph output (a name): a subgraph's ports; Subgraph: a use of one (hidden from a node search - listed by subgraph)

Memory and time go by the frame's Elapsed - the game's clock, which pauses and steps with it. A pulse into a node is taken as it comes on: a yes held down counts once.

Subgraphs

A subgraph is a graph of its own, used as one node in others: its Subgraph input nodes are its uses' inputs and its Subgraph output nodes their outputs, each by its name, listed top to bottom as they stand. The host keeps them in its library, by name - library.Subgraphs = library.Subgraphs.SetItem("Flicker", graph) - and a Subgraph node names the one it uses (library.CreateUse("Flicker", id, position)). InputsOf(node) and OutputsOf(node) give any node's ports - a use's its subgraph's - and Uses(graph, name) whether a graph uses one, through the subgraphs it uses: what an editor leaves out of a subgraph's own node search.

As a program is worked out, each use is put in its place as its subgraph's nodes: a use keeps a memory of its own - a Toggle, an Animation in it counts for that use alone - its nodes run under ids of their own (DriverProgram.InlinedId(useId, nodeId), the same each time, so their state carries over as the graph or the subgraph is edited). An unwired input of a use takes the use's own value, else the input's default. What is wrong inside is said on the use ("In 'Flicker': ..."); a use of no subgraph, or of one it is within, is an error. ValueOf, InputTypesOf and OutputTypesOf answer for a use through its ports. DriverSubgraphs.Extract(graph, nodeIds, name, library, type) makes a graph's nodes a subgraph: the subgraph, and the graph with a use of it in their place, wired as they were.

A host's own nodes

A DriverNodeKind<TRef> is a node's id, title and group, its ports (DriverPort: name, type, whether it carries pulses, the value it takes unwired), its settings (Options, FlagName), a state made as its run is reset (CreateState), and Evaluate, handed a DriverCall<TRef>: its inputs already of its ports' types (In, Number, Yes), its outputs to set (Out), its node, its state and the frame - the thing driven among it (Frame.Target). TypeOf gives the type of its Any ports from what it reads; Check says what is wrong with a node as it is set, for the editor to show; References (DriverReference: a title, and whether the node's switch hides it), NameTitle and NameChoices (DriverChoices: the ids a node's Name picks among, as the host has them - keys, modes, handlers) tell an editor what to give pickers for - or, NameIsText, a box to type it in. IsHidden leaves a kind out of an editor's node search. A node that acts as its input comes on keeps a DriverEdge in its state: Rose, Fell, Changed.

Changelog

1.2.0

  • Subgraphs: DriverNodeLibrary.Subgraphs, CreateUse, InputsOf / OutputsOf, InterfaceOf (DriverSubgraphInterface), Uses; the Subgraph input, Subgraph output and Subgraph nodes; each use put in its place as a program is worked out (DriverProgram.InlinedId); DriverSubgraphs.Extract.
  • DriverNodeKind.NameIsText and IsHidden.

1.1.0

  • Nodes: Noise, Power, Square root, Curve (DriverNode.Curve, a BaseShapingFunction), Dot, Normalize, Integrate, Sample.
  • DriverNodeKind.NameChoices and DriverChoice; DriverEdge; DriverCommand.Forward and Reverse.

1.0.0

  • DriverGraph<TRef>, DriverNodeLibrary<TRef>, DriverProgram<TRef> and DriverRun<TRef>; the inputs, animation, generator, logic, maths, vector, memory and output nodes.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on BorrowedTorch.Drivers:

Package Downloads
BorrowedTorch.Engine

Kindling, Borrowed Torch's game engine: what a game's own code builds against - its features registering components, systems, keys and UI handlers - for the Kindling editor and player to run

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.0 65 11/19/2026
1.1.0 52 11/18/2026
1.0.0 47 11/18/2026