漢文文檔

A Dynamic Scripting Language for Flutter Server-Driven UI

Flux is a lightweight, stack-based scripting language designed specifically to enable dynamic updates and server-driven UI logic within Flutter applications. It decouples business logic and UI layout from the app binary, allowing for instant updates without App Store submission.

• FluxUI Component Library: Complete set of UI components (Button, Card, Input, Badge, Row, Column, Grid, Stack)
• BLE Integration: Full Bluetooth Low Energy support via flutter_blue_plus
• Camera Integration: Real camera functionality via camera package
• Enhanced CLI: Project scaffolding, hot-reload, and static analysis

This diagram illustrates how Flux transforms raw script code into a reactive native Flutter UI interactively managed by Riverpod.

graph TD
    %% Styling
    classDef source fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
    classDef core fill:#fff3e0,stroke:#ff6f00,stroke-width:2px;
    classDef flutter fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef state fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;

    Input([📄 .flux Source Code]):::source -->|Parse & Compile| Compiler[⚙️ Flux Compiler]:::core
    
    Compiler -->|Bytecode| VM[🖥️ Flux VM]:::core
    
    subgraph "Flutter Runtime Environment"
        VM -->|Execute| ScriptLogic[🧠 Script Logic]:::core
        
        ScriptLogic -->|Call| Bindings[🔗 Flux Bindings]:::flutter
        Bindings -->|Build| UI[📱 Flutter Widgets]:::flutter
        
        ScriptLogic <-->|Read/Write| RP[🌊 Riverpod Providers]:::state
        RP -->|Notify| UI
    end

    UI -->|User Interaction| ScriptLogic

1. Compiler: Translates human-readable .flux code into efficient bytecode instructions.
2. VM: A stack-based virtual machine that executes the bytecode safely within the host app.
3. Bindings: Bridges the gap between the dynamic VM and static Flutter widgets (Text, Column, etc.).
4. Riverpod: Acts as the synchronized state layer, allowing Flux scripts to read/write native Flutter state seamlessly.

The project is organized as a monorepo containing the following core packages:

Package	Description	pub.dev
flux_compiler	Lexer, Parser, and Code Generator. Converts source to bytecode.
flux_vm	The runtime engine. A stack machine that executes Flux bytecode.
flux_flutter	Flutter integration layer. Contains widget bindings and the Riverpod runtime adapter.
flux_lang_cli	Command-line tool for running .flux scripts directly in the terminal.
flux_lsp	Language Server Protocol (LSP) implementation for editor intelligence.
flux_vscode	VSCode Extension providing syntax highlighting, snippets, and LSP integration.	-
flux_updater	OTA update system with bytecode diff and version control.

Add Flux to your pubspec.yaml:

dependencies:
  flux_flutter: ^2.0.1
  flutter_riverpod: ^3.0.0

Install from pub.dev:

flutter pub add flux_flutter

Or for local development:

dependencies:
  flux_flutter:
    path: ../packages/flux_flutter

Create a file named counter.flux:

// Define a widget component
widget Counter {
  state count = 0;
  
  build {
    Column(
      children: [
        Text(text: "Count: " + count),
        Button(
          text: "Increment",
          onPressed: fn() {
            count = count + 1;
          }
        )
      ]
    )
  }
}

// 1. Define your State
final counterProvider = NotifierProvider<FluxValueNotifier<int>, int>(
  () => FluxValueNotifier(0),
);

// 2. Use the FluxWidget
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: FluxWidget(
        source: fluxSourceCode, // Load your .flux file string here
        widgetName: 'Counter',  // The widget class implementation to use
      ),
    );
  }
}

• Hot-Pushable Logic: Update UI structure and business rules by simply downloading a new string.
• Sandboxed Execution: Scripts run in a controlled VM environment, preventing crashes in the host app.
• Native Performance: Uses lightweight bytecode interpretation, keeping the UI smooth (60fps).
• State Management: First-class support for Riverpod 3.x/2.x via the Notifier API.

The Flux VSCode Extension provides a premium development experience:

• Intelligent Navigation: Go to Definition and Find All References.
• Code Intelligence: Autocompletion for widgets, keywords, and providers.
• Diagnostics: Real-time error reporting as you type.
• Snippets: Rapidly scaffold widgets and logic blocks.

To install, see the VSCode Extension README.

The Flux CLI provides tools for development and deployment:

# Install globally
cd packages/flux_cli && dart pub global activate --source path .

# Create a new project
flux create my_app --template flutter

# Run with hot-reload
flux run main.flux --watch

# Static analysis
flux analyze ./src/

# Build to bytecode
flux build script.flux

For complete documentation, see Flux CLI README.

• Language Guide: Syntax, control flow, functions, and native interop.
• Widget Catalog: List of all supported Flutter widgets.
• Flux vs Lua: Comparison with Lua hot update solutions.
• Lua Migration Guide: For developers migrating from Lua.
• Chinese Quick Start: 30-second quick start guide in Chinese.

To ensure the integrity of the ecosystem, run the test suite across all packages:

# Core Logic Tests
dart test packages/flux_compiler
dart test packages/flux_vm
dart test packages/flux_cli
dart test packages/flux_lsp

# Integration Tests
flutter test packages/flux_flutter