repository·master·Indexed 12 days ago
https://github.com/lichess-org/lilaThe open-source engine powering lichess.org, a free, realtime online chess server. Built with Scala 3, Play 2.8, and MongoDB, Lila provides features such as tournaments, computer analysis, and a shared analysis board. The project includes documentation on its architecture, UI theme management, the Lichess Fast Action Trainer, and guidelines for contributing flairs.
The gathering module provides reusable components designed to support specific Lichess game formats and event structures. It serves as a shared logic layer for the following modules:
modules/tournament: Logic for tournament management and participation.modules/swiss: Logic for Swiss-system tournament structures.modules/simul: Logic for simultaneous exhibition matches.Lila is free software distributed under the GNU Affero General Public License (AGPLv3), or any later version. You are permitted to redistribute and/or modify the project under these terms.
Important Notes:
LICENSE file in the repository.Lila (li[chess in sca]la) is a free online chess server built with the following core technologies:
scalachess submodule.lila-ws) communicating via Redis.Lichess uses a hybrid approach of SCSS and CSS variables to manage themes.
ui/lib/css/theme/ (e.g., _theme.default.scss, _theme.light.scss). The _theme.default.scss file serves as the foundation.--) scoped to an HTML class (e.g., html.example-theme).$c- that map to the CSS variables.Best Practice: Use the generated SCSS forms (e.g., $c-color) in your style rules instead of raw CSS variables whenever possible to ensure type safety and consistency.
// Example of how CSS variables are mapped to SCSS wrappers in ui/lib/css/theme/gen/_wrap.scss
$c-color: var(--c-color);
$c-color-desaturated: var(--c-color-desaturated);site module is the primary entry point for all non-embed client pages in the Lichess application. It is responsible for running the main application logic on standard web pages. Additionally, this module defines the window.site global object, which can be used to access site-level functionality from the browser environment.The background gallery system operates through a combination of server-side parsing and client-side rendering:
lila starts, it parses gallery.json once and includes the array of image URLs in all dasher responses.dasher parameters contain a gallery image array, the client constructs a URL to the appropriate thumbnail background (columns-2.webp or columns-4.webp).dasher params, the client falls back to legacy behavior.div elements (2 or 4 columns) over the montage background. These divs handle:The voice system uses specific terminology to manage how heard phrases are mapped to move and command processing logic:
| Term | Definition |
|---|---|
| grammar | A list of entries for input words recognized by Kaldi. |
| entry | A single grammar entry containing an input word, token representation, value code, classification tags, and a substitution list. |
| word | A unit of recognition (e.g., "long castle"). |
| phrase | One or more words separated by spaces. |
| tok | (Token) A single character uniquely representing the Kaldi-recognizable characteristics of an input word. |
| val | (Value) The representation of a token/word in terms the move & command processing logic understands. Mappings are not necessarily bijective (e.g., 'captures' and 'takes' share a val but have different toks). |
| xtoks | An exact phrase in the token space. |
| xvals | An exact phrase in the value space. |
| htoks | A heard phrase as a token string (may contain errors/ambiguities). |
| hvals | A heard phrase in the value space (comma-separated vals). |
| xtoks | An exact phrase in the token space. |
| xvals | An exact phrase in the value space. |
Prefix Convention:
x prefix: Represents exact data (what the system tries to map heard data to).h prefix: Represents heard data (the raw input from the user).lila project, bits are a collection of single-file modules designed for dynamic loading. They are used to provide modular functionality that can be loaded on demand, while still being able to export TypeScript types and loading stubs to ensure type safety and availability during the build or development process.To manage the background image gallery, follow these steps to prepare assets and generate the necessary metadata and montage files:
lifat/background/gallery. The gallery order is determined by the alphanumeric sort order of the filenames.make-gallery.js script.What the script does:
imagemagick to create columns-2.webp and columns-4.webp. These are montage images containing thumbnails rendered at 160x90px in 2-column and 4-column grids respectively.gallery.json, which contains an ordered array of image asset URLs mapped to their gallery positions.# Run the gallery generation script
node make-gallery.jsThe cron directory contains optional scripts designed to run on the lila server via cron. These scripts are primarily intended for production environments to manage database maintenance and background tasks. They are not required for local development.
Jobs are categorized by the database they target: the production database (prod db) and the puzzle database (puzzle db).
Each cron entry follows the standard format:
m h dom mon dow user command
### running on prod db
# m h dom mon dow user command
0 3 * * * root jobq -q mongo_decay mongosh --quiet 172.16.0.50:27017/lichess /home/lichess/deploy/cron/mongodb-report-score-decay.js
0 4 * * * root jobq -q mongo_queue mongosh --quiet 172.16.0.50:27017/lichess /home/lichess/deploy/cron/mongodb-queue-stats.js
0 5 * * * root jobq -q mongo_queue mongosh --quiet 172.16.0.50:27017/lichess /home/lichess/deploy/cron/mongodb-simul-cleanup.js
*/2 * * * * root jobq -q mongo_patron mongosh --quiet 172.16.0.50:27017/lichess /home/lichess/deploy/cron/mongodb-patron-denorm.js
26 * * * * root jobq -q mongo_patron mongosh --quiet 172.16.0.50:27017/lichess /home/lichess/deploy/cron/mongodb-ublog-similar-incremental.js
* * * * * root jobq -q mongo_fscday25 mongosh --quiet 172.16.0.50:27017/lichess /home/lichess/deploy/cron/mongodb-tournament-participation-trophies.js
### running on puzzle db
# m h dom mon dow user command
14 */2 * * * root jobq -q mongo_puzzles mongosh --quiet rubik:27017/puzzler /home/lichess/deploy/cron/mongodb-puzzle-denormalize-themes.js
27 */2 * * * root jobq -q mongo_puzzles mongosh --quiet rubik:27017/puzzler /home/lichess/deploy/cron/mongodb-puzzle-regen-paths.jsWhen you need a color variation, avoid creating a new unique variable if the color does not require a unique hue. Instead, use CSS functions to derive colors at runtime. This ensures the derived color remains theme-friendly when the user switches themes.
Recommended methods:
color-mix(): Mix two colors together.<color> syntax: Adjust hue, saturation, or lightness.calc(): Perform mathematical operations on color components.Example usage in SCSS:
// Mix 30% of the primary color with the font color
color: color-mix(in oklab, $c-primary 30%, $c-font);
// Lighten a background color by 20% using relative color syntax
background-color: hsl(from $c-bg h s calc(l + 20));color: color-mix(in oklab, $c-primary 30%, $c-font);
background-color: hsl(from $c-bg h s calc(l + 20));Use the ui/build script to generate assets for the website. When changes are compiled successfully, a new manifest is created, listing the public JavaScript and CSS assets. The server uses these manifests to communicate updated URLs to browsers.
To build once:
ui/buildTo run in watch mode (continuously rebuilds on changes):
ui/build -wui/build -w