chessground

• Add ChessboardSettings.moveOnRelease: when enabled, a tap-to-move is committed on pointer release instead of pointer press, and a square target follows the finger so the destination can be adjusted before releasing.
• Add ChessboardColorScheme.copyWith.
• Add Totoy piece set.
• Convert all assets to WebP format for better compression and faster loading.

Fixed promotion that was not working when ChessboardSettings.enableDrops was set to true (for crazyhouse chess variant). The promotion dialog now shows up correctly.

Fixed a bug where pieces from a finished move animation would disappear when the board was reparented (e.g. during an Android predictive-back gesture). The controller now commits a finished or interrupted animation to the static position instead of relying on the animation notifiers staying populated.

Fixed a bug where tree shift after an animated capture would leave stale animation pieces.

This is a major release with significant internal changes to the board rendering and interaction model, in order to improve performance during gameplay and to simplify the public API.

It replaces the widget-tree-driven board rendering with a CustomPainter-based approach to bypass Flutter's build and layout phases for frequent interactions (piece selection, moves).

New

• ChessboardController is now the public API for driving the interactive board. Position updates, premoves, promotion, user-drawn shapes, and the atomic explosion animation are all managed through the controller instead of through widget rebuilds and GameData callbacks.
• StaticChessboard is now the single non-interactive board, with its own StaticChessboardSettings and support for shapes, square highlights, touched squares, and a board border.
• New ChessboardSettings flags: enableDrops, enablePremoves, and canPromoteToKing.
• Faster hit-testing in Chessboard (HitTestBehavior.opaque).

See the migration guide and the breaking changes below for details.

BREAKING CHANGES

• The interactive Chessboard() constructor now requires a controller: parameter of type ChessboardController instead of separate fen:, game:, and lastMove: parameters. See the migration guide for the before/after pattern.

• Callbacks (onMove) have been removed from GameData and is now an optional parameter on the Chessboard widget itself.

• Premovable typedef and GameData.premovable have been removed. Premove state is now managed entirely by ChessboardController. The onSetPremove callback has been removed from Chessboard. Enable or disable premoves via ChessboardSettings.enablePremoves (default true). See the migration guide for the before/after pattern.

• Position updates now go through the controller instead of rebuilding the Chessboard widget with a new fen. Call ChessboardController.updatePosition(GameData game) to advance the board with animation, updatePosition(game, animate: false) to switch positions instantly (e.g. history navigation), and updatePosition(game, resetPremove: true) to clear any pending premove when jumping to an arbitrary position. The position fen now lives on GameData (alongside lastMove, side to move, valid moves, etc.), so a single object describes the whole board state. Drag-and-drop moves are detected internally by the board, so the redundant translation of a dropped piece is suppressed automatically — the parent no longer passes a lastDrop argument.

• Chessboard.fixed() has been removed. For a non-interactive board, use StaticChessboard (which now accepts settings, shapes, squareHighlights, onTouchedSquare, and renders an optional border). For a board that is interactive only some of the time (e.g. disabled at the end of a game), use Chessboard and drive its controller with game data whose playerSide is PlayerSide.none. See the migration guide for the before/after pattern.

• squareHighlights has been removed from Chessboard(). It is now a parameter of StaticChessboard.

• explosionSquares has been removed from Chessboard(). Use ChessboardController.triggerExplosion() instead.

• Promotion is now handled fully inside the board. The onPromotionSelection callback has been removed from Chessboard. The promotionMove field and canPromoteToKing flag have been removed from GameData. canPromoteToKing is now a field on ChessboardSettings. The board calls onMove exactly once, after the user has selected a promotion piece, with a fully-resolved NormalMove (promotion role already set). See the migration guide for details.

• DrawShapeOptions no longer accepts onCompleteShape or onClearShapes callbacks. Shape state drawn by the user is now managed internally by ChessboardController. See the migration guide for the before/after pattern.

