Özel uygulamalar

Özel uygulamalara genel bakış

Özel uygulama nedir, nasıl kaydedilir ve FX Phone hangi tanım alanlarını okur.

#Özel uygulama nedir

Özel uygulama, kendi resource'undaki bir web sayfasıdır; FX Phone onu telefonun içinde bir iframe'de gösterir. Kendi Ana Ekran simgesi ve kendi App Store sayfası olur. Sayfa telefonla postMessage üzerinden, senin resource'unla da normal NUI callback'leri üzerinden konuşur.

Eklemenin iki yolu var:

  • Resource'undan AddCustomApp client export'unu çağır. Olağan yol budur.
  • configs/config_apps.lua içindeki Config.CustomApps listesinde tanımla. Bu hiç Lua gerektirmez ve başka bir yerde barındırılan bir sayfaya uygundur.

Bu bölümdeki sayfalar:

Burada kullanılan Lua export'ları Client export'ları: özel uygulamalar sayfasında anlatılıyor.

#Uygulama kaydetme

Client tarafında AddCustomApp'i çağır. FX Phone, lb-phone ve cylex_phone tanım biçimlerini kabul eder.

lb-phone biçimi:

luaexports['fx-phone']:AddCustomApp({
    identifier = 'garage',
    name = 'Garage',
    description = 'Your vehicles, wherever you are.',
    developer = 'My Server',
    defaultApp = true,
    size = 24000,
    price = 0,
    category = 'utilities',
    jobs = nil,
    images = { 'my-garage/html/shots/1.webp', 'my-garage/html/shots/2.webp' },
    ui = 'my-garage/html/index.html',
    icon = 'my-garage/html/icon.png',
})

cylex_phone biçimi:

luaexports['fx-phone']:AddCustomApp({
    appId = 'garage',
    label = 'Garage',
    ui = 'https://cfx-nui-my-garage/html/index.html',
    icon = 'https://cfx-nui-my-garage/html/icon.png',
    defaultInstalled = true,
})

AddCustomApp, true ya da false ile birlikte bir hata kodu döndürür:

Hata Anlamı
invalid tanım bir tablo değil
invalid_id id eksik, 40 karakterden uzun ya da harf, rakam, _ ve - dışında karakter içeriyor
invalid_ui ui eksik ya da bir adrese çözümlenemiyor
reserved_id id, telefonun kendi uygulamalarından birine ait

#Tanım alanları

Alan Şu adla da okunur Anlamı
identifier appId, id Harf, rakam, _ ve -, en fazla 40 karakter. Bir çekirdek uygulamanın id'si olmamalı
name label Simgenin altındaki ad, en fazla 40 karakter. Varsayılan olarak id
ui Sayfa. Zorunlu. Aşağıdaki yol kurallarına bak
icon Simge görseli, ui ile aynı yol kuralları
description App Store metni, en fazla 500 karakter
developer App Store geliştirici satırı, en fazla 60 karakter. Varsayılan olarak resource adı
defaultApp defaultInstalled Her telefonda kurulu gelir. Aksi hâlde oyuncular onu App Store'dan kurar
category App Store kategorisi. Varsayılan other
images App Store ekran görüntüleri, ui ile aynı yol kuralları
size App Store boyut satırı, KB cinsinden
price App Store fiyatı, ilk kurulumda bankadan alınır. Yeniden kurmak ücretsizdir. Üst sınırı Config.Limits.AppPriceMax
jobs Meslek adları listesi. Uygulamayı yalnızca bu meslekler görür
keepOpen Uygulama kapatıldıktan ya da uygulama değiştiriciden çıktıktan sonra sayfa, uygulama kaldırılana kadar yüklü kalır. Kaldırılmak yerine visibility mesajları alır
landscape Uygulama yatay görünümü destekler. Oyuncu telefonu Denetim Merkezi'nden döndürdüğünde ya da bir script SetLandscape(true) çağırdığında yan döner
fixBlur lb-phone uyumluluğu için kabul edilir. Etkisi yok

#ui, icon ve images için yollar

Yazdığın FX Phone'un yüklediği
https://example.com/app/ yazıldığı gibi
nui://my-garage/html/index.html https://cfx-nui-my-garage/html/index.html
my-garage/html/index.html https://cfx-nui-my-garage/html/index.html
index.html (eğik çizgi yok) https://cfx-nui-<calling resource>/index.html

