TheSingularityWorkshop.FSM_Bridge.Helix 0.0.1

FSM_Bridge.Helix

💖 Support Us

A bridge to a structured reality.

🔍 Overview

FSM_Bridge.Helix is the first package in the new Bridge Layer of The Singularity Workshop's ecosystem. It is designed to allow developers to seamlessly integrate behaviors from the Helix Toolkit into the core FSM_API. This package acts as an adaptation layer, providing the necessary IStateContext implementations and FSM components to manage the state of 3D objects and viewports within applications built on the Helix Toolkit. Its primary purpose is to serve as a pathway for existing Helix content to be consumed within the AnyApp and MyVR environments.

🚀 Quickstart

1. Define a simple context (your data model): C#

public class MeshFSMContext : IStateContext
{
    public MeshGeometryModel3D Mesh { get; set; }
    public Color OriginalColor { get; set; }
    public bool IsSelected { get; set; }
    public bool IsValid => Mesh != null;
    public string Name { get; set; }
}

1. Define and build your FSM: C#

// Define a simple condition function
private static bool OnMeshHover(IStateContext ctx)
{
    // A simplified example of checking for mouse hover
    return ((MeshFSMContext)ctx).IsSelected;
}

FSM_API.Create.CreateFiniteStateMachine("MeshSelectionFSM")
    .State("Deselected",
        onEnter: (ctx) => {
            if (ctx is MeshFSMContext c) c.Mesh.Material = new PhongMaterial(new DiffuseMaterial(c.OriginalColor));
        })
    .State("Selected",
        onEnter: (ctx) => {
            if (ctx is MeshFSMContext c) c.Mesh.Material = new PhongMaterial(new DiffuseMaterial(Colors.Yellow));
        })
    .WithInitialState("Deselected")
    // Now define the transitions between states
    .Transition("Deselected", "Selected", OnMeshHover)
    .Transition("Selected", "Deselected", (ctx) => !OnMeshHover(ctx))
    .BuildDefinition();

3. Create an instance for your context: C#

var myMeshContext = new MeshFSMContext { Mesh = my3DModel, OriginalColor = Colors.Red };
var handle = FSM_API.Create.CreateInstance("MeshSelectionFSM", myMeshContext, "MainLoop");

4. Tick the FSM from your application's main loop: C#

// Process all FSMs in the "MainLoop" group
FSM_API.Interaction.Update("MainLoop");

🔧 Core Concepts

FSMBuilder: Fluently define states, transitions, and associated OnEnter/OnExit actions.

FSMHandle: Represents a runtime instance of an FSM operating on a specific context.

IStateContext: The interface your custom data models must implement to be used by the FSM. `FSM_Bridge.Helix` provides concrete `IStateContext` implementations for Helix components, such as `MeshGeometryModel3D_FSM_Behavior.cs`.

Processing Groups: Organize and control the update cycles of multiple FSM instances.

Error Handling: Built-in thresholds and diagnostics prevent runaway logic or invalid state contexts.

Thread-Safe by Design: All modifications to FSM definitions and instances are deferred and processed safely on the main thread post-update, eliminating common concurrency issues.

📦 Features at a Glance

📘 What’s Next?

📖 Full Documentation & Wiki (TBD)

🧪 Unit Tests & Benchmarks (Currently Under Development)

🔌 Plugins & Extension Framework (e.g., for visual editors, debugging tools)

🤝 Contributing

Contributions welcome! Whether you're integrating FSM_Bridge.Helix into your enterprise application, designing new extensions, or just fixing typos, PRs and issues are appreciated.

📄 License

MIT License. Use it, hack it, build amazing things with it.

🧠 Brought to you by:

The Singularity Workshop - Tools for the curious, the bold, and the systemically inclined.

<a href="https://www.patreon.com/TheSingularityWorkshop" target="_blank"> <img src="Visuals/TheSingularityWorkshop.png" alt="Support The Singularity Workshop on Patreon" height="200" style="display: block;"> </a>

Because state shouldn't be a mess.

Support the project: Donate via PayPal