GrandMA3 Lua Plugin API'sine Giriş: Temel Kavramlar
GrandMA3 üzerinde Lua diliyle plugin geliştirmeye başlamak için ihtiyacınız olan temel API kavramları ve ilk adımlar.
GrandMA3 Lua Plugin API Nedir?
GrandMA3, sahne aydınlatma kontrol yazılımının en güçlü özelliklerinden biri, yerleşik Lua scripting motoru üzerinden plugin geliştirmeye olanak tanımasıdır. Bu sistem sayesinde tekrarlayan görevleri otomatikleştirebilir, özel kullanıcı arayüzleri oluşturabilir ve konsolun standart fonksiyonlarını genişletebilirsiniz.
Lua, hafif yapısı ve kolay öğrenme eğrisiyle sahne aydınlatma dünyasında tercih edilen bir scripting dilidir. GrandMA3'ün sunduğu API katmanı, bu dili doğrudan show dosyası ve donanımla konuşturan köprü görevini üstlenir.
Plugin Yapısının Temelleri
Her GrandMA3 plugin'i, yazılım tarafından tanınan belirli bir yapıya sahip olmak zorundadır. En temel plugin iskeleti şu üç fonksiyonu içerir:
- Main() – Plugin çalıştırıldığında ilk tetiklenen fonksiyon
- Cleanup() – Plugin sonlandırıldığında çağrılan temizlik fonksiyonu (opsiyonel)
- Version() – Plugin sürüm bilgisini döndürür (opsiyonel ama önerilir)
Minimal bir plugin örneği şöyle görünür:
local function Main(display_handle, argument) Printf("Merhaba MA3!") return false end return Main, "1.0", "Merhaba Dünya Plugin"Temel API Fonksiyonları
Printf ve Echo
Printf() fonksiyonu, sistem komut satırına çıktı göndermenin en yaygın yoludur. Hata ayıklama süreçlerinde vazgeçilmezdir. EchoReturn() ise kullanıcıya görsel geri bildirim sağlar.
Nesnelere Erişim
GrandMA3 API'sinin kalbi, show dosyasındaki nesnelere programatik erişimdir. GetObjectHandle() ve GetHandle() fonksiyonları belirli bir objenin referansını almanızı sağlar:
local seq_handle = GetObjectHandle("Sequence", "Cue List 1")Bir handle aldıktan sonra o objenin property'lerine okuma ve yazma işlemleri yapabilirsiniz.
Komut Çalıştırma
Lua plugin içinden GrandMA3 komut satırı komutları göndermek için Cmd() fonksiyonu kullanılır:
Cmd("Go+ Executor 201")Önemli Not: Cmd() fonksiyonu asenkron çalışır. Arka arkaya komut gönderirken aralarına coroutine.yield() eklemezseniz beklenmedik davranışlarla karşılaşabilirsiniz.Coroutine Kullanımı
GrandMA3 plugin sistemi, Lua'nın coroutine mekanizmasını yoğun biçimde kullanır. Uzun süren işlemleri yazılımı dondurmadan yürütmek için Main fonksiyonunuzu bir coroutine olarak yapılandırmanız önerilir:
- Plugin döngüsünün bloke olmaması için
coroutine.yield()noktaları belirleyin - Zamanlayıcı tabanlı işlemler için
coroutine.yield(saniye)sözdizimini kullanın - Sonsuz döngülerde mutlaka yield çağrısı yapın, aksi halde konsol yanıt vermez hale gelir
Plugin Nereye Kaydedilir?
Geliştirdiğiniz plugin dosyaları .lua uzantısıyla GrandMA3 show dosyasının içindeki Plugin klasörüne yerleştirilir. Yazılım içinden Menu > Plugins yolunu izleyerek mevcut plugin'leri yönetebilir, yeni dosyalar ekleyebilirsiniz.
İpucu: Geliştirme sürecinde plugin dosyalarını harici bir metin editöründe (VS Code + Lua eklentisi önerilir) düzenleyip GrandMA3'e import etmek, iş akışınızı önemli ölçüde hızlandırır.
API belgelerine erişmek için GrandMA3 yazılımının kurulum dizinindeki gma3_library klasörünü ve MA Lighting'in resmi geliştirici portalını takip etmeniz, güncel fonksiyon listesine ulaşmanın en güvenilir yoludur.