Eğik çizgiden önceki ilk kısım her zaman resource adı olarak okunur. html/index.html değil, my-garage/html/index.html yaz.

Koddan gelen diğer kurallar:

  • Bir yol en fazla 512 karakterdir ve boşluk, tırnak, açılı ayraç, ters eğik çizgi ya da ters tırnak içermemelidir.
  • Son ui adresi https:// olmalıdır. Resource sayfaları https://cfx-nui-<resource>/ olarak zaten böyledir. Başka her şey boş bir sayfa olarak açılır.
  • Resource'undan sunulan dosyalar, resource'un fxmanifest.lua dosyasında files { } altında listelenmelidir.

#Ne zaman kaydetmeli

Kayıt, FX Phone'un client durumunda tutulur. Resource'un başladığında kaydet, telefon her yüklendiğinde de yeniden kaydet. İkinci çağrı bir FX Phone yeniden başlatmasını da karşılar.

lualocal function register()
    exports['fx-phone']:AddCustomApp({ ... })
end

AddEventHandler('fx-phone:client:phoneLoaded', register)

CreateThread(function()
    if GetResourceState('fx-phone') == 'started' then register() end
end)
  • AddCustomApp'i aynı id ile yeniden çağırmak uygulamayı günceller.
  • Resource'un durduğunda uygulamaları kaldırılır.
  • RemoveCustomApp(id) bir uygulamayı elle kaldırır. Bilinmeyen bir id için false, 'not_found' döndürür.

#Açıldı ve kapandı event'leri

Bir özel uygulama öne geldiğinde ya da önden çekildiğinde FX Phone uygulama id'siyle iki client event'i tetikler:

luaAddEventHandler('fx-phone:customApp:opened', function(appId) end)
AddEventHandler('fx-phone:customApp:closed', function(appId) end)

Aynı event'ler cylex_phone:customApp:opened ve cylex_phone:customApp:closed olarak da tetiklenir.

#Config.CustomApps

Lua gerektirmeyen uygulamalar aynı alanlarla configs/config_apps.lua içinde tanımlanabilir:

luaConfig.CustomApps = {
    {
        identifier = 'wiki',
        name = 'City Wiki',
        description = 'Rules, laws and maps.',
        ui = 'https://wiki.example.com/phone',
        icon = 'https://wiki.example.com/icon.png',
        defaultApp = true,
        category = 'utilities',
    },
    {
        identifier = 'menu',
        name = 'Burger Shot',
        ui = 'my-menu/html/index.html',
        icon = 'my-menu/html/icon.png',
        jobs = { 'burgershot' },
        resource = 'my-menu',
    },
}

Bu uygulamalar, AddCustomApp ile eklenen uygulamalarla aynı kayıt defterinden geçer:

  • fx-phone:customApp:opened ve closed client event'leri onlar için de tetiklenir.
  • SendCustomAppMessage(identifier, data) herhangi bir resource'tan onların sayfasına ulaşır.
  • Sayfanın nuiCallback mesajları, yalnızca girdi kendi resource'unu resource = 'my-menu' ile belirtiyorsa <resource>:phoneApp:event olarak iletilir. Bu yoksa iletilecek bir resource yoktur ve sayfanın çağrısı not_found ile yanıtlanır.
  • Başka bir resource durduğunda hiçbir şey onları kaldırmaz.
  • id ya da ui değeri hatalı olan bir girdi atlanır. Neden, debug çıktısı açıksa yazdırılır.
  • Buradaki price yazıldığı gibi alınır. AppPriceMax uygulanmaz.
  • Yönetim tableti bu uygulamaları çekirdek uygulamalar gibi kapatabilir.

Sayfadan kendi resource'unun NUI callback'lerine fetch atmak iki durumda da çalışır.

#lb-phone ya da cylex_phone için yazılmış uygulamalar

lb-phone ya da cylex_phone için yazılmış bir uygulama, genellikle Lua kodunda exports['lb-phone'] ya da exports['cylex_phone'] ifadesini exports['fx-phone'] ile değiştirdikten sonra çalışır. İki tanım biçimi, iframe mesajları ve lb-phone'un componentsLoaded sinyali anlaşılır.

Uygulama düzenlenemiyorsa FX Phone, diğer telefonun adıyla yanıt veren katman resource'larıyla gelir. Bkz. lb-phone uyumluluğu ve cylex_phone uyumluluğu.