MosisService/docs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Company

OmixLab LTD - Package namespace: com.omixlab

Git Commit Guidelines

IMPORTANT: When creating git commits:

• DO NOT add yourself as a co-author (no Co-Authored-By lines)
• Commit messages must be a single line - keep it concise and descriptive

Project Overview

Mosis is a virtual smartphone OS for VR games and applications. It provides a phone-like device that users can interact with inside VR environments, with real smartphone functionality.

Current Status

Component	Status	Notes
MosisService	✅ Working	RmlUi rendering, touch input, navigation
App Management	✅ Working	Install/uninstall apps, sandbox integration
Lua Sandbox	✅ Working	149 security tests passing
Desktop Designer	✅ Working	Hot-reload, shell mode, hierarchy dump, recording
Designer Tests	✅ 5/5 Passing	Navigation tests automated
MosisVR (Unity)	✅ Building	OpenGL backend working, Vulkan in progress
MosisUnreal	✅ Working	Vulkan texture import via UE5 RHI, phone actor with mesh

Project Components

Component	Location	Purpose
Android Service	src/main/	Native service running RmlUi renderer
App Management	src/main/cpp/apps/	App install/uninstall/launch with sandbox
Lua Sandbox	src/main/cpp/sandbox/	Per-app Lua isolation (22 modules)
System Shell	src/main/assets/apps/shell/	Persistent status bar, nav bar, overlays
Desktop Designer	designer/	UI development with hot-reload
Designer Tests	designer-test/	Automated UI testing framework
Sandbox Tests	sandbox-test/	Lua sandbox security tests (149 tests)
UI Assets	src/main/assets/	Shared RML/RCSS/Lua assets

Detailed Documentation

All detailed documentation is in docs/:

Document	Description
BUILD-COMMANDS.md	Android, Desktop Designer, and test build commands
ARCHITECTURE.md	Native libraries, IPC flow, code structure
DESKTOP-DESIGNER.md	Shell architecture, hot-reload, recording
TESTING-FRAMEWORK.md	Automated UI testing, writing tests
UI-ASSETS.md	Asset structure, navigation system, element IDs
MATERIAL-DESIGN.md	Icons, MDL components, usage guide
ANDROID-TESTING.md	ADB commands, event injection, logs
GAME-ENGINES.md	Unreal & Unity integration, Vulkan import
DEVELOPER-PORTAL.md	Portal architecture, milestones
APP-MANAGEMENT.md	Package format, manifest, lifecycle
LUA-SANDBOX.md	Security features, permissions, APIs

Quick Reference

Environment Requirements

• ANDROID_HOME - Android SDK path
• ANDROID_NDK_HOME - Android NDK path (version 29.0.14206865)
• VCPKG_ROOT - vcpkg package manager root

Common Build Commands

# Android APK
./gradlew assembleDebug

# Desktop Designer (from designer/)
cmake -B build -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Debug

# Sandbox Tests (from sandbox-test/)
./run_tests.bat

Code Style

• C++23 standard with modern features (std::span, std::format)
• PascalCase for classes/functions, camelCase for variables
• RAII principles with smart pointers
• Kotlin code follows Android conventions

Dependencies

• vcpkg: RmlUi, GLFW, Freetype, Lua, libpng, nlohmann-json, minizip, sqlite3
• Android: arm64-v8a only
• Desktop: Windows x64 (MSVC)

Documentation Guidelines

IMPORTANT: Always document progress and new commands to avoid rediscovery.

Content Type	Location
General concepts, architecture	MosisService/docs/CLAUDE.md or docs/
Unreal plugin docs	MosisUnreal/Plugins/MosisSDK/README.md
Unity package docs	MosisVR/Packages/com.omixlab.mosis_sdk/README.md

DO NOT put documentation in the root D:\Dev\Mosis\ directory - it is not versioned.