MosisService/docs/PLAN.md

MosisService Implementation Plan

Overview

This document outlines the implementation plan for adding Lua scripting support to the MosisService project, enabling interactive UI elements that can execute Lua code.

Project Analysis

Current Architecture

The project consists of:

1. Kotlin-based Android UI components
2. Two native C++ libraries (mosis-service and mosis-test)
3. RmlUi-based UI rendering engine
4. Android Binder service integration
5. OpenGL ES 2.0 rendering pipeline

Build System

• Android Studio with Gradle
• CMake build system
• Android NDK (version 29.0.14206865)
• vcpkg for dependency management

Implementation Steps

Phase 1: Enable Lua Support in Build System

1. Update vcpkg.json

   • Verify RmlUi package includes Lua support
   • Add necessary Lua dependency if not included

2. Modify CMakeLists.txt

   • Add RmlUi Lua binding options
   • Configure proper linking with Lua libraries
   • Set compiler flags for maximum feedback

Phase 2: Integrate Lua in Core Engine

1. Update kernel.cpp

   • Include RmlUi/Lua.h header
   • Add Lua initialization call after main RmlUi initialization
   • Register C++ functions accessible from Lua scripts

2. Configure Build with Debug Flags

   • Enable all compiler warnings
   • Add debugging symbols
   • Enable sanitizers for memory and undefined behavior checks

Phase 3: UI Integration

1. Modify demo.rml

   • Add center button element
   • Position button using CSS transforms
   • Implement onclick handler that calls registered Lua function

2. Add CSS Styles

   • Create centered positioning for UI elements
   • Style the button appropriately
   • Ensure proper z-index for overlay elements

Phase 4: Script Execution

1. Create Lua Function Registration
   • Register C++ functions that interact with Android services
   • Implement callback mechanisms for UI events
   • Handle error cases in script execution

Phase 5: Testing and Validation

1. Verify Build with Debug Feedback

   • Compile with all warnings enabled
   • Test compilation with sanitizers
   • Validate debug symbol generation

2. Functional Testing

   • Test button click functionality
   • Verify Lua script execution
   • Validate UI updates from script execution

Specific Technical Requirements

CMake Configuration Changes

In CMakeLists.txt:

# Enable Lua bindings for RmlUi
# Add after find_package(RmlUi CONFIG REQUIRED)
set(RMLUI_LUA_BINDINGS ON)
set(RML_LUA_BINDINGS_LIBRARY lua_as_cxx)

# Link with Lua libraries if needed
# target_link_libraries(mosis-service RmlUi::RmlUi RmlUi::Lua)

Kernel Integration

In kernel.cpp:

#include <RmlUi/Lua.h>

// In main_loop() after Rml::Initialise():
Rml::Lua::Initialise();

// Register functions that can be called from RML
// Example of registering a basic callback
Rml::Lua::RegisterGlobalFunction("handleButtonClick", []() {
    Logger::Log("Button clicked via Lua!");
    // Add actual implementation
});

RML Button Implementation

In demo.rml:

<div id="center-button-container">
  <button id="trigger-button" onclick="handleButtonClick()">Execute Script</button>
</div>

CSS Styling

Add to CSS:

#center-button-container {
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    z-index: 1000;
}

#trigger-button {
    font-size: 2em;
    padding: 20px 40px;
    background-color: #3498db;
    color: white;
    border: none;
    border-radius: 10px;
    cursor: pointer;
    text-align: center;
}

Build Commands for Maximum Feedback

Debug Build with All Warnings

./gradlew clean && ./gradlew assembleDebug 
  --warning-mode all 
  --info 
  --stacktrace 
  -Pandroid.jetifier.enable=true

Compilation with Sanitizers

cmake -DCMAKE_BUILD_TYPE=Debug 
      -DCMAKE_CXX_FLAGS_DEBUG="-g -O0 -Wall -Wextra -Wpedantic -Werror -fsanitize=address,undefined" 
      .

Expected Outcome

After implementation, the UI will:

1. Display a center button in the demo interface
2. Allow button clicks to trigger Lua scripts
3. Execute registered C++ functions through Lua
4. Provide full build feedback with debug symbols
5. Support all compiler warnings and sanitization

Validation Steps

1. Successful compilation with no errors or warnings
2. UI renders with centered button
3. Button click executes Lua script successfully
4. Debug symbols present in native libraries
5. No memory leaks detected by sanitizers