Cubiq
engineering.md구현

구현

Cubiq 내부

큐브를 돌릴 때마다 자체 시스템이 작동합니다. 수학 모델, 3D 엔진, 수업 목표를 고려하는 솔버로 구성됩니다. Android 앱은 Kotlin과 Jetpack Compose로 작성했습니다.

프로젝트 스냅샷

소스와 텍스트 리소스 줄
740 244
앱 모듈
39
테스트를 제외한 Kotlin 물리적 줄
136 019
언어 변형
42
테스트 선언test* / androidTest* · @Test
1 624

stack.kt

현대적인 Android 기술 스택

프로젝트 스냅샷
Kotlin2.4.21
Compose BOM2026.09.00
Material 31.5.0-beta01
Adaptive1.3.0
Navigation 31.2.0
AGP9.4.1
KSP2.3.12
Gradle9.7.0
  • Kotlin
  • Jetpack Compose
  • Material 3
  • Adaptive
  • Navigation 3

Jetpack Compose와 Material 3가 인터페이스의 구성 요소와 테마를 정합니다. Adaptive는 창 크기에 따른 배치를, Navigation 3는 탐색과 화면 복원을 담당합니다. 상태는 Coroutines와 Flow를 통해 전달되며, Hilt가 앱 모듈을 연결합니다.

architecture.kt

독립된 앱 계층

app01Hilt / DI
feature07Compose / ViewModel
  • onboarding
  • learning
  • lesson
  • practice
  • progress
  • settings
  • events
domain07contracts / use cases
  • learning
  • lesson
  • practice
  • portability
  • progress
  • settings
  • events
data09repositories / storage
  • content
  • storage
  • learning
  • lesson
  • practice
  • portability
  • progress
  • settings
  • events
core14UI kit / cube / solver
  • common
  • model
  • designsystem
  • uikit
  • navigation
  • analytics
  • crashlytics
  • ads
  • billing
  • push
  • hardware
  • cube
  • scrambleimage
  • solver
baselineprofile01startup / frame timing

feature → domain ← data

modulesΣ 39
  • app1
  • baselineprofile1
  • core14
  • data9
  • domain7
  • feature7
Kotlin · physical LOCΣ 136 019
feature
82 86360.9%
core
21 16715.6%
data
14 34110.5%
app
9 5147.0%
domain
6 7595.0%
buildSrc
9610.7%
baselineprofile
4140.3%

인터페이스, 도메인 계약, 데이터를 별도 모듈로 나누고 Hilt로 구현을 연결합니다. Compose는 불변 상태와 명시적인 이벤트를 받습니다. Room은 기록과 학습 진행 상황을, DataStore는 설정을 저장합니다. Navigation 3는 섹션의 스택을 복원합니다.

  • Coroutines / Flow
  • Hilt
  • Room
  • DataStore

android-ux.md

Android 권장사항에 따른 UX

Cubiq는 Google이 Apps Experience Program에서 강조하는 접근 방식을 구현합니다. Compose, 적응형 배치, edge-to-edge가 포함됩니다.

창 크기에 맞춘 배치
넓은 화면에서는 이론과 연습을 나란히 배치합니다. 작은 화면에서는 콘텐츠와 탐색을 사용 가능한 공간에 맞춥니다. 배치는 창 크기에 따라 결정됩니다.
네이티브 탐색
Edge-to-edge는 시스템 표시줄과 키보드를 고려합니다. Navigation 3는 섹션의 스택을 보존하고, 뒤로 이동할 화면을 미리 보여 주는 Predictive Back을 지원합니다.
가독성과 접근성
밝은 테마와 어두운 테마, 텍스트 크기 조절, 탐색의 시맨틱 레이블은 TalkBack과 키보드로 앱을 사용하는 데 도움이 됩니다. 글꼴을 크게 설정해도 섹션 이름은 스크린 리더로 읽을 수 있습니다.
Google 권장사항 · Apps Experience Program
OpenGL ES 3.0

engine.glsl

수학 모델을 따르는 기하 구조

moving cubies
26
facelets
54
meshes
8
triangles
2 964

GLSL 셰이더는 PBR 재질, 거칠기, 환경 조명을 계산합니다. 모델과 애니메이션은 일치하도록 동작합니다. 한 단계 뒤로 가면 역회전을 적용하고, 카메라는 패널 사이의 빈 공간을 고려합니다.

  • OpenGL ES 3.0
  • GLSL
  • PBR
  • Instancing

큐브 상태 / 공식 재생

타입이 지정된 표기를 회전 동작과 일관된 큐브 상태로 변환합니다. 렌더러 큐는 조각과 페이스렛의 동일성을 유지하면서 층 회전을 애니메이션으로 보여 줍니다. 공식은 실제 회전 동작의 순서로 재생하며, 재생, 일시정지, 속도 조절을 지원합니다.

  1. Notation
  2. Cube state
  3. Move queue
  4. OpenGL ES 3.0

