README.md

metadata

title: Riaslink Port Builder
emoji: 🏮
colorFrom: yellow
colorTo: red
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0

Riaslink Port Builder

Bir RPG Maker MV/MZ web dışa aktarımını (www/ klasörü) Android APK'ya dönüştürür ve oyuna otomatik olarak taverna temalı bir menü ile FPS sayacı eklentisi enjekte eder.

Bu Space, Ludens projesinden yalnızca "Android WebView port" fikrini ödünç alır (Ludens'in kod tabanı doğrudan kullanılmaz); menü, eklentiler ve build pipeline'ı sıfırdan yazılmıştır. Ayrıntılar için android-template/README.md dosyasına bakabilirsin.

Mimari

Arayüz düz FastAPI + statik HTML/CSS/JS ile yazılmıştır — hiçbir UI framework'ü (Gradio, Streamlit vb.) kullanılmaz. Bunun nedeni tarihsel: ilk sürüm Gradio ile yazılmıştı, ama o sürümün kullandığı Gradio sürümünde (5.9.1) art arda farklı iç route/şema hataları çıktı — her düzeltme farklı bir iç mekanizmayı bozdu. Az sayıda, sade route'a sahip kendi FastAPI uygulamamızı yazmak, üzerinde kontrolümüz olmayan bir kütüphanenin iç davranışına bağımlı kalmaktan daha güvenilir çıktı.

hf-space/
├── app.py              FastAPI backend: form, build başlatma, SSE log akışı, indirme
├── build_pipeline.py   Asıl iş: zip enjeksiyonu, plugin kaydı, Gradle çağrısı
├── static/
│   ├── index.html      Build formu (taverna temalı)
│   ├── style.css        Aynı --ria-* renk paleti, RIA_TavernMenu.js ile tutarlı
│   └── app.js            Form gönderimi, sürükle-bırak, canlı log (Server-Sent Events)
└── android-template/    Native Android port + menü eklentileri (bkz. kendi README'si)

Backend route'ları:

Route	Ne yapar
GET /	Build formunu döner (static/index.html)
POST /api/build	Formu + zip'i alır, arka planda build başlatır, {build_id} döner
GET /api/build/{id}/stream	Server-Sent Events ile canlı log satırları
GET /api/build/{id}/download	Tamamlanan APK'yı indirir

Her build, bellekte tutulan bir BuildState nesnesiyle takip edilir (log satırları + durum). stream_build_log, bu state'i yarım saniyede bir kontrol edip yeni log satırlarını tarayıcıya SSE ile akıtır; build bitince (success ya da failed) akış otomatik kapanır ve indirme linki (varsa) gösterilir. Tek process içinde çalıştığı için harici bir kuyruk/veritabanı gerekmez — bu, tek instance'lı bir Space için yeterlidir.

Nasıl çalışır

1. RPG Maker'da projeni web'e dışa aktar (Deploy Masterpiece).
2. Oluşan www klasörünü (ya da içeriğini) zip'le.
3. Bu Space'e yükle, uygulama adı / paket adı / versiyon bilgilerini gir.
4. "APK Oluştur" — arka planda android-template/ projesi kopyalanır, www/ senin oyununla değiştirilir, RIA_FPSCounter.js ve RIA_TavernMenu.js eklentileri js/plugins/ altına konur ve projenin kendi js/plugins.js dosyasına (mevcut eklentilerine dokunmadan) kaydedilir, ardından Gradle ile APK derlenir. Build günlüğü sağ panelde canlı olarak akar.

Release imzalama

Release APK'lar varsayılan olarak konteynerin debug anahtarıyla imzalanır (kurulabilir, ama Space yeniden başladığında anahtar değişir ve yeni sürüm eskisinin üzerine güncelleme olarak kurulamaz). Kalıcı imza için Space ayarlarında şu secret'ları tanımla:

Secret	Değer
RIASLINK_KEYSTORE_B64	.jks/.keystore dosyasının base64 hali (base64 -w0 release.jks)
RIASLINK_KEYSTORE_PASSWORD	keystore şifresi
RIASLINK_KEY_ALIAS	anahtar alias'ı
RIASLINK_KEY_PASSWORD	anahtar şifresi (boşsa keystore şifresi kullanılır)

Sınırlamalar

• release build'i imzasızdır (unsigned) — kendi keystore'unla imzalamadan cihaza kurulamaz. Test için debug seçeneğini kullan.
• Build süresi, oyunun asset boyutuna ve Space'in donanımına bağlı olarak birkaç dakika sürebilir.
• Bu Space'in Docker imajı derleme sırasında Android SDK ve Gradle indirdiğinden, ilk build (soğuk başlatma) internet erişimi gerektirir; Hugging Face'in Space build ortamı bunu otomatik sağlar.
• Build durumu bellekte tutulur; Space yeniden başlarsa devam eden build'ler kaybolur (yeniden başlatmak gerekir).

Yerel geliştirme

docker build -t riaslink-port-builder .
docker run -p 7860:7860 riaslink-port-builder

Ya da Docker olmadan, sadece Python tarafını test etmek için:

pip install -r requirements.txt
python3 app.py
# http://localhost:7860

(android-template/ build'i için yine de Android SDK + Gradle gerekir — bu yol sadece formu/arayüzü test etmek içindir.)

Android projesini Space dışında (örn. Android Studio'da) elle de açabilirsin — bkz. android-template/README.md.