lichess-org / mobile

Lichess mobile app v2

Lichess Mobile

Second iteration of the Lichess mobile app.

How to contribute

The project is still in early stage of development. Drastic changes may still happen, including project structure.

If you want to contribute, please read the contributing guide.

Setup

1. Follow the Flutter guide to install Flutter and the platform of you choice (iOS and/or Android). Note, if you're on Linux, you should install flutter manually because there is an issue with snapd when building Stockfish. Note that this project is not meant to be run on web platform.
2. Switch to the beta channel by running flutter channel beta and flutter upgrade
3. Ensure Flutter is correctly configured by running flutter doctor

Flutter version

While the app is in beta we'll use the beta channel of Flutter.

Flutter Version Management

If you want to use FVM to manage your Flutter versions effectively, please consult the FVM (Flutter Version Management) guide for comprehensive instructions on installing Flutter on your specific operating system.

Pro Tip: Remember to prepend the 'flutter' prefix when using FVM commands, like this: fvm flutter [command].

Local lila

You will need a local lila (lichess server scala app) instance to work on this project. You will also need to setup lila-ws (websocket server).

Instructions to install both are found in the lila wiki.

The mobile application is configured by default to target http://127.0.0.1:9663 and ws://127.0.0.1:9664, so keep these when installing lila.

Run

We don't commit generated code to the repository. So you need to run the code generator first:

flutter pub get
dart run build_runner watch

Check you have some connected device with: flutter devices.

If you target an android emulator you need to run these commands so the device can reach the local lila instance:

adb reverse tcp:9663 tcp:9663
adb reverse tcp:9664 tcp:9664

Then run on your device:

flutter run -d <my_device>

You can find more information about emulators in the wiki.

You can find more information about the flutter run command by running flutter run --help.

Test

Before submitting a pull request, please run the tests:

flutter analyze
flutter test

Logging

dart devtools

Then run the app with the flutter run command above, and a link to the logging page will be printed in the console.

Internationalisation

Do not edit the app_en.arb file by hand, this file is generated. More information in the wiki.

Releasing

Only for members of lichess team.

1. Bump the pubspec.yaml version number. This can be in a PR making a change or a separate PR. Use semantic versioning to determine which part to increment. The version number after the + should also be incremented. For example 0.3.3+000303 with a patch should become 0.3.4+000304.
2. Run workflow Draft GitHub Release
3. Run workflow Deploy to Play Store

mobile's Issues

Add support for interactive lessons for studies.

It would be very helpful if the mobile app had the ability to do interactive lessons. It would be useful for people on the go or just testing their knowledge when they have a few moments to spare.

Character encoding issues in leaderboard.

As seen above there is an issue regarding the character encoding.

Reproduce:
Home -> leaderboard -> Danya06-2014

Cupertino text and button color

Apparently Cupertino takes the color from the Material 3 theme for the color of some buttons and text (at least with a dark theme)

