Project Overview

Source Files

This page is generated from the following source files:

• README.md
• packages/hetu_script/pubspec.yaml

Hetu Script is a lightweight scripting language implemented purely in Dart, specifically designed for embedding within Flutter applications. The project addresses a critical need in the Flutter ecosystem: enabling runtime code execution, hotfix capabilities, and scripting functionality without requiring application recompilation. According to the official documentation, the primary goal is to empower Flutter applications and games with dynamic scripting abilities (README.md:28-32).

The language features modern syntax inspired by TypeScript, Kotlin, and Swift, making it accessible to developers familiar with contemporary programming paradigms. As a pure Dart implementation, Hetu Script runs on all platforms supported by Flutter, including mobile devices, web browsers, and desktop environments (README.md:8-10).

Technical Stack Overview

The package metadata confirms version 0.6.2, indicating an active development state with ongoing feature additions and improvements (packages/hetu_script/pubspec.yaml:1-4).

Core Features

Hetu Script provides a comprehensive set of features designed for embedded scripting scenarios:

Modern Language Syntax

The language adopts syntax patterns from TypeScript, Kotlin, and Swift, reducing the learning curve for developers already familiar with these languages. This design choice enables rapid onboarding and immediate productivity (README.md:34-41).

Full Scripting Capabilities

The language supports multiple programming paradigms:

• Class-based Object-Oriented Programming (OOP): Traditional class inheritance and encapsulation
• Prototype-based OOP: JavaScript-style prototype chains for flexible object composition
• Functional Programming (FP): First-class functions and functional constructs
• Module System: Code organization and encapsulation through modules
• Error Handling: Structured exception management mechanisms

Cross-Platform Execution

Hetu Script executes on every platform that Flutter supports, including web browsers and desktop environments. This universal compatibility ensures consistent behavior across deployment targets (README.md:34-41).

Seamless Dart Integration

The binding system enables bidirectional interaction between Dart and Hetu Script with minimal boilerplate. Developers can invoke Dart functions from script code and call script functions from Dart with single-line bindings, significantly reducing integration overhead (README.md:34-41).

Interactive Development Environment

An online playground is available at hetu.dev/codepad/, allowing developers to test Hetu Script code directly in web browsers without local installation (README.md:1-6).

System Architecture

The Hetu Script system is designed as a layered architecture that integrates with Flutter applications through well-defined interfaces. The following diagram illustrates the core architectural components and their relationships:

正在加载图表渲染器...

Architecture Component Analysis

Lexer Component: Responsible for converting raw script source code into a stream of tokens. This component handles lexical analysis, identifying keywords, identifiers, operators, and literals from the input text.

Parser Component: Transforms the token stream into an Abstract Syntax Tree (AST). The parser enforces grammar rules and builds a hierarchical representation of the program structure.

Compiler Component: Converts the AST into bytecode instructions optimized for execution. This intermediate representation enables efficient interpretation by the virtual machine.

Virtual Machine: The execution engine that interprets compiled bytecode. It manages the execution stack, controls program flow, and coordinates with the runtime environment for object manipulation and variable resolution.

Dart Binding Layer: Provides the bridge between Hetu Script and the host Flutter application. This layer handles type conversions, function marshaling, and external resource access.

Script Execution Data Flow

The following diagram illustrates the complete data flow from script source input to execution result output:

正在加载图表渲染器...

Data Flow Key Points

Source Loading Phase: The Flutter application provides script source code to the Hetu Engine. This source can originate from assets, network responses, or dynamically generated strings, enabling hotfix scenarios.

Compilation Pipeline: The three-stage compilation process (lexing → parsing → compilation) transforms human-readable code into optimized bytecode. Each stage produces a distinct intermediate representation.

Execution Phase: The Virtual Machine executes bytecode instructions, interacting with the Object Heap for memory operations. The execution loop continues until completion or error occurrence.

Result Propagation: Final execution results or errors propagate back through the engine to the calling Flutter application, maintaining clear error boundaries.

Project Directory Structure

Based on the repository organization, the project follows a standard Dart/Flutter package structure:

hetu-script/
├── packages/
│   └── hetu_script/           # Core scripting engine package
│       ├── pubspec.yaml       # Package configuration (v0.6.2)
│       ├── lib/               # Dart library implementation
│       │   ├── src/           # Source implementation files
│       │   └── hetu_script.dart  # Public API exports
│       └── test/              # Unit tests and integration tests
├── README.md                  # Project documentation
└── hetu.dev/                  # Documentation website resources

The monorepo structure with the packages/ directory suggests potential for modular expansion, allowing separate packages for tools, extensions, or platform-specific implementations.

Quantitative Project Metrics

The version number 0.6.2 indicates the project is in active development with regular updates, approaching a stable 1.0 release while maintaining backward compatibility considerations (packages/hetu_script/pubspec.yaml:1-4).

Applicable Use Cases

Hotfix and Dynamic Updates

Hetu Script enables deploying bug fixes and feature updates to Flutter applications without app store review cycles. Script code can be downloaded and executed at runtime, modifying application behavior dynamically.

Game Scripting

Game developers can use Hetu Script to define game logic, NPC behaviors, quest systems, and event handlers. The scripting layer allows content updates without rebuilding the core game engine.

