Mate-Engine for macOS (Unofficial Port)

⚠️ Notice / 注意: This is an UNOFFICIAL port of Mate-Engine. This project is currently in the Early Development / Experimental Phase. It is NOT ready for end-users yet.

本專案為 Mate-Engine 的 非官方 macOS 移植版本。 目前處於 早期開發/實驗階段，尚未開發完成，不適合一般使用者下載使用。

🚧 Current Status / 目前狀態

• Status: Pre-Alpha (Testing & Porting)
• Target Platform: macOS (Apple Silicon & Intel)
• Engine: Unity

This branch focuses on replacing Windows-specific APIs (User32.dll, dwmapi.dll) with macOS Native APIs (Cocoa/AppKit) to achieve transparency, click-through, and window interactions.

此分支專注於將原專案中依賴 Windows API 的功能（如透明視窗、滑鼠穿透），替換為 macOS 原生 API (Cocoa/AppKit)。

🗺️ Development Roadmap / 開發路線圖

We are currently working on the following tasks. Checked items [x] are completed. 我們目前正在進行以下移植工作。打勾 [x] 代表已完成。

Phase 1: Environment Setup (基礎建設)

• Fork & Cleanup: Isolate Windows-only code using preprocessor directives (#if UNITY_STANDALONE_WIN).
  • 目標：解決在 Mac 上開啟專案時的大量編譯錯誤 (Compiler Errors)。
• Build Pipeline: Ensure the project can successfully build a basic (non-transparent) app on macOS.
  • 目標：確保能編譯出一個基本的 Mac 應用程式（即使還沒有透明背景）。

Phase 2: Core Window Features (核心視窗功能)

• Transparent Window: Implement NSWindow transparency and remove window borders/title bars via Objective-C bridge.
  • 目標：實作 Mac 原生的透明無邊框視窗。
• Window Level (Always on Top): Implement NSWindowLevel to keep the character above other windows.
  • 目標：讓角色視窗永遠置頂。
• Mouse Click-through: Implement dynamic ignoresMouseEvents logic using Raycasting.
  • 目標：實作動態滑鼠穿透（點擊角色時互動，點擊空白處時穿透）。

Phase 3: System Interaction (系統互動)

• Permissions Management: Handle "Screen Recording" and "Accessibility" permission requests.
  • 目標：處理 macOS 的權限請求（螢幕錄製與輔助使用權限）。
• Window Detection: Use CoreGraphics to detect other windows' positions (for "Sitting" feature).
  • 目標：偵測其他視窗座標，支援「坐在視窗上」的功能。
• Dock Interaction: Detect macOS Dock height and adjust the character's floor level.
  • 目標：適應 Mac Dock 的高度變化，讓角色能站在 Dock 上。

🛠️ For Developers / 開發者指南

If you want to help porting this project: 如果你想協助移植：

1. Clone this repository.
2. Open in Unity (Version matches original repo).
3. Switch Platform to macOS in Build Settings.
4. Check the Assets/Scripts/MacOS folder (TBD) for native bridges.

Known Technical Challenges:

• Native Plugin: We need to write a .bundle or direct C# to Objective-C bridge for window management.
• Sandboxing: Window detection requires explicit permissions on macOS.

📄 License & Credits

• Original Project: Mate-Engine by shinyflvre.
• License: Follows the original project's license (GNU AGPL v3 & MateProv2).
• Assets: Default avatars and assets belong to their original creators/Yorshka Shop.

---

Created for the community to bring Mate-Engine to Mac.