_{It's not noticeable, but at first I thought I was going crazy :)}

Puzzle history

Offline puzzle history, using a new SQLite table.

We should store only the last n (2?) months of history. Deleting old items should be done at startup time, when opening the database, or with a cron job.

On main puzzle tab screen, only show the last 10 items. Tapping the "..." goes to the full history screen.

Tablet support needed here. See leaderboard screen for an example.

Mobile l10n

Right now the app is translated using Lila translations, which are themselves coming from crowdin.

We need to create another crowdin project to handle translations that are specific to the mobile app.

The update-arb-from-crowdin.mjs script need to be updated to fetch the new mobile translations.

User activity games 3 digit cutoff

Create the archived game screen

Waiting for https://github.com/lichess-org/dartchess/pull/3/files#diff-c2ae3eba35e66b624c14f65d90bb873671781e2f7ab4ceecf895de880a3d3ec4

Android phone is not locked in portrait

From discord feedback.

Add "Jump to next puzzle immediately" setting

I'd like to suggest a feature that already exists on the Lichess website:

"Jump to the next puzzle immediately"

It's a very simple but very useful setting: if it's enabled, the user gets a new puzzle immediately after solving one correctly. It makes solving puzzles a much faster and smoother experience.

I don't have to knowledge to do it, nor do I know how difficult it is to implement, but in my opinion a lot of users would find it useful. Let me know what you think, if it's possible and if there is someone who could/would implement it. Thanks!

Puzzle dashboard

Create the puzzle dashboard, like on lichess website: https://lichess.org/training/dashboard/30/dashboard

Corresponding lichess API: https://lichess.org/api#tag/Puzzles/operation/apiPuzzleDashboard

Suggestion of library to make the radar chart: https://pub.dev/packages/fl_chart

Encoding issue

A lot of people reported encoding issues on discord.

feature: replay puzzle by touching a score card

navigate through recent puzzle history using the rating diff boxes underneat the board.

Porting Issues

Not sure if there is a better way than this, but creating a bunch of new issues seems suboptimal.

https://github.com/lichess-org/lichobile/issues?q=is%3Aissue+author%3ADaniSpringer+is%3Aclosed

How can i actually use this app?

I've built the app in my own fork but when i try to sign in it redirects me to lichess.dev which is down.

Improve TV with variants

For this you have the lichess API:

• https://lichess.org/api#tag/TV/operation/tvChannels
• https://lichess.org/api#tag/Games/operation/streamGame

It should replace the existing stream that only shows the main TV.

It should filter out unsupported variants (crazy house, racing kings, horde).

TV channel selector at the top should use a widget adapted to the platform, that can be something similar to what is implemented here:

https://github.com/flutter/samples/blob/main/platform_design/lib/widgets.dart#L289

Missing thumbs up icon

I'm currently working on the user activity feed #24 .
When trying to make the gained x follower entry, I can't find the thumbs up icon in common/lichess_icons.dart.

Making the mobile App accessible with screen readers

As the mobile App will be rebuilt/rewritten, please keep accessibility with screen readers in mind. Though the website is accessible with screen readers, the app is nott and it would be great if the new App can be made accessible for visually impaired chess players.
Screen readers provide spoken feedback, which allows a VI to access the smartphone and other devices.

Improve loading with a shimmer effect

Using the technique described here: https://docs.flutter.dev/cookbook/effects/shimmer-loading

King in check board highlight

Black is in check but the red mark on the king does not show.

This issue also applies for white.

Steps to reproduce:
Go to puzzles.
Get in check as black.

App does not compile for android in release mode.

I have tried it to compile it on my personal machine and on github actions it always throws this error
Your project requires a newer version of the Kotlin Gradle plugin.

Which is something i dont understand since i have tried to update the version but the same error keeps happening.

Live streamers

Corresponding lichess API:

• https://lichess.org/api#tag/Users/operation/streamerLive

The widget should look similar to the already existing LeaderboardWidget. It is basically a PlatformCard with a dense ListTileTheme and a list of PlatformListTile inside. We may want to extract that into a custom widget here.

Tapping on a streamer item should open an external browser to the streaming platform (twitch, YouTube, ...).

Can I also be a part of creating this?

Hi devs, can I also be a part of the dev team for this app? 😄

pubspec.lock should be committed

To avoid problems with different dependencies, everybody should use the same versions. That is what pubspec.lock is for. It should be definitely committed.

Differentiate without color

App should indicate UI events visible with the assumption of grayscale

Progressive Web App

Rather than building an entire app from scratch, why not embrace the PWA standard more? https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps

The website already functions almost like a native app if added to the home screen on iOS. With some work on offline functionality/service workers the analysis engine/analysis board/games vs computer could work without a connection too.

Problem with timeago on android

Seen on user screen or profile screen, recent games section.

Android displays the wrong time, for instance it will display "A moment ago", while on iOS it is "10 hours ago". The right time is on iOS.

bottom_navigation translation problem?

I think the "home" tab should also be translated. "lib\src\widgets\bottom_navigation.dart" line 55.

Maybe the problem has already been voiced, but I couldn't find it...

...
 53   final tabs = [
 54     const _Tab(
 55       label: 'Home',
 56       icon: Icon(Icons.home),
 57      ),
...

crowdin.com seems to have this translation.

_27.03.2023

Board theme picker

Add a board theme picker in settings screen.

This feature depends on lichess-org/flutter-chessground#6.

A board thumbnail should be passed to the leading parameter of the settings list tile. This thumbnail should be an image consisting of 6 board squares aligned (a row). So that we can display the 6 pieces type over the board thumbnail. Thumbnail pixel ratio should be the same as the original board image, so the asset size should be 768*128.

Non visual board UI

A non visual board

To allow blind people to move pieces on a chessboard.

This feature is not that easy to do right. That's why we should start simple and improve later. If you know the subject, or are interested by it I'd be glad to get help. Come and join on discord to discuss it!

Implementation notes

Ideally, this should be done by a widget which should replace automatically GameBoardLayout if navigation by screen reader is detected in the current context.

final mediaQueryData = MediaQuery.of(context);
...   
 if (mediaQueryData.accessibleNavigation) {
      return NonVisualBoard(...);
    } else {
      return GameBoardLayout(...);
    }

Here's lichess.org implementation as a reference:

• https://github.com/lichess-org/lila/blob/master/ui/round/src/plugins/nvui.ts
• https://github.com/lichess-org/lila/blob/master/ui/nvui/src/chess.ts

List of commands that we should eventually support (not in the scope of this issue), for reference:

// play move should support SAN or UCI notation
// Example: e4, or e2 e4

// these commands are on lichess website
c: Read clocks.
l: Read last move.
o: Read name and rating of the opponent.
p: Read locations of a piece type. Example: p N, p k.
s: Read pieces on a rank or file. Example: s a, s 1.
abort: Abort game.
resign: Resign game.
draw: Offer or accept draw.
takeback: Offer or accept take back.

// extra commands needed for mobile since it does not have the virtual board
m: read possible moves for selected piece. Example: m e4

Puzzle.freezed.dart uses wrong type.

There is a type mismatch between the constructor function of the _PuzzleGamePlayer class and the PuzzleGamePlayer interface. Specifically, the constructor function expects a String type for the userId parameter, while the PuzzleGamePlayer interface expects a UserId type.

Stockfish build error

It happened both shortly before and after 4755882.
Ubuntu 22.10, mobile is android 13.

I've tried deleting ~/.pub-cache and .dart_tool multiple times but it never worked.

err_log.txt
flutter doctor -v.txt

option to view Lobby tab

there are many players who don't play 960 or other variants because of exhausting opponent finding process!

for example :
you create a 960 variant , 10+30 game.
i'm OK with 10+30 , 10+25 , 15+20 ,15+25 , 20+15 and .....
but i'm on mobile app and don't have lobby so i can't see your created game and the only way to pair is when i also create exactly 960 , 10+30 game!!

it's an old feature request :
lichess-org/lichobile#1149

is there any chance to add this feature?
thanks.

User activity feed

Add the user activity feed section on profile screen.

See it on lichess: https://lichess.org/@/veloce

API reference: https://lichess.org/api#tag/Users/operation/apiUserActivity

Design notes: the list should stay short, so we should show only the most important items, and keep one line per item. Example: don't show the followers in the "Gain X followers" item.

Ideally it should be place above the "recent games" section:

Chess engine integration

Hey Lichess devs, I made a chess engine in dart with beginner ELO strength it's written in Dart and free for use so if Lichess mobile will like to integrate it, note it has the engine logic, so can be used for testing/integration. not sure if it is needed right now, but I thought to reach out if needed in future.

https://github.com/jalpp/DartChessEngine

Thanks!

Perf stats screen

Create the performance screen for each time control and variant. Those screens are accessed from the corresponding "perf" card in the profile screen.

See on lichess.org:

• https://lichess.org/@/Shant7777777/perf/bullet
• https://lichess.org/@/veloce/perf/blitz

Note the difference between the first and second: the second correspond to the logged in user profile, the working is different.

See lichess API reference to obtain the data: https://lichess.org/api#tag/Users/operation/apiUserPerf

Android back button exits app instead of navigating back

Won't fix for now. Waiting for flutter/packages#2650

potential issues with flutter when using LineageOS

In the lichess announcement it was stated that this project would rely on Flutter. I just wanted to point you to this issue. I guess this is something to be aware of in case it will pop up here as I am sure it will.

Good luck with your endeavour, looking forward to the new app. :)

Leaderboard screen

Corresponding lichess page: https://lichess.org/player

Lichess API reference: https://lichess.org/api#tag/Users/operation/player

[iOS] sound conflict with other applications

When starting lichess app it turns off sound coming from another app. Same when a move is played.

Missing tests for AuthRepository

It should test the signIn, signOut, getAccount logic, checking the token is well saved and deleted and the _authState properly set at the same time.

TestFlight

Is there a TestFlight Beta we can join, as opposed to running flutter?

Sound theme picker

Add a new settings section to choose a sound theme (or silent).

Available sounds are listed here: https://github.com/lichess-org/lila/blob/master/modules/pref/src/main/SoundSet.scala

And the assets are here: https://github.com/lichess-org/lila/tree/master/public/sound

Game history agains anon

From discord. Games played against anon are showed as "Stockfish level null".

Accuracy Metric

The accuracy metric is useful and present on the site. Currently, the mobile app only shows average centipawn loss. Please display the accuracy metric in the mobile app as well.

Game history variants icons are showed as time control icons

Desktop Support

Would it be worthwhile to add MacOS/Windows/Linux as supported platforms? It would allow for these platforms to play even without an internet connection, and Flutter would make it simple to build anyway.

Create shareable PGNs from the app

Feature request which is mostly aimed at OTB players who want to share their games with friends. As a user I want to share PGNs via standard mobile methods, possibly from multiple places in the app:

• possibility to enter the moves of an OTB game in the analysis tool (or any other specific part of the app - you'll decide)
• make it easy to enter the most important corresponding tags: White, WhiteElo, Black, BlackElo, Date, Site, Event, Result, titles. Important: make the "Result" tag a multiple choice so that they don't have to type 1-0 themselves.
• share button which allows to copy the pgn and send it over the usual suspects: Messenger/Whatsapp/Signal etc.

The user flow would look like this:

1. They enter the moves of a game, either by hand (edit: Moving the pieces on the board) of by pasting an already-existing pgn
2. Optional: They enter the tags (button "pgn tags" - not sure about the wording though)
3. They click the button "share this game".
4. If the name tags are "Anonymous" or empty or if the result is "*", the user is prompted: "Do you want to enter the names of the players and the result before sharing the game?" If they click yes, go to step number 2 before proceeding to the last step
5. Open the dialog box which asks where to share the game with the usual options: copy pgn, usual IMs etc.

Stretch goals:

• possibility to enter clock times in minutes and insert them in the pgn (some players write the clock times on their scoresheet). Let me know if/when you want to proceed with this feature and if you have questions about it.
• possibility to save the game in a study (new or existing) and share it.

Puzzle Storm

This issue is about puzzle storm run only. It is linked to storm dashboard that will come with a separate issue.

Server API

GET /api/storm, works both with and without oauth. With oauth you get an extra high object of highscores.

{
    "high": {
        "allTime": 25,
        "day": 6,
        "month": 6,
        "week": 6
    },
    "key":"WbUQKHtY3N4Y",
    "puzzles": [
        {
            "fen": "2r3k1/pp3p1p/1n4p1/3Pb3/Pq5P/1Pr1BQP1/5PB1/1RR3K1 w - - 1 23",
            "id": "W73mR",
            "line": "g2h3 c3c1 b1c1 c8c1 e3c1 b4e1 g1g2 e1c1",
            "rating": 931
        },
        {
            "fen": "8/8/3Bp3/1k2P3/p5r1/2KR4/3N1r2/8 w - - 3 58",
            "id": "oG8Pr",
            "line": "d2b1 g4c4",
            "rating": 936
        },
        {
            "fen": "8/1p2kp2/p7/2p1b1p1/2P1P1Pp/1P2K2P/P3N3/8 w - - 0 38",
            "id": "bYvre",
            "line": "e2g1 e5d4 e3d2 d4g1",
            "rating": 949
        },
        {
            "fen": "8/6kp/6p1/8/1p6/5N2/5PPP/2b3K1 w - - 0 34",
            "id": "yUKEa",
            "line": "g1f1 b4b3 f1e2 b3b2 f3d2 c1d2",
            "rating": 967
        },
        ...
    ]
}

Implementation tips

• don't reuse the logic in puzzle_view_model.dart; here we use a tree data structure to enable move analysis and evaluation when the puzzle is completed but in storm we don't need that
• reuse the sounds of puzzle streak (for transition to next puzzle and failure)
• you may want to look at https://github.com/lichess-org/lila/blob/master/ui/storm/src/ctrl.ts to see some of the logic of website implementation
• come discuss on discord if you have questions

Live Streamers platform icons UI support

the Live streamers UI page in #42 should also be able to support the streamers' streaming platform icon below/above "English"

Free Twitch Icon:
https://www.flaticon.com/free-icon/twitch_4494567?term=twitch&page=1&position=9&origin=tag&related_id=4494567

Free YouTube Icon:
https://www.flaticon.com/free-icon/youtube_3670147?term=youtube&page=1&position=1&origin=search&related_id=3670147

Should be able to get the streamers' platform under "service" in https://lichess.org/api#tag/Users/operation/streamerLive

Thanks.

Material 3 custom color scheme

Currently the application uses a generated color scheme from a color seed:

mobile/lib/src/app.dart

Line 24 in bcdb25e

colorSchemeSeed: LichessColors.primary,

It would be nice to investigate creating a full custom color scheme, that would match more precisely lichess colors. See here for lichess theme definition: https://github.com/lichess-org/lila/tree/master/ui/common/css/theme

This color scheme can be built with the material theme builder tool.

It is easier to test it first using the material 3 demo app.