Skip to content

Regalia v1.2.1

Choose a tag to compare

View all tags
@YDW99 YDW99 released this 14 Jul 02:38
· 5 commits to main since this release
v1.2.1
81cd0b6
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's New in v1.2.1

Full Changelog: https://github.com/YDW99/Regalia/releases/tag/v1.2.1/compare/v1.2.0...v1.2.1

Contributors

Bug Fixes

  • fix;docs;style;build (#43) (@YDW99) 83cc208

Build / CI

  • Update BUILDING.md with v1.2.1 notes and remove AI-GEN (@YDW99) 81cd0b6

Installation

Download the APK from the assets below and install it on your Android device.
Note: This app requires Stockfish chess engine binaries (libstockfish.so) to be built separately via NDK.

⚠️ Note: If you encounter any issues, please report them here.

Regalia v1.2.1 — Release Notes

A standalone, open-source chess app for Android — play offline against Stockfish 18, analyze your games, and explore openings. No account, no network, no tracking.

SonarQube Cloud
Lines of Code
Security Rating
Maintainability Rating
Vulnerabilities
Signing
Engine: Stockfish 18
License: AGPL v3
License: GPL v3
Platform: Android
Min SDK: 23
Target SDK: 35
Xiaomi HyperOS 3

📦 Download

File Size Description
Regalia-v1.2.1-release.apk ~75 MB Release APK — arm64-v8a only, Android 6.0+
Regalia-v1.2.1-manual-zh.html ~972 KB Chinese user manual (self-contained HTML)
Regalia-v1.2.1-manual-en.html ~1.1 MB English user manual (self-contained HTML)

⚠️ The engine binary is NOT included in the source tarball.
If you build from source, download the official Stockfish 18 arm64-v8a-dotprod binary separately. See BUILDING.md for instructions.

✨ What's New in v1.2.1

v1.2.1 is a same-version refinement release — no new features, no new permissions, no versionCode bump. It is the result of 15 rounds of iterative quality improvement on top of the v1.2.0 architecture refactor, driven by first-principles code audits, SonarCloud static analysis, and guidance from three reference PDFs (AI Code Generation Defect Prevention, Android WebView Development, SonarCloud Perfect Review).

🎯 Highlights

  • 3 SonarCloud Bugs fixed (PR #43): 2 real S3923 "if/else identical" issues + 1 S2757 false-positive refactor
  • 152 empty catch blocks eliminated (S108): 146 in chess.src/*.js + 6 in stats.html — all now log module-tagged console.warn
  • God Function refactors (S3776): renderInternal 347→23 lines, _renderDialogs 181→31 lines, _renderReviewMode 612→561 lines
  • 53 typeof modernizations (S2703): typeof x === 'undefined' → x === undefined for declared variables; true globals (crypto, AndroidBridge) correctly preserved
  • 2 user-reported bugs fixed: review eval chart not refreshing + stats page data completeness
  • 25 style unifications (S3523/S1154): parseFloat → Number.parseFloat, String.fromCharCode → String.fromCodePoint
  • 4 nested ternary refactors (S3358) + 2 duplicate CSS selector merges (S3646)

♟️ Features

Core Gameplay

Feature Description
Stockfish 18 engine World-class chess engine, arm64-v8a-dotprod build (ARMv8.6-A DOTPROD instruction set for accelerated NNUE inference)
8 difficulty levels Level 1 (beginner) → Level 7 (Skill Level mode) → Level 8 (⚙️ custom engine config)
Chess960 (Fischer Random) Full Chess960 support with SP-ID selector, back-rank preview, Shredder-FEN castling rights
Time controls Untimed / Sudden Death / Fischer Increment / Bronstein Delay / US Delay
Ponder mode Engine thinks on opponent's time for faster response
Undo/Redo Full move history navigation with redo stack
Setup mode Custom board positions with manual castle-rights (🔁) and en-passant (⚡) markers

Analysis & Review

Feature Description
Review mode Step through your game move-by-move with eval bar, trend chart, and move slider
Analyze All Batch-evaluate every move in the background; long-press to prioritize a specific step
Evaluation trend chart SVG line chart showing eval progression; auto-centers on the active move
Visual annotations [%csl] square highlights (B/R/G/Y) + [%cal] arrows; supports multi-color per square
Control heatmap 🌗/🌈 Board coloring showing piece control influence per square
Critical moves Auto-detected moves where evaluation changed significantly
Statistics page 📊 Full-game statistics: move quality distribution, eval trend, opening classification, PGN text

PGN Support

Feature Description
PGN import/export Standard PGN (1994 spec) with NAG, [%csl]/[%cal], [%eval], [%clk], [%emt]
PGN cache manager 📚 Save/load games locally with tags; partial-eval coverage dialog
FEN import/export Copy/paste FEN positions; setup-mode FEN with Shredder castling for Chess960
ECO opening classifier 500+ openings with search, family filter, and AI book moves
Lichess Syzygy tablebase 7-piece endgame tablebase queries (WDL/DTZ) via TLS-pinned API

User Experience

Feature Description
Bilingual UI 🇨🇳 Chinese / 🇬🇧 English, toggle from header; persists across sessions
Dark/Light theme Auto-follows system setting; optimized palettes for both modes
Sensor anti-shake Board stabilization via sensor fusion (optical-image-stabilization principle)
Haptic feedback Distinct vibration patterns for piece move, capture, check, game-over
Sound system Per-piece-type sound effects with move/capture/check/game-over variations
Coordinate labels a-h file labels + 1-8 rank labels + per-square coordinates on all boards
Responsive layout Portrait + landscape; notch/cutout/R-corner safe-area insets
SAF file picker Storage Access Framework for PGN export/import (no storage permission needed on API 29+)

🔒 Privacy & Security

Regalia is designed to be private by design.

  • 🚫 No account — no registration, no login, no user identification
  • 🚫 No tracking — no analytics, no telemetry, no crash reporting to remote servers
  • 🚫 No ads — no advertising SDKs, no ad network connections
  • 🌐 Offline-first — all gameplay is local; only optional tablebase queries use network (TLS-pinned)
  • 🔐 WebView hardened:
    • setAllowFileAccess(false)
    • setAllowFileAccessFromFileURLs(false)
    • setAllowUniversalAccessFromFileURLs(false)
    • @JavascriptInterface annotation on all exposed methods
    • URL scheme whitelist + sandbox path validation (JsBridgeGateway)
    • TLS 1.2+ enforcement + SPKI SHA-256 certificate pinning (TlsSecurityHelper)
  • 📁 Scoped storage — all file I/O via SAF content URIs (no direct file path access on API 29+)

Permissions

Permission Why
INTERNET Optional Lichess Syzygy tablebase queries (7-piece endgame)
ACCESS_NETWORK_STATE Check network availability before tablebase queries
WAKE_LOCK Keep engine alive during long analysis (foreground service, 30-min timeout)
VIBRATE Haptic feedback on moves/captures/checks
FOREGROUND_SERVICE Engine stability service (keeps Stockfish process alive)
FOREGROUND_SERVICE_SPECIAL_USE Android 14+ FGS subtype declaration (chess_engine_analysis)
POST_NOTIFICATIONS Android 13+ foreground service notification
WRITE_EXTERNAL_STORAGE (maxSdk 28) Legacy PGN export on Android 9 and below
READ_EXTERNAL_STORAGE (maxSdk 32) Legacy PGN import on Android 12 and below

See PRIVACY.md for the full privacy policy.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Java Layer                            │
│  ┌──────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │ MainActivity │──│ StockfishNative  │──│ EngineProcess │  │
│  │  (WebView    │  │  (Facade,        │  │  Manager      │  │
│  │   host)      │  │   @JsInterface)  │  │  (chmod)      │  │
│  └──────────────┘  └──────────────────┘  └───────────────┘  │
│         │                    │                    │          │
│         │           ┌────────┴────────┐    ┌──────┴──────┐   │
│         │           │ JsBridgeGateway │    │EngineHealth │   │
│         │           │ (sandbox + UCI  │    │  Monitor    │   │
│         │           │  whitelist)     │    └─────────────┘   │
│         │           └─────────────────┘                      │
│         │                                                    │
│  ┌──────┴──────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │ StatsActivity│  │ EngineService│  │ ChessWebViewClient│   │
│  │ (stats page) │  │ (FGS, keep-  │  │ (load, crash      │   │
│  └─────────────┘  │  alive)      │  │  recovery)         │   │
│                   └──────────────┘  └───────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   JNI Bridge      │
                    │  (engine_jni.cpp) │
                    └─────────┬─────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      JS Layer (WebView)                      │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │game-logic  │ │ chess960 │ │  pgn-    │ │ worker-pool  │  │
│  │  .js       │ │   .js    │ │standard  │ │    .js       │  │
│  │(rules,i18n)│ │(SP-ID,   │ │  .js     │ │(Web Workers) │  │
│  └────────────┘ │Shredder) │ │(encode/  │ └──────────────┘  │
│                 └──────────┘ │ decode)  │                    │
│  ┌────────────┐ ┌──────────┐ └──────────┘ ┌──────────────┐  │
│  │state-store │ │ai-bridge │ ┌──────────┐ │  eco-data    │  │
│  │   .js      │ │   .js    │ │tablebase │ │    .js       │  │
│  │(Redux-like)│ │(engine,  │ │   .js    │ │(ECO openings)│  │
│  └────────────┘ │ eval,PGN)│ │(Syzygy)  │ └──────────────┘  │
│                 └──────────┘ └──────────┘                    │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  ui.js  (rendering, dialogs, review, interaction)    │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Source Code Stats

Component Files Lines
Java 18 ~10,300
JavaScript 9 ~20,700
C++ (JNI) 1 ~100
HTML/CSS template 1 ~1,300
Total 29 ~32,400

🔧 Build & Verification

Build Environment

Tool Version
JDK Temurin 21.0.5+11
Android SDK API 35, Build-Tools 34.0.0
NDK 27.2.12479018
CMake 3.22.1
Gradle 8.11.1 (wrapper)
AGP 8.7.3
minSdk 23 (Android 6.0)
targetSdk 35 (Android 15)

APK Signature

Verified using v1 scheme (JAR signing): true
Verified using v2 scheme (APK Signature Scheme v2): true
Verified using v3 scheme (APK Signature Scheme v3): true

✅ v1 + v2 + v3 signatures all enabled — compatible with Xiaomi HyperOS 3 and all Android 6.0+ devices.

Engine Integrity

The Stockfish 18 arm64-v8a-dotprod binary is verified by three-way SHA-256 match:

Source binary:    8f7116d3f1a7004a6581d4fb0c1ff891ce095bab6d45e52f1578897cf23b61b5
jniLibs copy:     8f7116d3f1a7004a6581d4fb0c1ff891ce095bab6d45e52f1578897cf23b61b5
APK-internal:     8f7116d3f1a7004a6581d4fb0c1ff891ce095bab6d45e52f1578897cf23b61b5

✅ All three match — the engine binary is the official Stockfish 18 dotprod build, unmodified.

📜 License

Regalia is a combined work under dual licensing:

Component License
Original application code (UI, WebView, services, build scripts, manuals) AGPL v3
DroidFish-derived code (engine management, game logic, PGN parsing, UI patterns) GPL v3
Stockfish 18 engine binary (libstockfish.so) GPL v3
ECO opening data CC0 (data) / AGPL v3 (code)
Application icons AI-generated / AGPL v3

Per GPL v3 Section 13, these licenses are compatible for combination. Each component retains its original license. Since AGPL v3 imposes stricter network interaction provisions (Section 13), its obligations effectively extend to the entire combined work.

License Files

File Description
LICENSE AGPL v3 full text (alias for GitHub/F-Droid auto-detection)
LICENSE-AGPL v3 AGPL v3 full text (application)
LICENSE-GPL v3 GPL v3 full text (engine + DroidFish-derived)
LICENSE-Apache v2.0 Apache v2.0 (Gradle)
NOTICE Third-party component notices + version history
NOTICE-DroidFish Original DroidFish notice
NOTICE-gradle Gradle notice

📚 Documentation

Document Description
README.md Project overview, directory tree, licensing
BUILDING.md Full build instructions (engine download, keystore, Gradle)
PRIVACY.md Privacy policy (permissions, data flow, security)
SECURITY_FIXES.md Security fix history
UBIQUITOUS_LANGUAGE.md Domain terminology glossary (80+ chess/engine/PGN/UI terms)
CONTRIBUTING-zh.md Contribution guidelines (Chinese)
CONTRIBUTING-en.md Contribution guidelines (English)
Manual/Regalia-v1.2.1-manual-zh.html Chinese user manual
Manual/Regalia-v1.2.1-manual-en.html English user manual

Each source directory also has a README.license file classifying every file's license:

src/main/README.license
src/main/assets/README.license
src/main/assets/chess.src/README.license
src/main/java/com/Regalia/README.license
src/main/cpp/README.license
src/main/res/README.license
Manual/README.license

🔄 Version History Summary

v1.2.1 (versionCode 121) — Current Release

Same-version refinement, 15 rounds of quality improvement:

📖 Click to expand full changelog

Round 15 (2026.7.14) — Final Perfection

  • S3776 _renderReviewMode partial extraction (612→561 lines): _buildRvFileLabels, _buildRvRankLabels, _prepareRvVisualAnnotations
  • S108 stats.html empty catches (6 sites): console.warn('[Stats]', e.message)
  • PDF-guided audit: AI Defect Guide ✓, WebView Guide ✓, SonarCloud Guide ✓

Round 14 (2026.7.14) — _renderDialogs + typeof

  • S3776 _renderDialogs refactor (181→31 lines): 8 per-dialog helpers
  • S2703 typeof audit (53 conversions): declared vars → direct === undefined; true globals preserved

Round 13 (2026.7.14) — renderInternal God Function

  • S3776 renderInternal refactor (347→23 lines): _buildRenderHTML, _saveScrollState, _restoreScrollState, _postRenderFinalize

Round 12 (2026.7.14) — SonarCloud PR #43

  • 3 SonarCloud Bugs fixed (S3923 ×2 real, S2757 ×1 false-positive refactor)
  • S108 empty catches (146 sites across 5 JS files)
  • S3358 nested ternary (2 sites), S3646 duplicate CSS (2 sites)
  • S3523 parseFloat (7 sites), S1154 fromCharCode (18 sites)

Round 11 (2026.7.14) — 2 User-Reported Bugs

  • Bug #1: review eval chart not refreshing on eval completion
  • Bug #2: stats page data completeness varied by selected move (10-min safety timeout)
  • Review-report non-false-positive defects (5 items)

Round 10 (2026.7.14) — Deep review-D/E/F fix

  • 13 P2/P3 items: concurrency hardening, URL scheme case-insensitivity, HapticHelper dead-code removal, magic-number extraction, build-config cleanup

Round 9 (2026.7.13) — First-principles code review

  • 22 items (7 P1 + 11 P2 + 4 P3) from 6 parallel review agents covering ~32K lines

Round 8 (2026.7.13) — TDZ white-screen bug fix

  • state-store.js DEEP_CLONE_MAX_DEPTH declaration moved to IIFE top (TDZ violation fix)

Round 7 (2026.7.13) — Phase 62 revert + security hardening

  • Phase 62 imported flag control reverted; secureRandomInt safe-fail; structured postJsCallback

Rounds 1-6 (2026.7.12-13) — Initial defect fix + 4 parallel review agents

  • P0 TOCTOU race fix, P1 Chess960 symmetry, P1 eval-mode option leak, P1 sandbox hardening, 16+ critical fixes

v1.2.0 (versionCode 120) — Previous Release

Architecture refactor major version:

  • Java God Module split: StockfishNative.java (5,443→4,492 lines) → Facade + 11 manager/helper classes
  • JS God Module split: ui.js (8,245→8,061 lines) → 4 new modules + sub-function decomposition
  • SonarCloud: All 42 Bugs fixed, 5 Vulnerabilities fixed, _buildPGNString decomposed
  • Review board coordinate labels (Phase 77→83)

🚀 Install

From Pre-built APK

  1. Download Regalia-v1.2.1-release.apk to your Android device (arm64-v8a, Android 6.0+)
  2. Allow "Install from unknown sources" in Settings if prompted
  3. Tap the APK to install

Build from Source

# 1. Extract source
tar xzf Regalia-v1.2.1-src.tar.gz
cd Regalia-v1.2.1-src

# 2. Download Stockfish 18 arm64-v8a-dotprod binary (NOT in tarball)
mkdir -p src/main/jniLibs/arm64-v8a
tar xf stockfish-android-armv8-dotprod.tar
cp stockfish/stockfish-android-armv8-dotprod src/main/jniLibs/arm64-v8a/libstockfish.so
chmod +x src/main/jniLibs/arm64-v8a/libstockfish.so

# 3. Configure SDK path
echo "sdk.dir=/path/to/Android/SDK" > local.properties

# 4. Configure keystore (see BUILDING.md §Signing)

# 5. Build chess.html (merge JS modules)
python3 build-chess.py

# 6. Build release APK
./gradlew assembleRelease -x lint -x lintRelease -x lintVitalRelease --no-daemon

See BUILDING.md for full instructions.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING-en.md (or CONTRIBUTING-zh.md for Chinese) before submitting a pull request.

Development Setup

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

Code Quality

  • All JavaScript modules must pass node --check
  • state-store.js must load cleanly in a Node vm context (no TDZ violations)
  • Follow the existing code style: _camelCase for private functions, camelCase for public
  • Add JSDoc comments for all new functions
  • Update NOTICE, README.md, and the relevant README.license for any new files

📄 Citation

If you use Regalia in your research or project, please cite:

@software{regalia_chess,
  title  = {Regalia: A Standalone Open-Source Chess App for Android},
  author = {Regalia Contributors},
  year   = {2026},
  version= {1.2.1},
  url    = {https://github.com/YDW99/Regalia},
  note   = {Powered by Stockfish 18 (arm64-v8a-dotprod). AGPL v3 + GPL v3 dual-licensed.}
}

🙏 Acknowledgments

  • Stockfish — The world-class chess engine that powers Regalia's analysis
  • DroidFish — Peter Österlund's Android chess app; Regalia's engine management and game logic are derived from DroidFish
  • Lichess — For the Syzygy tablebase API and ECO opening data
  • All contributors who have helped shape Regalia through code reviews, bug reports, and feature suggestions

⚠️ Disclaimer

"Regalia" is used solely as a project name for this open-source chess app. No trademark rights are claimed. Anyone is free to fork and rename their own version.

Chess piece symbols (♔♕♖♗♘♙ ♚♛♜♝♞♟) are Unicode characters and are rendered using the device's system fonts.

This software is provided "as is", without warranty of any kind. See the license files for complete terms.

📊 Stats

Metric Value
Version Code 121
Version Name 1.2.1
APK Size 78,137,493 bytes (~75 MB)
Source Tarball 4,751,464 bytes (~4.6 MB)
Source Files 112 (excluding build artifacts)
Total Lines of Code ~32,400
Java Files 18
JavaScript Files 9
Minimum Android 6.0 (API 23)
Target Android 15 (API 35)
Architecture arm64-v8a only
Engine Stockfish 18 (dotprod)
Signatures v1 + v2 + v3
License AGPL v3 + GPL v3

♔ Built with care for chess enthusiasts who value privacy, openness, and quality. ♚

AI-GEN

Contributors

YDW99
Assets 7
Loading
0 Join discussion