ASimFrame 1.1.0

ASimFrame

A high-level .NET wrapper for MSFS SimConnect API, focused on clean architecture and reliable flight state tracking.

Requirements

• .NET 8.0 or later
• MSFS SimConnect SDK properly installed. The SDK installer sets the MSFS_SDK environment variable, which the project uses to reference the managed and native SimConnect libraries.

Abstraction Levels

ASimFrame is built on a layered architecture to separate concerns between raw SimConnect interactions and your application logic.

Level 1: Orchestration

• ASimFrame: The "God Object" entry point. It orchestrates the lifecycle of both Client and FlightBox, providing a unified API for connection, updates, and events.

Level 2: Core Services

• Client: The raw muscle. It manages the SimConnect connection, handles the message pump (ReceiveMessage), and exposes system-level events (Connection, SimStart/Stop, FlightLoad).
• FlightBox: The logistics manager. It handles the registration of definitions, processes incoming simulation data, and manages the wiring of requests and events.

Level 3: Management (Registries)

Middleware components that bridge the gap between Core Services and your Data Entities.

• DefinitionRegistry: Manages Data IDs and Type mapping.
• EventRegistry: Manages Event IDs.
• RequestRegistry: Handles Async request IDs and callbacks (Subscription model).

Level 4: Basic Entities

The building blocks you interact with.

• SimEntity: Base abstraction for any mapped SimConnect object.
  • Data Definitions:
    • VariableDefinition<T>: Represents a single SimVar (e.g., "PLANE ALTITUDE").
    • StructDefinition<T>: Represents a complex data structure mapped to a C# struct.
  • SimEvent:
    • ClientEvent: Represents an action you can trigger (e.g., "AUTOPILOT_ON").
• Ephemeral:
  • Request: Represents a transient async operation, managed via Subscription and SimRequest delegates.

Level 5: Infrastructure

Internal plumbing and transport layer.

• ISimProvider: A thin abstraction over the native SimConnect object.
• QueueProvider: A "Deferred Execution" provider. Allows you to define variables and events before a connection is established. It queues actions and replays them once connected.
• DirectProvider: A pass-through wrapper for active connections.

Key Features

• No Enum/Switch Hell: Registries auto-manage SimConnect IDs — no hand-maintained enum tables and no giant switch dispatch blocks.
• Type-Safe Data Binding: Work with VariableDefinition<T> and StructDefinition<T> instead of raw data buffers and manual offset arithmetic.
• Define Before Connect: QueueProvider lets you declare variables, events, and subscriptions up front; everything is replayed once a connection is established.
• Reliable Flight Tracking: State-machine logic to detect actual flight start/end, filtering out MSFS menu transitions and partial load states.

Project Structure

• ASimFrame: Top-level unified API.
• Client: Connection & Message Pump.
• FlightBox: Data & Registry Management.
• Abstractions: Base classes (SimEntity).
• SimProvider: SimConnect wrapping & Queuing logic.

Quick Start

// 1. Create Config (Helper for Console Apps)
var config = Config.CreateStandalone("MyApp");

// 2. Initialize Framework
var sim = new ASimFrame(config);

// 3. Define Data (Can be done before connection thanks to QueueProvider)
var altitude = sim.AddVariableDefinition<double>("PLANE ALTITUDE", "feet", SIMCONNECT_DATATYPE.FLOAT64);

// 4. Wire Events
sim.OnConnected += () => Console.WriteLine("Connected!");
sim.OnFlightStart += (aircraft, flight) => Console.WriteLine($"Flying: {aircraft}");

// 5. Subscribe to Data
altitude.Subsribe(alt => Console.WriteLine($"Altitude: {alt} ft"));

// 6. Main Loop
while (running)
{
    // Auto-connects if needed, processes messages
    sim.CheckConnection();
    sim.Process();
    Thread.Sleep(50);
}

sim.Dispose();

Examples

You can find complete working projects in the Examples/ folder:

• Example.ASimFrame:
  Recommended. Demonstrates the unified ASimFrame class. Shows how to define data before connecting (using QueueProvider) and how to handle high-level events.

• Example.Basic:
  Low-Level. Shows how to manually orchestrate Client, DefinitionRegistry, RequestRegistry, and EventRegistry without the ASimFrame wrapper. Useful if you need custom architecture.

• Example.FlightBox:
  Hybrid. Demonstrates using Client for connection management while delegating data handling to an isolated FlightBox instance. Useful for separating connection logic from data logic.

License

MIT License - see LICENSE for details.