앞으로 이동하면 새 동작을 애니메이션으로 보여 주고, 뒤로 이동하면 역회전을 적용합니다. 탐색 이동은 기본 장면과 목표 동작 순서를 복원합니다. 취소하면 다음 동작의 전달을 멈추지만, 이미 시작한 회전은 완료합니다. EGL 수명 주기는 pause/release를 처리합니다. GL을 사용할 수 없어도 3D 없이 학습을 이어 갈 수 있습니다.

solver.kt

수업 목표에 맞는 해법

  • BFS
  • Beam search
  • F2L

자체 솔버는 현재 수업의 공식과 보조 동작으로 해법을 만듭니다. SolverRequest는 큐브 상태, 목표 조각, 잠긴 목표, 허용된 공식, 사례, 방향을 포함합니다. 플래너는 학습 목표의 순서를 따르고 이미 맞춘 조각을 보호합니다.

단계별 계획에는 제한된 BFS, 빔 탐색, F2L 사례 인식을 사용합니다. 검증은 조각 구성, 뒤집힘, 비틀림, 순열의 패리티를 확인합니다. 탐색 정책은 깊이와 빔 너비를 제한합니다. 수업이 바뀌면 탐색을 취소하고 오래된 결과를 적용하지 않습니다.

결과는 PracticePlan으로, 단계, 공식 참조, 표시 타임라인, 실행 타임라인을 포함합니다. 설명은 학습용 방향을 유지하며, 엔진은 전체 실행 순서를 받습니다. 결과 유형은 plan / solved / invalid input / no constrained path입니다.

  1. 큐브 상태
  2. 모델 검증
  3. 학습 계획
  4. 3D 연습

content.md

빌드를 거치는 콘텐츠

이론은 Markdown 문서 756개에 저장하며, 연습은 현지화된 시나리오 336개로 정의합니다. Gradle은 번역 구조와 자체 제작한 삽화 316개의 참조를 검증합니다. 그래픽은 Blender/Cycles로 준비했습니다. Android 엔진은 별도의 절차적 기하 구조를 사용합니다.

workflow.md

문서를 코드로 관리 / 에이전트 작업

AGENTS.md
48
README.md
16

저장소는 에이전트 개발에 맞게 구성합니다. AGENTS.md 계층은 담당 범위, 아키텍처 제약, 검증 게이트를 정합니다. README.md는 모듈 계약을, KDoc는 API와 불변 조건을 설명합니다.

아키텍처, 디자인, 현지화 계약은 코드와 함께 버전 관리합니다. PLAN.md는 작업 범위와 인계를 기록하고, 계약이 바뀌면 이를 담당하는 문서도 갱신합니다. 검증과 생성은 Gradle로 실행하며, CI는 두 스토어 버전을 모두 빌드합니다.

physical text linesΣ 740 244
Resources / localization
399 56854.0%
Kotlin · non-test
136 01918.4%
Lesson Markdown
132 64217.9%
Kotlin · JVM tests
46 6456.3%
Kotlin · Android tests
13 6361.8%
Build tooling / web
8 9851.2%
Documentation
2 7490.4%
품질과 집계 방법

테스트는 불가능한 큐브 상태, 맞춘 층의 유지, 학습 계획, 오래된 요청 취소, 세션 복원, 데이터 가져오기를 다룹니다. CI는 두 스토어 버전을 모두 빌드합니다. 출시 검증에는 R8, APK/AAB, 체크섬, 16 KB 페이지에 맞춘 네이티브 라이브러리 정렬이 포함됩니다.

Kotlin 규모는 주석, 빈 줄, buildSrc, 벤치마크 코드를 포함하고 테스트 디렉터리를 제외한 물리적 줄 수로 집계합니다. 테스트 수는 JVM 선언 1 343개와 Android 선언 281개이며, 실행 횟수가 아닙니다. 문서에는 대체 텍스트가 포함됩니다. 시나리오가 있다고 해서 모든 수업에 연습이 있는 것은 아닙니다.

baselineprofile · @Test
3

전체 텍스트는 추적 대상 UTF-8 파일의 물리적 줄을 집계합니다. 소스, 테스트, XML/JSON 리소스, Markdown 콘텐츠, 현지화, 문서, 빌드 도구, 웹 소스가 대상입니다. 주석, 빈 줄, 언어별 사본을 포함합니다. 미디어, 생성물과 빌드 출력, 공급업체 코드, 서비스 설정, 임시 PLAN.md는 제외합니다. 프로젝트의 텍스트 입력 규모이며 실행 가능한 LOC가 아닙니다.

Cubiq 살펴보기