Designing Candy: A Lightweight Flutter Game Engine for In‑App Mini‑Games

What is the Candy Engine?

Candy is an embedded, lightweight, easy‑to‑develop, and performance‑stable interactive engine designed by the Xianyu team.

App‑embedded, lightweight interactive engine.

Highly integrated with Flutter, supporting seamless mixing of game scenes and Flutter UI.

Animation system with friendly support for mainstream formats.

This article explains why the engine was built and how it was designed.

Background

Typical in‑app mini‑games use H5, which has security and store‑approval issues. A new solution needed to be safe, developer‑friendly, stable, and feature‑complete.

Design Considerations

Three approaches were evaluated:

Native game capabilities – high development and maintenance cost due to dual codebases.

Existing game engines (Cocos‑2dx, Unity) – large package size, heavy memory usage, slow startup, and limited UI integration.

Flutter‑based lightweight interactive engine – Flutter already provides a 2D Skia‑based rendering pipeline, making it a promising foundation.

We chose the Flutter‑based approach.

Candy Engine Architecture

The engine consists of four layers:

Interface Layer : Exposes APIs for creating games, objects, and components, plus factory methods.

Game System : Manages Game, Scene, GameObject, and Component relationships and controls subsystem lifecycles.

Game Subsystems : Lifecycle, physics, animation, and resource systems invoked by the game system.

Rendering System : Integrates game rendering with Flutter’s rendering tree, allowing each GameObject to correspond to a Widget, Element, and RenderObject.

The engine provides the following subsystems:

Game System

Inspired by Unity, it includes Game, Scene, GameObject, and Component.

Lifecycle

Eight callbacks cover creation, start, pause, resume, update, render, destroy, and dispose phases.

Rendering System

Game objects are mapped to Flutter’s Widget‑Element‑RenderObject trio, enabling coordinate conversion, dynamic addition/removal, depth changes, and Inspector support.

GUI System

By reusing Flutter UI, a special GameObject can embed a Flutter widget tree, eliminating the need for a separate GUI implementation.

final GUIObject gui = IdleFishGame.createGUI(
  'gui',
  child: GestureDetector(
    child: Container(
      width: 100.0,
      height: 60.0,
      decoration: BoxDecoration(
        color: const Color(0xFFA9CCE3),
        borderRadius: const 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);

Event System

A GestureBoxComponent registers gesture callbacks, and GameObject’s RenderObject overrides hitTest to forward events to the component, integrating with Flutter’s gesture arena.

Animation System

Supports skeletal animation (DragonBones) and particle animation (EgretFeather).

Resource System

Reuses the app’s resource library to avoid duplication. A fallback resource system provides image caching via Flutter’s ImageCache and simple JSON animation loading.

Conclusion

The Candy interactive engine addresses many challenges of embedding mini‑games in apps, though issues such as memory leaks in Flutter rendering remain. Future posts will detail performance testing and further optimizations.