Design of the Candy Flutter Interactive Game Engine

Candy Engine is an embedded, lightweight, developer‑friendly interactive engine designed by the Xianyu team. It tightly integrates with Flutter’s drawing system, allowing seamless mixing of game scenes and Flutter UI.

The motivation comes from the rising trend of app gamification, which seeks safe, performant ways to embed mini‑games without the drawbacks of H5 solutions. The team evaluated three approaches: native game capabilities, heavyweight game engines (Cocos‑2dx, Unity), and Flutter‑based lightweight engines, ultimately choosing the latter.

The engine architecture consists of four layers: an interface layer exposing game creation APIs, the core game system, various subsystems (lifecycle, physics, animation, resources), and a rendering system that fuses game objects with Flutter’s Widget‑Element‑RenderObject hierarchy.

The game system mirrors Unity’s design with four main elements: Game (overall manager), Scene (scene manager), GameObject (entity), and Component (capability). Each GameObject can compose multiple Components to define its behavior.

The engine defines an eight‑stage lifecycle (init, load, start, update, render, pause, resume, destroy) to cover typical interactive game needs.

Rendering integration requires each GameObject to correspond to a Widget, Element, and RenderObject. Challenges addressed include coordinate conversion between game and Flutter layouts, dynamic addition/removal of objects, depth management, and Flutter Inspector support.

For the GUI system, the engine reuses Flutter UI directly. A sample GUI object creation code is shown below:

final GUIObject gui = IdleFishGame.createGUI('gui',
    child: GestureDetector(
      child: Container(
        width: 100.0,
        height: 60.0,
        decoration: BoxDecoration(
          color: const Color(0xFFA9CCE3),
          borderRadius: BorderRadius.all(Radius.circular(10.0)),
        ),
        child: const Center(
          child: Text('Flutter UI示例', style: TextStyle(fontSize: 14.0)),
        ),
      ),
      behavior: HitTestBehavior.opaque,
      onTap: () { print('UI被点击了'); },
    ),
    position: Position(100, 100),
);
game.scene.addChild(gui);

The event system introduces GestureBoxComponent , which registers gesture callbacks and integrates with Flutter’s hit‑testing and gesture arena to handle input events.

Animation support currently includes skeletal animation via DragonBones and particle animation via EgretFeather. Resource management reuses the app’s existing resource pool, leveraging Flutter’s ImageCache and a simple JSON loader, with a fallback resource system for cases without a registered app resource manager.

In summary, the article outlines the overall design of the Candy interactive engine, with future posts planned to dive deeper into rendering, animation, performance testing, and stability analysis.