Agency-ProgressBar: Her Script'i Sessizce Üst Seviyeye Taşıyan Arayüz Detayı

Küçük Bir Script, Muazzam Bir Etki

İlerleme çubukları FiveM içinde her yerde karşımıza çıkar: kilit açma, tamir etme, kara para aklama, madencilik, ilk yardım. Varsayılan uygulamalar işlevsel olsa da tekdüzedir. Agency-ProgressBar, biri ayrıntılara gerçekten önem verdiğinde bu aracın nasıl hissettirmesi gerektiğine dair bizim yorumumuzdur.

İyi Bir İlerleme Çubuğunun Anatomisi

İyi bir ilerleme çubuğu aynı anda dört şeyi iletir: Hangi işlemin gerçekleştiği, ne kadar ilerlediğiniz, ne kadar süre kaldığı ve iptal edip edemeyeceğiniz. Çoğu uygulama yalnızca ilk ikisini sunar. Agency-ProgressBar, ilerlemenin takılarak değil akıcı hissedilmesini sağlayan zarif animasyonlarla dördünü birden gösterir.

İşe Yarayan İptal Mekanizması

Oyuncunun başlattığı iptal işlemi, çubuğun opaklığını 300 ms içinde sıfıra döndüren kısa bir kararma animasyonunu tetikler. Göze batan ani kaybolmalar olmaz. Geliştiriciler, oyuncular bir eylemi tamamlamadan yarıda bıraktığında script'lerin düzgün şekilde temizlenmesi için bir iptal callback'i kaydedebilir.

Bağlamsal Konumlandırma

Çubuk ekrandaki ilgili ögenin yanında belirir: Kendinize yönelik eylemlerde başınızın üzerinde, etkileşimli eylemlerde ise hedef NPC'nin üzerinde. Yukarıda bir şeyler olurken ekranın altından eylem durumunu okumaya son. Bu bağlamsal konumlandırma, oyuncuların tam adını koyamasalar da hissettikleri ince bir UX geliştirmesidir.

Export Kalıbı

Tüm yardımcı scriptlerimiz gibi, Agency-ProgressBar da basit bir exports API'si sunar: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). Dakikalar içinde herhangi bir script'e ekleyin. Özel bir yapılandırmaya gerek kalmadan Agency-Notify, Agency-Hud ve ekosistemimizin geri kalanıyla sorunsuz şekilde çalışır.

Kurulum & Yapılandırma

Agency-ProgressBar, sıfır veritabanı bağımlılığına sahip, doğrudan kullanıma hazır bir yardımcı araçtır. Tebex'ten indirin, klasörü resources dizininize bırakın, ekleyin ensure agency-progressbar kime server.cfg. Bu kadar. Resource hemen çalışmaya başlar ve bir sonraki yeniden başlatmada herhangi bir script exports API'sini çağırabilir.

Mevcut bir ilerleme çubuğunu değiştiriyorsanız (ox_lib progressBar, qb-progressbar vb.), export çağrısı adı üzerinde yapılacak bir bul ve değiştir işlemi çoğu geçişi dakikalar içinde halleder. Parametre yapısı bilinçli olarak yaygın topluluk kalıplarına yakın tutulmuştur.

Yapılandırma Seçenekleri

Aç config.lua varsayılanları ayarlamak için:

• Varsayılan konum, oyuncu başının üzerinde (varsayılan) veya sabit alt ortada.
• Renk şeması, dolgu rengi gradyanı. Tek renk, iki duraklı gradyan veya önem derecesine göre eşlenmiş (normal için yeşil, yavaş için turuncu, kritik için kırmızı) renkleri destekler.
• İptal tuşu, iptal edilebilir bir ilerleme çubuğunu hangi tuşun iptal edeceği. Varsayılan: backspace.
• İptal animasyonu, solma (varsayılan), kayma veya anında kaybolma.
• Zaman göstergesi, kalan saniyeyi (varsayılan), yüzdeyi veya hiçbirini gösterme.
• Minimum süre, bu eşikten daha kısa eylemler çubuğu tamamen atlar. Varsayılan: 500ms.

Framework Uyumluluğu

Agency-ProgressBar, hiçbir framework bağımlılığı olmaksızın tamamen standalone çalışır. QBCore, ESX ve özel sunucu kurulumlarında birebir aynı şekilde işlev görür. Exports API'si yegane entegrasyon yüzeyidir, paylaşılan global değişkenler, framework event'leri ve yetki kontrolleri yoktur. Kurun ve kaynağından bağımsız olarak herhangi bir script'ten çağırın.

Roleplay İçin Bu Neden Önemli

İlerleme çubukları; maymuncukla kilit açma, kelepçeleme, üretim, iyileştirme, kanıt toplama, bilgisayar korsanlığı gibi onlarca oynanış anında görünen bir UX temelidir. Bu çubuklar farklı scriptler arasında uyumsuz göründüğünde veya tutarsız davrandığında, sunucu bütünlüğünü bozan hafif bir görsel karmaşa yaratır.

