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
<PackageReference Include="BorrowedTorch.Drivers" Version="1.2.0" />
<PackageVersion Include="BorrowedTorch.Drivers" Version="1.2.0" />
<PackageReference Include="BorrowedTorch.Drivers" />
paket add BorrowedTorch.Drivers --version 1.2.0
#r "nuget: BorrowedTorch.Drivers, 1.2.0"
#:package BorrowedTorch.Drivers@1.2.0
#addin nuget:?package=BorrowedTorch.Drivers&version=1.2.0
#tool nuget:?package=BorrowedTorch.Drivers&version=1.2.0
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),ReferencesandName(what a host's node reads),Clip(an animation's) - so a graph is saved and read as plain data.TRefis 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, andDiagnostics- 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.NameIsTextandIsHidden.
1.1.0
- Nodes: Noise, Power, Square root, Curve (
DriverNode.Curve, aBaseShapingFunction), Dot, Normalize, Integrate, Sample. DriverNodeKind.NameChoicesandDriverChoice;DriverEdge;DriverCommand.ForwardandReverse.
1.0.0
DriverGraph<TRef>,DriverNodeLibrary<TRef>,DriverProgram<TRef>andDriverRun<TRef>; the inputs, animation, generator, logic, maths, vector, memory and output nodes.
| Product | Versions 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. |
-
net10.0
- BorrowedTorch.Animations (>= 1.1.0)
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.