Configuration and Customization

Complex configuration scenarios benefit from scripting capabilities. Instead of static JSON or XML configurations, applications can use script-based configurations with conditional logic and computed values.

Plugin and Extension Systems

Applications can expose APIs to Hetu Script, enabling third-party developers or power users to extend functionality through scripts while maintaining sandbox isolation.

Educational Tools

The TypeScript/Kotlin/Swift-like syntax makes Hetu Script suitable for programming education tools built with Flutter, providing a safe, constrained execution environment for learning code.

Report Reading Roadmap

The following diagram illustrates the recommended reading sequence for this technical analysis report:

正在加载图表渲染器...

Reading Path Recommendations

Sequential Reading: For comprehensive understanding, follow the linear path from Overview through Deployment. Each chapter builds upon concepts established in previous sections.

Feature-Focused Path: Developers primarily interested in language capabilities should proceed from Overview to Features Analysis, then to API Design for practical integration guidance.

Architecture-Focused Path: System architects should prioritize the Architecture Deep Dive and Data Flow Analysis chapters after completing this overview.

Integration-Focused Path: Teams planning to integrate Hetu Script should read Overview, API Design, and Deployment Guide in sequence, referencing other chapters as needed.

Core Implementation Modules

Based on the architectural analysis, the following core modules constitute the Hetu Script engine:

Lexer Module

Responsibility Boundary: Converts raw source text into structured tokens. Does not perform semantic validation or syntax checking.

Key Data Structures:

• Token stream: Sequential collection of typed tokens
• Position tracking: Line and column information for error reporting

Critical Operations:

• Character classification and grouping
• String literal parsing with escape sequence handling
• Numeric literal parsing (integers and floating-point)
• Comment and whitespace filtering

Parser Module

Responsibility Boundary: Constructs Abstract Syntax Tree from token stream. Validates syntactic correctness but defers semantic analysis.

Key Data Structures:

• AST nodes: Hierarchical representation of program structure
• Parse context: Tracking state for nested constructs

Critical Operations:

• Expression parsing with operator precedence
• Statement parsing and block construction
• Declaration processing (classes, functions, variables)
• Error recovery and synchronization

Compiler Module

Responsibility Boundary: Transforms AST into executable bytecode. Performs optimizations and generates constant pools.

Key Data Structures:

• Bytecode array: Sequential instruction stream
• Constant pool: Literal values and symbol references
• Debug information: Source mapping for error reporting

Critical Operations:

• Code generation for each AST node type
• Jump instruction resolution for control flow
• Symbol table construction for scope management

Virtual Machine Module

Responsibility Boundary: Executes compiled bytecode. Manages runtime state and coordinates with host application.

Key Data Structures:

• Execution stack: Operand stack for expression evaluation
• Call stack: Function invocation frames
• Global object table: Root object references

Critical Operations:

• Instruction fetch-decode-execute cycle
• Stack manipulation for expression evaluation
• Function call setup and teardown
• Exception handling and propagation

Integration Architecture

The integration between Hetu Script and Flutter applications follows a layered approach that maintains clear separation of concerns:

正在加载图表渲染器...

Integration Component Responsibilities

Binding Registry: Maintains mappings between Dart functions and script-callable identifiers. Handles function lookup and dispatch during script execution.

Type Converters: Transform data between Dart and Hetu Script representations. Handles primitive types, collections, and custom object marshaling.

Communication Channel: Manages the bidirectional flow of control and data between the host application and script environment. Ensures thread safety and proper context isolation.

Script Context: Encapsulates the execution environment for a script instance. Maintains isolation between multiple script contexts within the same application.

Error Handling and Boundary Conditions

The Hetu Script engine implements comprehensive error handling across all pipeline stages:

Lexical Errors

• Invalid character sequences
• Unterminated string literals
• Malformed numeric literals

Syntax Errors

• Unexpected token encounters
• Mismatched delimiters (parentheses, braces, brackets)
• Invalid statement constructions

Runtime Errors

• Type mismatches in operations
• Undefined variable access
• Null reference dereferences
• Stack overflow conditions
• Division by zero attempts

Binding Errors

• External function invocation failures
• Type conversion errors
• Resource access violations

Each error category includes position information for diagnostic purposes, enabling precise error location in source code.

Performance Characteristics

The bytecode compilation approach provides several performance advantages:

Ahead-of-Time Compilation: Scripts are compiled to bytecode before execution, enabling optimization passes that would be impractical during direct interpretation.

Compact Representation: Bytecode occupies less memory than AST representations, improving cache efficiency during execution.

Direct Threaded Interpretation: The virtual machine can use computed goto or direct threading techniques for faster instruction dispatch.

Lazy Loading: Modules can be loaded on-demand, reducing initial memory footprint and startup time.

Documentation and Resources

Official documentation is available at hetu.dev with comprehensive guides in both English and Chinese (README.md:28-32). The documentation covers:

• Language syntax and semantics
• Standard library reference
• Integration tutorials
• Best practices for embedded scripting

The online playground at hetu.dev/codepad/ provides an interactive environment for experimenting with Hetu Script without local installation requirements (README.md:1-6).