• GameData.droppable (the Droppable record wrapper) has been removed. Pass validDropSquares directly on GameData instead, and set ChessboardSettings(enableDrops: true) to activate the drop target. The Droppable typedef has been removed. See the migration guide for the before/after pattern.

BREAKING CHANGES

• BoardSettings.enableDropMoves has been removed. Use GameData.droppable instead.

• Add Droppable to GameData. For drop moves, Chessboard will now only call onMove if and only if Droppable.validDropSquares contains the target square. This makes the behavior consistent with normal moves. Note that dropping a pawn on the back rank does not trigger onMove, even if validDropSquares would allow it.

• Fix top player promotion selector when canPromoteToKing is true.
• Preserve the piece animation behaviour even if the system is requesting the animations to be reduced or disabled.

• Add canPromoteToKing in GameData to allow promotion to king in variants like Antichess.

• Add explosionSquares to Chessboard to show explosion effect on specific squares, useful for variants like atomic chess.

• Revert piece is deselected when the board is updated from the parent widget.

• Add support for drop moves for crazyhouse chess variant.

### BREAKING CHANGES

• {bool? isDrop} parameter of the onMove callback has been renamed to viaDragAndDrop to be more explicit.

• Revert piece is deselected when the board is updated from the parent widget.

• Ensure any piece is deselected when the board is updated from the parent widget.

• Update dartchess to 0.12.0

• New piece sets: firi and xkcd,
• New board: purple,
• Fixed Staunty knights that were not correctly centered.

• Add RhosGFX piece set.
• Do not update the square all the time while panning in board editor.

Fix promotion selection order if player on top promotes

• Fix board image background not aligned with pieces on tablets.

• When piece shift method is set to drag, the piece will awlays be deselected when the pointer is released, even if the piece is dropped on the same square.

• Make board annotations always on top of shapes.

• Fix crash when calling setState in pointerUp, pointerMove or pointerCancel callbacks.
• flip pieces instead of rotating to keep the shadows in the same direction.

• Update dartchess to 0.11.0

• Expose 'BoardShapeWidget' class.

• Make the hue setting apply only to the board background to avoid changing board highlights colors.
• Update dependencies
• Update minimum Dart SDK version to 3.7.0 and minimum Flutter version to 3.29.0

• Update dependencies
• Update minimum Dart SDK version to 3.7.0 and minimum Flutter version to 3.29.0

• Added an onTouchedSquare callback to Chessboard
• Chessboard now supports highlighting arbitrary squares.
• StaticChessboard now supports position change animations.

• Fix board editor color filter

• Fix default value of brightness

• Improved the color filter
• Values of hue and brightness are now precised in the documentation
• BrightnessHueFilter widget is now exposed.

• Add the possibility to change board colors

• Added a new DragTargetKind settings to control the appearance of the drag target.
• Detects if the drag is triggered with a mouse or a touch event, and adjust the drag settings accordingly to provide a better experience.
• Removed the withValues not yet available in specified dart sdk version.

Breaking changes:

• Removed ChessboardEditorSettings. The ChessboardEditor widget now takes a ChessboardSettings object as a parameter.

New features:

• Add a new border settings to show a border around the board.

Bug fixes:

• Fixed a timer not properly canceled when the board is disposed.

• Added a new StaticChessboard widget that is optimized for scrollable contexts.
• SolidColorChessboardBackground is now implemented with CustomPaint to improve performance when building a lot of boards.
• Added a new board colorscheme: ic.

• Introduced a ChessgroundImages singleton to precache piece images. This is useful when using the same piece set in multiple places, and to avoid using the global flutter image cache, which can be unpredictable. It should prevent any "blinking" effect that could happen with the Image widget when the image is reloaded from the cache.

• Reset animation state when the board is updated. This fixes potential issues where the board would display ghost pieces on some conditions.

• Dragging a piece to the same square will now keep the piece selected.

