Skip to content

project-context.md

Latest commit

 

History

History
66 lines (53 loc) · 5.08 KB

project-context.md

File metadata and controls

66 lines (53 loc) · 5.08 KB
Raw

Project Context: Android Large Screen x Unity (Lost Crypt)

Overview

  • Core Intent: Demonstrates Android-optimized large-screen and foldable device capability (adaptive layouts, folding posture awareness, aspect ratio adjustments, and safe zone/notch calculations) in a 2D Unity environment, based on the Lost Crypt demo project.
  • Primary Users: Unity and mobile game developers seeking reference implementations for large screen and foldable Android devices (e.g., Google Pixel Fold).
  • Terminology:
    • Jetpack WindowManager: Google's library that provides support for multi-display, window features, and folding posture sensing.
    • FoldingFeature: Represents a hinge or fold in a display, providing the physical state (e.g., FLAT, HALF_OPENED) and bounds coordinates.
    • Safe Area: The area of the screen where UI components can be rendered without overlapping hardware notches, camera cutouts, or system navigation bars.

Technical Details

  • Tech Stack:
    • Engine: Unity Editor 6000.5.4f1 (see ProjectVersion.txt)
    • Languages: C# (Game logic/bridge), Java (Native Android override)
    • Frameworks/Libraries: Universal Render Pipeline (URP), Unity Input System, Android Jetpack WindowManager (androidx.window:window:1.3.0 & androidx.window:window-java:1.3.0).
  • Code Location: lsf-lostcrypt
  • Data Flow:
    • An orientation or fold event triggers on the Android OS level.
    • LargeScreenPlayableActivity.java receives the event via Jetpack WindowManager's WindowInfoTracker listener.
    • It serializes the display metrics or folding state into a JSON payload and calls UnityPlayer.UnitySendMessage("ConfigurationManager", "onConfigurationChanged" | "onFoldChanged", jsonString).
    • ConfigurationManager.cs receives the message, parses the JSON, and invokes actions/UnityEvents on the main Unity thread.
    • UI scripts like SafeZoneUI.cs react to adjust panel anchors relative to Screen.safeArea.
    • Gameplay response scripts like ConfigurationResponse.cs handle pausing the gameplay during resizing or fold state transitions.
  • Key Directories:
  • Build/Run Commands:
    • To run locally: Load the project root in Unity Editor 6000.5.4f1 and run scene Mainmenu.unity in Play mode.
    • Enable Resizable Windows (Editor): Run the menu tool Android Large Screen -> Add Resizeable Option to configure PlayerSettings automatically.
    • To build APK: Configure Android build target in Unity Build Settings and build standard Gradle package. Ensure custom manifest and settings are loaded.

Project Management

Documentation

  • README.md - General layout and description of subdirectories.
  • ABOUT.md - Details on aspect ratio support, full screen utilization, and foldable optimizations.
  • Assets/README.md - Specific mappings of files and folders inside the Unity Assets tree.
  • Assets/Scripts/README.md - Details of code responsibility breakdown.

Architecture Diagram

Architecture Diagram

AI Agent Tips

  • Common Tasks:
    • Updating responsive UI panels to handle different aspect ratios.
    • Extending configuration changes mapped in LargeScreenPlayableActivity.java or ConfigurationManager.cs (e.g. to support multi-display transition statuses).
    • Updating Android Jetpack dependencies inside mainTemplate.gradle.
  • Areas to be Careful:
    • Thread Safety: Ensure UI redraws and screen updates are called on the main Unity Thread (use ExecuteOnMainUnityThread helper coroutine inside ConfigurationManager.cs).
    • Manifest attributes: Ensure <activity> attributes in AndroidManifest.xml (e.g., android:resizeableActivity="true") remain active. Removing them will disable dynamic multi-window/fold resizing.