# Can OpenMAIC Generate Interactive Simulations? Technical Architecture and Implementation Guide

> Discover how OpenMAIC generates interactive simulations. Learn the technical architecture and implementation guide for transforming text outlines into executable physics-based learning components.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: technical-architecture
- Published: 2026-09-01

---

**Yes, OpenMAIC can generate fully interactive simulations through a multi-layered widget pipeline that transforms text outlines into executable, physics-based learning components.**

OpenMAIC is an open-source framework for AI-generated educational content. The platform supports **interactive simulations** as first-class widgets, enabling dynamic exploration of scientific concepts directly within lesson pages. This capability is implemented through a robust type system, validation layers, and generation engines that convert textual descriptions into functional simulation components.

## How OpenMAIC Generates Interactive Simulations

The generation process follows a structured pipeline that begins with type definitions and ends with client-side rendering. When you request an interactive simulation, the system validates the widget type, applies default configurations if needed, and generates the specific simulation parameters through several coordinated modules.

### Widget Type Definitions

At the foundation of the system, the **simulation widget type** is formally declared in [`lib/types/widgets.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/types/widgets.ts) (line 24). This file establishes the contract that all simulation components must follow, including supported fields like `concept` and `keyVariables`.

### API Validation and Routing

When submitting a generation request, the server validates the `widgetType` parameter against an allowed set of interactive components. In [`app/api/generate/scene-outlines-stream/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/scene-outlines-stream/route.ts) (line 225), the system checks that the requested type matches one of the supported values: `simulation`, `diagram`, `code`, `game`, or `visualization3d`. If the request specifies `simulation`, the pipeline routes it to the appropriate generation handler.

### Default Fallback Mechanisms

If an interactive page outline lacks an explicit widget type, OpenMAIC automatically defaults to the simulation widget. The logic in `packages/@openmaic/generation/src/outline-type.ts` (line 51) ensures that when no specific interaction mode is defined, the system supplies `widgetType: 'simulation'` as the fallback. This design choice prioritizes hands-on learning experiences as the default interactive modality.

### Scene Generation Engine

The core transformation logic resides in `packages/@openmaic/generation/src/scene-generator.ts`. This module handles the creation of widget configurations, injecting the `widgetType: 'simulation'` identifier and processing any provided `variables` or `concept` fields (lines 135-139 and 262-267). The generator constructs a complete configuration object that specifies the simulation's behavior, initial state, and interactive controls.

### DSL Integration

OpenMAIC provides a domain-specific language (DSL) for authoring interactive content. The `packages/@openmaic/dsl/src/interactive.ts` file (lines 5-14) declares `simulation` as a valid interactive widget type. This enables authors to write imperative actions such as `SetState` that modify simulation variables in real-time, creating dynamic learning experiences where learners can adjust parameters and observe immediate results.

## Implementing Interactive Simulations

Developers can generate simulations through three primary interfaces: the REST API, the DSL, or direct React component integration.

### Requesting Simulations via the API

To generate a simulation programmatically, send a POST request to the scene outlines endpoint with the `widgetType` explicitly set to `simulation`:

```typescript
// POST /api/generate/scene-outlines-stream
await fetch('/api/generate/scene-outlines-stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Energy conservation simulation',
    type: 'interactive',
    widgetType: 'simulation',
    widgetConfig: {
      concept: 'conservation of energy',
      keyVariables: ['mass', 'velocity', 'height']
    }
  })
});

```

The server validates the `widgetType` against the allowed set and forwards the request to the scene generator, which returns a complete widget configuration ready for embedding in lesson pages.

### Defining Simulations in the DSL

For content authors, the DSL provides a declarative syntax for creating simulations with associated actions:

```typescript
import { interactive } from '@openmaic/dsl';

interactive({
  widgetType: 'simulation',
  widgetConfig: {
    concept: 'pendulum motion',
    keyVariables: ['length', 'mass', 'gravity']
  },
  actions: [
    // Adjust variables and observe the motion
    { type: 'SetState', payload: { length: 1.2 } },
    { type: 'Run' }
  ]
});

```

The DSL parser recognizes the `simulation` widget declaration, creates the appropriate client-side component, and wires the action handlers to the simulation engine.

### Rendering in React Components

Once generated, simulations render as standard React components. Import the `SimulationWidget` from the widgets package and pass the generated configuration:

```tsx
import { SimulationWidget } from '@openmaic/widgets';

function LessonPage() {
  const config = {
    concept: 'ideal gas law',
    keyVariables: ['pressure', 'volume', 'temperature']
  };
  return <SimulationWidget config={config} />;
}

```

The `SimulationWidget` component renders the interactive UI, allowing learners to manipulate variables and instantly visualize the resulting physical changes.

## Testing and Validation

The simulation generation pipeline includes comprehensive test coverage to ensure reliability. Test suites in files such as [`tests/lib/agent/client/apply-regenerate.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/agent/client/apply-regenerate.test.ts) (lines 166-170) and [`tests/generation/widget-actions-direct-pipeline.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/generation/widget-actions-direct-pipeline.test.ts) (lines 14-70) verify that the system correctly produces simulation widgets and persists their configurations. These tests validate the end-to-end flow from outline processing through final widget generation, confirming that the `widgetType: 'simulation'` field is correctly maintained throughout the pipeline.

## Summary

- OpenMAIC generates interactive simulations through a dedicated widget pipeline defined in the core type system.
- The system validates simulation requests in [`app/api/generate/scene-outlines-stream/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/scene-outlines-stream/route.ts), defaulting to simulation widgets when no type is specified in [`outline-type.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/outline-type.ts).
- Scene generation logic in [`scene-generator.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scene-generator.ts) constructs widget configurations with physics variables and conceptual metadata.
- The DSL in [`interactive.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/interactive.ts) supports imperative actions like `SetState` for real-time simulation manipulation.
- Simulations can be requested via REST API, authored declaratively in DSL files, or rendered directly as React components using `SimulationWidget`.

## Frequently Asked Questions

### What types of interactive simulations can OpenMAIC generate?

OpenMAIC supports physics-style simulations that allow parameter exploration and dynamic visualization. The system handles concepts ranging from energy conservation and pendulum motion to thermodynamic processes like the ideal gas law. Each simulation accepts configurable `keyVariables` that learners can manipulate to observe real-time changes in the system's behavior.

### How does OpenMAIC handle generation requests without a specified widget type?

When an interactive outline omits an explicit `widgetType`, the system automatically defaults to `simulation`. This fallback logic is implemented in `packages/@openmaic/generation/src/outline-type.ts` (line 51), ensuring that hands-on, exploratory learning experiences remain the primary interactive mode unless specifically overridden by other widget types like `diagram` or `code`.

### Can simulation states be modified programmatically after generation?

Yes. The DSL defined in `packages/@openmaic/dsl/src/interactive.ts` enables authors to declaratively specify actions that modify simulation state. Using the `SetState` action type, developers and content creators can programmatically update variables such as mass, velocity, or length, triggering immediate recalculation and visualization updates in the client-side simulation engine.

### Is the simulation widget generation pipeline tested?

Yes. OpenMAIC includes comprehensive test suites that validate simulation generation end-to-end. Tests in [`tests/lib/agent/client/apply-regenerate.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/agent/client/apply-regenerate.test.ts) and [`tests/generation/widget-actions-direct-pipeline.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/generation/widget-actions-direct-pipeline.test.ts) specifically verify that the system correctly produces simulations with valid configurations and that these configurations persist correctly through the generation pipeline.