• Added another Chessboard.fixed constructor that allows to set the board to a fixed position.
• Premove state is now lifted up to the parent widget, in order to allow instant play of premoves.
• Promotion state is now lifted up to the parent widget, in order to allow more control over the promotion dialog.
• Add symmetric piece set (PieceAssets.symmetric).
• ChessboardEditor now supports highlighting squares.
• Flip BoardSettings.dragFeedbackOffset.dy for flipped pieces. Support displaying all pieces upside down based on side to move.
• Fix: ensure the board background does not overflow the board.

Breaking changes:

• Chessboard now require a game parameter of type GameData instead of BoardData.
• Added required parameters piece and pieceAssets to PieceShape, removed role. Added optional opacity parameter.
• Remove 'ChessboardState.opponentsPiecesUpsideDown' in favor of ChessboardSettings.pieceOrientationBehavior.

New features:

• Add a ChessboardEditor widget, intended to be used as the basis for a board editor like lichess.org/editor.
• Add the writeFen helper function.

Breaking changes:

• Requires an SDK version of at least 3.3.0.
• Chessground is now dependant on dartchess. It is only used for the models, and not for the game logic, so Chessground can still be used with any chess library.
• Board has been renamed to Chessboard, along with other classes.

Bug fixes:

• Fix arrow bad shape when new destination is the same as the origin: it now returns a circle.
• Fix unsetting premoves:
  • When a premove is set, tapping on the same origin square will now unset it.
  • dragging a piece to an invalid square will now unset the premove.
  • dragging a piece off the board will now unset the premove.

• Add pieceShiftMethod to BoardSetttings, with possible values: either (default), drag, or tapTwoSquares.

• Any simultaneous touch on the board will now cancel the current piece selection or drag.

• Allow shapes to be drawn on a non-interactable board.
• Fix a bug where the board would be stuck after transitioning from a non-interactable board to an interactable one.
• Selecting a piece will now clear all shapes on the board.
• Add the scale property to all Shape classes. Use a 0.8 scale for the shapes being drawn on the board to distinguish them from the already drawn ones.

• Add an optional scale parameter to arrows (default is scale: 1.0, matching the previous behavior).
• Implement BoardData.copyWith method to allow updating the board data
• Implement BoardData equality and hashcode operators
• Implement BoardSettings equality and hashcode operators

Improve board interaction and add support for drawing shapes while playing.

Playing:

• pieces are now moved with pointer down events, instead of a tap events (pointer down followed by a pointer up event): this allows to move a piece faster
• premoves are not anymore cleared when selecting another piece: this matches lichess website behaviour and allow to prepare another move along with the premove that is currently set

Drawing shapes (experimental)

• drawing shapes is now possible while keeping the normal board play interaction (before it was either one or another mode)
• one can draw a shape by holding a finger to an empty square while using a second finger to draw a shape anywhere in the board
• a double tap on an empty square will clear all shapes at once
• to clear a single shape is still supported: draw the same shape again

• Fix coordinates and board display on devices with RightToLeft Directionality.

• Improve coordinates display on the board.

• Fix borderRadius settings not being applied to the board highlights.

• Fix BoardSettings copyWith method.

• Add 2 new settings: borderRadius and boxShadow.

• Add a new shape type: piece (useful to show promotion hints).

• Don't clip board: fix annotations display on edge.

• Deprecate BoardTheme and export Background.

• Remove handling of android gestures exclusion.

• Upgrade fast_immutable_collections to version 10.0.0.

• Improve quality of PNG files, fix wrong rendering of some piece set like "Cardinal". More info: https://github.com/lichess-org/flutter-chessground/pull/28.
• Piece cache size is now rounded to the nearest integer above the actual value.

• BoardData.sideToMove is now optional with no default value, as well as BoardData.isCheck and constructor assertion will guarantee they are set when needed.

• BoardData.sideToMove is now a required parameter.

• Fix missing blindfoldMode to BoardSettings.copyWith