Implementation
Every cube turn relies on a custom system: a mathematical model, a 3D engine, and a solver that accounts for lesson goals. The Android app uses Kotlin and Jetpack Compose.
Project snapshot
test* / androidTest* · @Teststack.kt
| Kotlin | 2.4.21 |
|---|---|
| Compose BOM | 2026.09.00 |
| Material 3 | 1.5.0-beta01 |
| Adaptive | 1.3.0 |
| Navigation 3 | 1.2.0 |
| AGP | 9.4.1 |
| KSP | 2.3.12 |
| Gradle | 9.7.0 |
Jetpack Compose and Material 3 define interface components and themes. Adaptive handles layout by window size, while Navigation 3 handles navigation and screen restoration. State arrives through Coroutines and Flow; Hilt connects the app modules.
architecture.kt
app01Hilt / DIfeature07Compose / ViewModelonboardinglearninglessonpracticeprogresssettingseventsdomain07contracts / use caseslearninglessonpracticeportabilityprogresssettingseventsdata09repositories / storagecontentstoragelearninglessonpracticeportabilityprogresssettingseventscore14UI kit / cube / solvercommonmodeldesignsystemuikitnavigationanalyticscrashlyticsadsbillingpushhardwarecubescrambleimagesolverbaselineprofile01startup / frame timingfeature → domain ← data
modulesΣ 39app1baselineprofile1core14data9domain7feature7Kotlin · physical LOCΣ 136 019featurecoredataappdomainbuildSrcbaselineprofileThe interface, domain contracts, and data have separate modules; Hilt connects their implementations. Compose receives immutable state and explicit events. Room stores history and learning progress, DataStore stores settings, and Navigation 3 restores section stacks.
android-ux.md
Cubiq implements approaches Google highlights in the Apps Experience Program: Compose, adaptive layout, and edge-to-edge.
engine.glsl
GLSL shaders calculate PBR materials, roughness, and environment lighting. The model and animation stay in sync: stepping back applies the inverse move, and the camera accounts for the space between panels.
Typed notation converts into moves and consistent cube states. The renderer queue animates layer turns while preserving piece and facelet identities. A formula plays as a sequence of real moves, with play/pause and tempo controls.
Stepping forward animates a new move; stepping back applies the inverse move. Seeking restores the base scene and target sequence. Cancellation stops issuing further moves; a turn already started completes. The EGL lifecycle handles pause/release; if GL is unavailable, the learning path remains usable without 3D.
solver.kt
The custom solver builds a solution from the current lesson's formulas and auxiliary moves. SolverRequest includes cube state, target pieces, locked targets, allowed formulas, cases, and orientation. The planner respects the order of learning goals and protects pieces already solved.
Phase-specific planning uses bounded BFS, beam search, and F2L case recognition. Validation checks piece composition, flips/twists, and permutation parity. Search policy limits depth/beam width. Changing the lesson cancels the search and prevents an outdated result.
The result is a PracticePlan: steps, formula references, a display timeline, and an execution timeline. Explanations preserve the lesson orientation; the engine receives the full execution sequence. Outcomes: plan / solved / invalid input / no constrained path.
content.md
Theory lives in 756 Markdown documents, and practice is defined in 336 localized scenarios. Gradle validates translation structure and references to 316 original illustrations. Graphics were prepared in Blender/Cycles; the Android engine uses separate procedural geometry.
workflow.md
AGENTS.mdREADME.mdThe repository is organized for agent development: the AGENTS.md hierarchy defines ownership, architectural constraints, and validation gates; README.md files describe module contracts, while KDoc describes API and invariants.
Architecture, design, and localization contracts are versioned alongside the code. PLAN.md records scope and handoff; contract changes include updates to the owner docs. Checks and generation run through Gradle; CI builds both store variants.
physical text linesΣ 740 244Resources / localizationKotlin · non-testLesson MarkdownKotlin · JVM testsKotlin · Android testsBuild tooling / webDocumentationTests cover impossible cube states, preserving solved layers, learning plans, canceling outdated requests, session restoration, and data import. CI builds both store variants; release checks cover R8, APK/AAB, checksums, and native library alignment for 16 KB pages.
Kotlin volume counts physical lines, including comments, blank lines, buildSrc, and benchmark code, excluding test directories. The test count means 1 343 JVM declarations and 281 Android declarations, not executions. Documents include fallback text; a scenario's presence does not mean every lesson includes practice.
baselineprofile · @TestTotal text counts physical lines in tracked UTF-8 source, tests, XML/JSON resources, Markdown content, localization, documentation, build tooling, and web source. Comments, blank lines, and locale copies are included. Media, generated/build output, vendor code, service config, and the temporary PLAN.md are excluded. This measures the project's text inputs, not executable LOC.