Sunucunuzdaki her işlem çubuğu Agency-ProgressBar kullandığında, görsel dil birleşir. Oyuncular çubuğun ne anlama geldiği ve nasıl davrandığı konusunda sezgisel bir anlayış geliştirir. İptal davranışı tutarlıdır. Tipografi, kullanıcı arayüzünüzün geri kalanıyla eşleşir. Bunlar küçük şeylerdir, ancak bir araya gelerek belirgin şekilde daha kusursuz bir oyuncu deneyimi oluşturur.

Bağlamsal konumlandırma göründüğünden daha önemlidir. Maymuncuk kullanırken karakterinizin kafasına sabitlenen bir ilerleme çubuğu, ekranın bir köşesine değil aksiyona odaklanmanızı sağlar. Gergin anlarda, örneğin kilit açarken kovalanırken, çubuk görünür durumdayken oyuncuların mekânsal olarak tetikte kalmasını sağlar.

Sıkça Sorulan Sorular

Aynı anda birden fazla progress bar çalıştırabilir miyim?

Evet. Her Play() çağrısı bir ID döndürür ve kendi durumunu yönetir. Çoğu RP senaryosu aynı anda tek bir çubuk kullansa da, paralel görevlerdeki ilerlemenin aynı anda görünür olması gereken çok adımlı eylemler için birden fazla çubuk oyuncunun üzerinde uygun aralıklarla dikey olarak sıralanır.

Bir progress bar'ı oyuncu yerine bir prop'a veya NPC'ye nasıl bağlayabilirim?

Bir ... iletin target = {type = 'entity', id = entityNetId} options tablosundaki alan. Çubuk, oyuncu yerine belirtilen entity'nin üzerinde durur. Bunu tamir eylemleri, baygın oyuncular üzerindeki tıbbi müdahaleler veya eylemin odağının harici olduğu her durum için kullanın.

Bar sunucu tarafından zorunlu olarak iptal edilemez yapılabilir mi?

Evet. Şunu ayarlayın: canCancel = false Play() çağrıldığında. İptal tuşunun herhangi bir etkisi olmaz ve hiçbir iptal animasyonu oynatılmaz. Bu durum, oyuncunun müdahalesinin akışı bozabileceği sunucu tarafından zorunlu kılınan eylemler (tutuklama animasyonları, senaryolu ara sahneler) için uygundur.

Bu ox_lib animasyonları ile çalışır mı?

Evet. Agency-ProgressBar animasyondan bağımsızdır, animasyonları ilerleme çubuğu çağrısıyla birlikte kendi scriptinizde yönetirsiniz. Çubuk tamamen bir UI ögesidir. Herhangi bir animasyon kütüphanesiyle veya bağımsız ham FiveM animasyon çağrılarıyla eşleştirebilirsiniz.

Gereksinimler

• FiveM sunucusu (herhangi bir framework veya standalone)
• geçerli Agency-ProgressBar lisansına sahip cfx.re hesabı
• Veritabanı bağımlılığı yok
• Harici resource bağımlılığı yok

Pratik Entegrasyon Örnekleri

Agency-ProgressBar ürününü mevcut script'lerle entegre etmek için yaygın kalıplar şunlardır:

Maymuncukla kilit açma: Ara Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) maymuncukla kilit açma girişiminin başlangıcında. Paralel çalışan maymuncuk mini oyunu ile eşleştirin. Mini oyun başarısız olursa, döndürülen kimlik (ID) ile Dismiss() çağrısını yapın. Başarılı olursa, çubuğun doğal şekilde tamamlanmasına izin verin.

Tıbbi tedavi: Kullanın target = {type = 'entity', id = patientNetId} çubuğu sağlık görevlisi yerine hastanın üzerine sabitlemek için. Olayı izleyen oyuncular, ilerlemenin sağlık görevlisinin kafasının üzerinde yüzdüğünü değil, tedavinin yapıldığı noktada gerçekleştiğini görür.

Kanıt toplama: Ayarla canCancel = false kesintiye uğramaması gereken senaryolu kanıt toplama işlemleri için (oyuncuların olay yerinde parmak izi bırakmaktan kaçınmak amacıyla işlemi iptal etmelerini önlemek için). İptal edilemeyen çubuk, oyuncuya bu eylemin isteğe bağlı değil, zorunlu olduğunu bildirir.

Sunucu taraflı eylemler: Sunucu tarafındaki bir eylem eşzamansız olarak çalışırken istemcide bir ilerleme çubuğu tetikleyin. Sunucu geri çağırması döndüğünde, sunucu tarafındaki sonuca bağlı olarak çubuğun tamamlanmasına izin verin veya erken kapatın. Görsel süre, beklenen sunucu işlem süresiyle yaklaşık olarak eşleşmelidir.