diff --git a/docs/pl/faq/faq.md b/docs/pl/faq/faq.md new file mode 100644 index 00000000..401a6366 --- /dev/null +++ b/docs/pl/faq/faq.md @@ -0,0 +1,313 @@ +--- +title: FAQ o silniku i edytorze Defold +brief: Najczęściej zadawane pytania o silnik gry Defold, edytor i platformę. +--- + +# Najczęściej zadawane pytania + +## Pytania ogólne + +#### P: Czy Defold naprawdę jest darmowy? + +A: Tak, silnik Defold i edytor z pełną funkcjonalnością są całkowicie bezpłatne. Bez ukrytych kosztów, opłat ani tantiem. Po prostu za darmo. + + +#### P: Dlaczego na świecie Defold Foundation oddaje Defold za darmo? + +A: Jednym z celów [Defold Foundation](/foundation) jest zapewnienie, że oprogramowanie Defold będzie dostępne dla deweloperów na całym świecie, a kod źródłowy będzie dostępny bezpłatnie. + + +#### P: Jak długo będziecie wspierać Defold? + +A: Jesteśmy mocno zaangażowani w Defold. [Defold Foundation](/foundation) została powołana tak, by przez wiele kolejnych lat pozostać odpowiedzialnym właścicielem Defold. To się nie skończy. + + +#### P: Czy mogę zaufać Defold w profesjonalnym tworzeniu gier? + +A: Zdecydowanie. Defold jest używany przez coraz większą liczbę profesjonalnych twórców gier i studiów. Zobacz [galerię gier](/showcase), aby znaleźć przykłady gier stworzonych w Defold. + + +#### P: Jakiego rodzaju śledzenie użytkowników prowadzicie? + +A: Rejestrujemy anonimowe dane użycia z naszych stron internetowych i edytora Defold, aby ulepszać nasze usługi i produkt. W grach, które tworzysz, nie ma śledzenia użytkowników, chyba że sam dodasz usługę analityczną. Więcej informacji znajdziesz w naszej [Polityce prywatności](/privacy-policy). + + +#### P: Kto stworzył Defold? + +A: Defold został stworzony przez Ragnara Svenssona i Christiana Murraya. Zaczęli pracować nad silnikiem, edytorem i serwerami w 2009 roku. W 2013 roku King i Defold rozpoczęły współpracę, a w 2014 roku King przejął Defold. Przeczytaj pełną historię [tutaj](/about). + + +## Pytania o tworzenie gier + +#### P: Czy mogę tworzyć gry 3D w Defold? + +A: Oczywiście! Silnik jest pełnoprawnym silnikiem 3D. Zestaw narzędzi jest jednak przygotowany głównie pod 2D, więc wiele rzeczy trzeba będzie zrobić samodzielnie. Lepsze wsparcie 3D jest planowane. + + +## Pytania o język programowania + +#### P: W jakim języku programowania pracuje się w Defold? + +A: Logika gry w projekcie Defold jest przede wszystkim pisana w języku Lua, konkretnie Lua 5.1/LuaJIT. Szczegóły znajdziesz w [podręczniku Lua](/manuals/lua). Lua to lekki, dynamiczny język, który jest szybki i bardzo wydajny. Od wersji 1.8.1 Defold obsługuje użycie transpilerów generujących kod Lua. Po zainstalowaniu rozszerzenia do transpilacji możesz używać alternatywnych języków, takich jak [Teal](https://github.com/defold/extension-teal), do pisania statycznie sprawdzanego Lua. Możesz też używać kodu natywnego (C/C++, Objective-C, Java i JavaScript w zależności od platformy), aby [rozszerzać silnik Defold o nową funkcjonalność](/manuals/extensions/). Przy tworzeniu [własnych materiałów](/manuals/material/) używany jest język shaderów OpenGL ES SL do pisania shaderów wierzchołków i fragmentów. + + +#### P: Czy mogę używać C++ do pisania logiki gry? + +A: Obsługa C++ w Defold służy głównie do pisania rozszerzeń natywnych, które integrują się z SDK innych firm lub platformowymi API. [dmSDK](https://defold.com/ref/stable/dmGameObject/) (API C++ dla Defold używane w rozszerzeniach natywnych) będzie stopniowo rozbudowywane o kolejne funkcje, tak aby w przyszłości dało się pisać całą logikę gry w C++, jeśli deweloper będzie tego chciał. Lua pozostanie głównym językiem do logiki gry, ale dzięki rozbudowanemu API C++ będzie można pisać logikę gry także w C++. Prace nad rozbudową API C++ polegają głównie na przenoszeniu istniejących prywatnych plików nagłówkowych do sekcji publicznej i porządkowaniu API do publicznego użytku. + + +#### P: Czy mogę używać TypeScript z Defold? + +A: TypeScript nie jest oficjalnie obsługiwany. Społeczność utrzymuje zestaw narzędzi [ts-defold](https://ts-defold.dev/) do pisania w TypeScript i transpilowania go do Lua bezpośrednio z VSCode. + + +#### P: Czy mogę używać Haxe z Defold? + +A: Haxe nie jest oficjalnie obsługiwany. Społeczność utrzymuje [hxdefold](https://github.com/hxdefold/hxdefold) do pisania w Haxe i transpilowania go do Lua. + + +#### P: Czy mogę używać C# z Defold? + +A: Defold Foundation doda obsługę C# i udostępni ją jako zależność biblioteczną. C# to szeroko stosowany język programowania i pomoże studiom oraz deweloperom mocno zainwestowanym w C# przejść na Defold. + + +#### P: Obawiam się, że dodanie obsługi C# negatywnie wpłynie na Defold. Czy powinienem się martwić? + +A: Defold NIE odchodzi od Lua jako głównego języka skryptowego. Obsługa C# zostanie dodana jako nowy język dla rozszerzeń. Nie wpłynie na silnik, chyba że zdecydujesz się używać rozszerzeń C# w swoim projekcie. + +Obsługa C# będzie miała swoją cenę, na przykład większy rozmiar pliku wykonywalnego czy wpływ na wydajność w czasie działania, ale to już decyzja konkretnego dewelopera lub studia. + +Samo C# to stosunkowo niewielka zmiana, ponieważ system rozszerzeń już obsługuje wiele języków (C/C++, Java, Objective-C, Zig). Generowane wiązania C# pozwolą utrzymać SDK w synchronizacji. Dzięki temu te wiązania pozostaną aktualne przy minimalnym nakładzie pracy. + +Defold Foundation wcześniej była przeciwna dodaniu obsługi C# w Defold, ale zmieniła zdanie z kilku powodów: + +* Studia i deweloperzy nadal proszą o obsługę C#. +* Obsługa C# została ograniczona wyłącznie do rozszerzeń, więc wymaga niewielkiego nakładu pracy. +* Główny silnik nie ulegnie zmianie. +* API C# można utrzymywać w synchronizacji przy minimalnym nakładzie pracy, jeśli jest generowane. +* Obsługa C# będzie oparta na DotNet 9 z NativeAOT, co wygeneruje biblioteki statyczne, do których istniejący potok budowania może linkować, tak jak do każdego innego rozszerzenia Defold. + + +## Pytania o platformy + +#### P: Na jakich platformach działa Defold? + +A: Następujące platformy są obsługiwane przez edytor i narzędzia oraz przez środowisko uruchomieniowe silnika: + + | System | Wersja | Architektury | Obsługiwane | + | ------------------ | ------------------ | ------------------ | ------------------ | + | macOS | 11 Big Sur | `x86-64`, `arm-64` | Edytor i silnik | + | Windows | Vista | `x86-32`, `x86-64` | Edytor i silnik | + | Ubuntu (1) | 22.04 LTS | `x86-64` | Edytor | + | Linux (2) | Dowolna | `x86-64`, `arm-64` | Silnik | + | iOS | 15.0 | `arm-64` `x86_64` | Silnik | + | Android | 5.0 (API level 21) | `arm-32`, `arm-64` | Silnik | + | HTML5 | | `asm.js`, `wasm` | Silnik | + + (1 Edytor jest budowany i testowany dla 64-bitowego Ubuntu. Powinien też działać na innych dystrybucjach, ale nie dajemy żadnych gwarancji.) + + (2 Środowisko uruchomieniowe silnika powinno działać na większości 64-bitowych dystrybucji Linuksa, o ile sterowniki graficzne są aktualne. Więcej informacji znajdziesz poniżej, w sekcji o API graficznych.) + + +#### P: Na jakie platformy docelowe mogę tworzyć gry z Defold? + +A: Jednym kliknięciem możesz publikować na PS4™, PS5™, Nintendo Switch, iOS (64-bit), Android (32-bit i 64-bit) oraz HTML5, a także na macOS (x86-64 i arm64), Windows (32-bit i 64-bit) i Linux (x86-64 i arm64). To naprawdę jedna baza kodu i wiele obsługiwanych platform. + + +#### P: Jakiego API renderowania używa Defold? + +A: Jako deweloper pracujesz tylko z jednym API renderowania, korzystając z [w pełni skryptowalnego potoku renderowania](/manuals/render/). Skrypt renderowania Defold tłumaczy operacje renderowania na następujące API graficzne: + +:[API graficzne](../shared/graphics-api.md) + +#### P: Czy mogę sprawdzić, jaką wersję uruchamiam? + +A: Tak, wybierz opcję About w menu Help. Okno wyraźnie pokazuje wersję beta Defold i, co ważniejsze, konkretny SHA1 wydania. Aby odczytać wersję środowiska uruchomieniowego, użyj [`sys.get_engine_info()`](/ref/sys/#sys.get_engine_info). + +Najnowszą wersję beta dostępną do pobrania z http://d.defold.com/beta można sprawdzić, otwierając http://d.defold.com/beta/info.json. Ten sam plik istnieje także dla wersji stabilnych: http://d.defold.com/stable/info.json + + +#### P: Czy da się sprawdzić, na jakiej platformie działa gra w czasie uruchomienia? + +A: Tak, zobacz [`sys.get_sys_info()`](/ref/sys#sys.get_sys_info). + + +## Pytania o edytor +:[FAQ edytora](../shared/editor-faq.md) + + +## Pytania o Linuksa +:[FAQ Linuksa](../shared/linux-faq.md) + + +## Pytania o Androida +:[FAQ Androida](../shared/android-faq.md) + + +## Pytania o HTML5 +:[FAQ HTML5](../shared/html5-faq.md) + + +## Pytania o iOS +:[FAQ iOS](../shared/ios-faq.md) + + +## Pytania o Windows +:[FAQ Windows](../shared/windows-faq.md) + + +## Pytania o konsole +:[FAQ konsol](../shared/consoles-faq.md) + + +## Publikowanie gier + +#### P: Próbuję opublikować moją grę w App Store. Jak powinienem odpowiedzieć na IDFA? + +A: Podczas przesyłania aplikacji Apple pokazuje trzy pola wyboru dla trzech poprawnych przypadków użycia IDFA: + + 1. Wyświetlanie reklam w aplikacji + 2. Atrybucja instalacji na podstawie reklam + 3. Atrybucja działań użytkownika na podstawie reklam + + Jeśli zaznaczysz opcję 1, recenzent aplikacji będzie szukał reklam w aplikacji. Jeśli twoja gra nie wyświetla reklam, może zostać odrzucona. Sam Defold nie używa identyfikatora reklamowego. + + +#### P: Jak mogę monetyzować swoją grę? + +A: Defold obsługuje zakupy w aplikacji oraz różne rozwiązania reklamowe. Sprawdź kategorię [Monetization](https://defold.com/tags/stars/monetization/) w Asset Portal, aby zobaczyć aktualną listę dostępnych opcji monetyzacji. + + +## Błędy w Defold + +#### P: Nie mogę uruchomić gry i nie ma błędu budowania. Co jest nie tak? + +A: Proces budowania może w rzadkich przypadkach nie przebudować plików, jeśli wcześniej wystąpiły błędy budowania, które już naprawiłeś. Wymuś pełną przebudowę, wybierając Project ▸ Rebuild And Launch z menu. + + + +## Zawartość gry + +#### P: Czy Defold obsługuje prefaby? + +A: Tak. Nazywają się [kolekcje](/manuals/building-blocks/#collections). Pozwalają tworzyć złożone hierarchie obiektów gry i przechowywać je jako oddzielne elementy składowe, które można instancjonować w edytorze lub w czasie działania programu, przez tworzenie instancji kolekcji. Dla węzłów GUI dostępne są szablony GUI. + + +#### P: Dlaczego nie mogę dodać obiektu gry jako dziecka innego obiektu gry? + +A: Najprawdopodobniej próbujesz dodać obiekt podrzędny w pliku obiektu gry, a to nie jest możliwe. Żeby zrozumieć dlaczego, trzeba pamiętać, że hierarchie rodzic-dziecko są wyłącznie hierarchią transformacji grafu sceny. Obiekt gry, który nie został umieszczony (lub utworzony dynamicznie) w scenie (kolekcji), nie należy do grafu sceny, więc nie może być częścią takiej hierarchii. + + +#### P: Dlaczego nie mogę rozsyłać wiadomości do wszystkich dzieci obiektu gry? + +A: Relacje rodzic-dziecko wyrażają wyłącznie relacje transformacji w grafie sceny i nie należy ich mylić z agregatami obiektów w programowaniu obiektowym. Jeśli skupisz się na danych swojej gry i na tym, jak najlepiej je przekształcać, gdy gra zmienia stan, prawdopodobnie rzadziej będziesz musiał wysyłać wiadomości z danymi stanu do wielu obiektów jednocześnie. Tam, gdzie potrzebujesz hierarchii danych, można je łatwo tworzyć i obsługiwać w Lua. + + +#### P: Dlaczego widzę artefakty wizualne wokół krawędzi moich sprite'ów? + +A: To artefakt wizualny nazywany `edge bleeding`, w którym piksele z krawędzi sąsiednich obrazów w atlasie przenikają do obrazu przypisanego do sprite'a. Rozwiązaniem jest dodanie dodatkowych wierszy i kolumn identycznych pikseli na obrzeżach obrazów atlasu. Na szczęście można to zrobić automatycznie w edytorze atlasu w Defold. Otwórz atlas i ustaw wartość właściwości `Extrude Borders` na 1. + + +#### P: Czy mogę barwić sprite'y albo uczynić je przezroczystymi, czy muszę napisać do tego własny shader? + +A: Wbudowany shader sprite'a, używany domyślnie dla wszystkich sprite'ów, ma zdefiniowaną stałą `tint`: + + ```lua + local red = 1 + local green = 0.3 + local blue = 0.55 + local alpha = 1 + go.set("#sprite", "tint", vmath.vector4(red, green, blue, alpha)) + ``` + + +#### P: Jeśli ustawię współrzędną Z sprite'a na 100, to nie będzie renderowany. Dlaczego? + +A: Pozycja Z obiektu gry kontroluje kolejność renderowania. Niższe wartości są rysowane przed wyższymi. W domyślnym skrypcie do renderowania rysowane są obiekty gry o głębokości od -1 do 1, a wszystko poza tym zakresem nie zostanie narysowane. Więcej o skrypcie do renderowania przeczytasz w oficjalnej [dokumentacji renderowania](/manuals/render). W przypadku węzłów GUI wartość Z jest ignorowana i w ogóle nie wpływa na kolejność renderowania. Zamiast tego węzły są renderowane w kolejności, w jakiej widnieją na liście, oraz zgodnie z hierarchią węzłów podrzędnych i warstwami. Więcej o renderowaniu GUI i optymalizacji wywołań rysowania z użyciem warstw przeczytasz w oficjalnej [dokumentacji GUI](/manuals/gui). + + +#### P: Czy zmiana zakresu Z projekcji widoku na zakres od -100 do 100 wpłynęłaby na wydajność? + +A: Nie. Jedyny efekt dotyczy precyzji. Bufor Z jest logarytmiczny i ma bardzo wysoką rozdzielczość wartości Z blisko 0 oraz mniejszą rozdzielczość dalej od 0. Na przykład przy 24-bitowym buforze wartości 10.0 i 10.000005 można odróżnić, natomiast 10000 i 10005 już nie. + + +#### P: Dlaczego sposób reprezentacji kątów jest niespójny? + +A: W rzeczywistości istnieje spójność. Kąty są wszędzie w edytorze i w API gry wyrażane w stopniach. Biblioteki matematyczne używają radianów. Obecnie wyjątek stanowi właściwość fizyki `angular_velocity`, która jest wyrażana w radianach/s. To ma się zmienić. + + +#### P: Gdy tworzę węzeł GUI typu box z samym kolorem, bez tekstury, jak będzie renderowany? + +A: To po prostu kształt pokolorowany wierzchołkami. Trzeba jednak pamiętać, że nadal będzie to kosztować fill-rate. + + +#### P: Jeśli w locie zmienię zasoby, czy silnik automatycznie je zwolni? + +A: Wszystkie zasoby są wewnętrznie objęte zliczaniem referencji. Gdy tylko licznik referencji spadnie do zera, zasób zostaje zwolniony. + + +#### P: Czy można odtwarzać dźwięk bez używania komponentu dźwięku dołączonego do obiektu gry? + +A: W Defold wszystko jest oparte na komponentach. Można utworzyć pusty obiekt gry z wieloma dźwiękami i odtwarzać je, wysyłając wiadomości do obiektu sterującego dźwiękiem. + + +#### P: Czy można w czasie działania zmienić plik dźwiękowy powiązany z komponentem dźwięku? + +A: Zasadniczo wszystkie zasoby są deklarowane statycznie, dzięki czemu zarządzanie nimi dostajesz za darmo. Możesz użyć [właściwości zasobów](/manuals/script-properties/#resource-properties), aby zmienić zasób przypisany do komponentu. + + +#### P: Czy istnieje sposób na dostęp do właściwości kształtu kolizji w fizyce? + +A: Nie, obecnie nie jest to możliwe. + + +#### P: Czy istnieje jakiś szybki sposób na renderowanie obiektów kolizji w mojej scenie? (jak debug draw w Box2D) + +A: Tak, ustaw flagę *physics.debug* w *game.project*. (Zobacz oficjalną [dokumentację ustawień projektu](/manuals/project-settings/#debug)) + + +#### P: Jakie są koszty wydajnościowe wielu kontaktów i kolizji? + +A: Defold uruchamia w tle zmodyfikowaną wersję Box2D, więc koszt wydajnościowy powinien być bardzo podobny. Zawsze możesz sprawdzić, ile czasu silnik spędza na fizyce, otwierając [profiler](/manuals/debugging). Powinieneś też wziąć pod uwagę, jakiego rodzaju obiekty kolizji używasz. Na przykład obiekty statyczne są tańsze wydajnościowo. Zobacz oficjalną [dokumentację fizyki](/manuals/physics) w Defold, aby uzyskać więcej szczegółów. + + +#### P: Jaki jest wpływ na wydajność wielu komponentów efektów cząsteczkowych? + +A: To zależy od tego, czy są odtwarzane, czy nie. Nieodtwarzany ParticleFX nie ma kosztu wydajnościowego. Wpływ odtwarzanego ParticleFX trzeba ocenić za pomocą profilera, ponieważ zależy od jego konfiguracji. Jak w większości innych przypadków pamięć jest przydzielana z góry dla liczby komponentów ParticleFX zdefiniowanej jako max_count w *game.project*. + + +#### P: Jak mogę odbierać wejście w obiekcie gry wewnątrz kolekcji załadowanej przez pełnomocnika kolekcji? + +A: Każda kolekcja załadowana przez pełnomocnika kolekcji ma własny stos wejścia. Wejście jest kierowane ze stosu wejścia głównej kolekcji przez komponent pełnomocnika kolekcji do obiektów w kolekcji. Oznacza to, że nie wystarczy, aby obiekt gry w załadowanej kolekcji przejął skupienie wejścia. Obiekt gry, który _zawiera_ komponent pełnomocnika kolekcji, również musi przejąć skupienie wejścia. Zobacz [dokumentację wejścia](/manuals/input), aby uzyskać szczegóły. + + +#### P: Czy mogę używać właściwości skryptowych typu string? + +A: Nie. Defold obsługuje właściwości typu [hash](/ref/builtins#hash). Można ich używać do oznaczania typów, identyfikatorów stanu lub dowolnych kluczy. Hashe można też wykorzystywać do przechowywania identyfikatorów obiektów gry (ścieżek), choć często lepsze są właściwości [url](/ref/msg#msg.url), ponieważ edytor automatycznie wypełnia listę rozwijaną odpowiednimi adresami URL. Zobacz [dokumentację właściwości skryptowych](/manuals/script-properties), aby uzyskać szczegóły. + + +#### P: Jak uzyskać dostęp do poszczególnych komórek macierzy (utworzonej za pomocą [`vmath.matrix4()`](/ref/vmath/#vmath.matrix4:m1) lub podobnej)? + +A: Dostęp do komórek uzyskujesz przez `mymatrix.m11`, `mymatrix.m12`, `mymatrix.m21` itd. + + +#### P: Dostaję komunikat `Not enough resources to clone the node` podczas używania [gui.clone()](/ref/gui/#gui.clone:node) lub [gui.clone_tree()](/ref/gui/#gui.clone_tree:node) + +A: Zwiększ wartość `Max Nodes` komponentu GUI. Znajdziesz ją w panelu Properties, gdy zaznaczysz korzeń komponentu w Outline. + + +## Forum + +#### P: Czy mogę założyć wątek, w którym reklamuję swoją pracę? + +A: Oczywiście! Mamy do tego specjalną kategorię ["Work for hire"](https://forum.defold.com/c/work-for-hire). Zawsze wspieramy wszystko, co służy społeczności, a oferowanie swoich usług społeczności, za wynagrodzeniem lub bez, jest tego dobrym przykładem. + + +#### P: Założyłem wątek i dodałem swoją pracę. Czy mogę dodać więcej? + +A: Aby ograniczyć podbijanie wątków z kategorii "Work for hire", nie możesz pisać w swoim własnym wątku częściej niż raz na 14 dni, chyba że jest to bezpośrednia odpowiedź na komentarz w wątku, wtedy możesz odpowiedzieć. Jeśli chcesz dodać dodatkową pracę do wątku w ciągu 14 dni, musisz edytować istniejące posty i dopisać do nich nową treść. + + +#### P: Czy mogę użyć kategorii „Work for hire” do publikowania ofert pracy? + +A: Jasne, śmiało! Można jej używać zarówno do ofert, jak i do próśb o współpracę, na przykład: „Programista szuka grafika 2D specjalizującego się w pixel arcie. Mam pieniądze i dobrze zapłacę”. diff --git a/docs/pl/glossary.txt b/docs/pl/glossary.txt new file mode 100644 index 00000000..ed3fe6c9 --- /dev/null +++ b/docs/pl/glossary.txt @@ -0,0 +1,2122 @@ +--- +title: Zbiorczy słowniczek glosariuszy PL +brief: Jeden skonsolidowany plik łączący glosariusze z docs/pl/glossaries/manuals i docs/pl/glossaries/shared. +--- + +# Zbiorczy słowniczek glosariuszy PL + +Ten plik łączy zawartość rozbitych glosariuszy per artykuł i per sekcję `shared` w jeden skonsolidowany dokument. + +Terminy zapisane w instrukcji jako `(ang. ...)` warto na pierwszym użyciu podawać w formie `polski termin (ang. English)`; gdy chodzi o literalną nazwę elementu edytora, UI, API lub inną widoczną etykietę, angielska forma może pozostać bez tłumaczenia. + +Liczba scalonych plików: 86. + +## `manuals/2dgraphics.md` + +This glossary covers the most relevant terms from the 2D graphics manual and keeps literal Defold/API identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| 2D Graphics | grafika 2D | +| manual | instrukcja, czyli strona dokumentacji opisująca dany obszar | +| outdated | przestarzały | +| `This manual has been replaced by the Graphics overview manual` | ten materiał został zastąpiony przez instrukcję ogólną o grafice | +| `Graphics overview manual` | instrukcja ogólna o grafice; nazwa docelowej strony dokumentacji | +| `manuals/graphics` | ścieżka do strony dokumentacji o grafice | + +## `manuals/3dgraphics.md` + +This glossary covers the most relevant terms from the article and keeps literal Defold/documentation identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| 3D graphics | grafika 3D | +| 3D graphics manual | podręcznik dotyczący grafiki 3D | +| `Defold 3D graphics manual` | tytuł angielskiej strony; oznacza starszy materiał | +| `This manual is outdated` | informacja, że materiał jest przestarzały | +| `Graphics overview manual` | podręcznik przeglądowy dotyczący grafiki; docelowy materiał, do którego przekierowano | +| replaced | zastąpiony innym materiałem | + +## `manuals/adapting-graphics-to-screen-size.md` + +This glossary covers the most relevant terms from the article and keeps literal Defold/API identifiers in English. + + +| English term | Polish translation / explanation | +|---|---| +| screen size | wielkość ekranu | +| resolution | rozdzielczość | +| aspect ratio | proporcje obrazu; stosunek szerokości do wysokości | +| render script | skrypt do renderowania | +| `game.project` | plik konfiguracyjny projektu; zawiera ustawienia rozdzielczości, wyświetlania i grafiki | +| `use_fixed_projection` | wiadomość do `@render` ustawiająca stałą projekcję z określonym zoomem | +| `use_fixed_fit_projection` | wiadomość do `@render` dopasowująca projekcję do ekranu przy zachowaniu proporcji | +| `zoom` | powiększenie obrazu lub projekcji | +| `Fixed Projection` | stała projekcja; nazwa trybu używanego w render script | +| `nearest` | próbkowanie najbliższego sąsiedniego piksela, dobre dla grafiki pixel art | +| `linear` | liniowe próbkowanie tekstury, które może rozmywać obraz po skalowaniu | +| `Subpixels` | opcja ograniczająca renderowanie sprite'ów do pełnych pikseli | +| `High DPI` | tryb wysokiej gęstości pikseli na ekranach typu Retina | +| `GUI` | interfejs użytkownika; w Defoldzie system węzłów i layoutów | +| `pivot` | punkt centralny węzła GUI | +| `anchor` | zakotwiczenie określające, jak węzeł reaguje na zmianę rozmiaru ekranu | +| `adjust mode` | tryb dopasowania węzła do zmiany rozmiaru sceny lub rodzica | +| `Debug->Simulate Resolution` | polecenie menu debugowania do symulacji rozdzielczości; angielska forma może pozostać bez tłumaczenia, bo to literalna etykieta menu | +| `layout` | układ GUI dostosowany do orientacji i wielkości ekranu | + +## `manuals/addressing.md` + +Ten słowniczek obejmuje najważniejsze terminy użyte w artykule o adresowaniu w silniku Defold. + + +| English term | Polish translation / explanation | +| --- | --- | +| addressing | adresowanie | +| address | adres | +| identifier | identyfikator | +| game object | obiekt gry | +| game objects | obiekty gry; angielska forma może pozostać bez tłumaczenia jako nazwa pojęcia | +| component | komponent | +| collection | kolekcja | +| collections | kolekcje; angielska forma może pozostać bez tłumaczenia jako nazwa pojęcia | +| collection file | plik kolekcji | +| relative address | adres względny | +| absolute address | adres bezwzględny | +| naming context | kontekst nazewniczy | +| namespace | przestrzeń nazw | +| path | ścieżka | +| socket | socket, czyli identyfikator świata/instancji kolekcji | +| fragment | fragment URL, czyli identyfikator komponentu | +| URL | URL | +| disable | `disable`, nazwa wiadomości wyłączającej komponent; angielska forma może pozostać bez tłumaczenia | +| bean | `bean`, przykładowy identyfikator obiektu; angielska forma może pozostać bez tłumaczenia | +| body | `body`, przykładowy identyfikator komponentu; angielska forma może pozostać bez tłumaczenia | +| shield | `shield`, przykładowy identyfikator komponentu; angielska forma może pozostać bez tłumaczenia | +| buddy | `buddy`, przykładowy identyfikator obiektu; angielska forma może pozostać bez tłumaczenia | +| dance | `dance`, nazwa wiadomości; angielska forma może pozostać bez tłumaczenia | +| hash | hasz; techniczny termin oznaczający skrót lub funkcję skrótu | +| hashed | haszowany; angielska forma może pozostać bez tłumaczenia jako opis techniczny | +| hashed identifier | haszowany identyfikator | +| `msg.post()` | funkcja do wysyłania wiadomości | +| `go.get_id()` | funkcja zwracająca identyfikator obiektu gry | +| `go.set_position()` | funkcja ustawiająca pozycję obiektu | +| `factory.create()` | funkcja tworząca instancję | +| `#` | separator obiektu gry i komponentu | +| `.` | skrót oznaczający bieżący obiekt gry | +| `/` | prefiks adresu bezwzględnego od root kolekcji bootstrapowej | + +## `manuals/ads.md` + +This glossary covers the most relevant terms from the ads manual and keeps literal Defold, UI, API, and provider names in English. + +| English term | Polish translation / explanation | +|---|---| +| ads | reklamy | +| monetization | monetyzacja, czyli zarabianie na grze przez reklamy lub inne mechanizmy | +| ad format | format reklamy | +| banner ad | reklama banerowa, zwykle zajmująca niewielki fragment ekranu | +| interstitial ad | reklama pełnoekranowa wyświetlana między poziomami lub sesjami gry | +| rewarded ad / incentivized ad | reklama nagradzana; opcjonalna reklama, za której obejrzenie gracz otrzymuje nagrodę | +| ad network | sieć reklamowa | +| AdMob | `AdMob`, usługa sieci reklamowej Google | +| Enhance | `Enhance`, dostawca wspierający wiele sieci reklamowych | +| Facebook Instant Games | `Facebook Instant Games`, platforma, w której można wyświetlać reklamy | +| IronSource | `IronSource`, sieć reklamowa | +| Unity Ads | `Unity Ads`, sieć reklamowa | +| CPM | koszt za tysiąc wyświetleń reklamy (Cost per mille) | +| ad revenue | przychody z reklam | +| project dependency | zależność projektu dodawana do projektu Defold | +| In-app purchase | zakup wewnątrz aplikacji; w tym kontekście sposób na trwałe usunięcie reklam | + +## `manuals/android.md` + +This glossary covers the most relevant terms from the Android manual and keeps literal Defold, UI, API, and platform names in English. + + +| English term | Polish translation / explanation | +|---|---| +| Android | Android | +| development app | aplikacja do tworzenia i testowania gry na urządzeniu; w tekście pozostaje jako nazwa własna | +| hot reload | szybkie przeładowanie zasobów i kodu na urządzeniu | +| APK | pakiet aplikacji Android (`.apk`) | +| AAB | Android App Bundle (`.aab`) | +| application bundle | paczka aplikacji przygotowana do dystrybucji | +| Android application bundle | paczka aplikacji Android przygotowana do dystrybucji; angielska forma może pozostać bez tłumaczenia jako nazwa formatu | +| keystore | magazyn kluczy i certyfikatów używany do podpisywania aplikacji | +| certificate | certyfikat podpisu aplikacji | +| key | klucz prywatny używany przy podpisywaniu | +| debug keystore | testowy magazyn kluczy tworzony automatycznie przez Defold | +| Play Console | `Play Console`, panel Google Play do publikowania aplikacji | +| Play App Signing | `Play App Signing`, usługa Google podpisująca aplikacje po przesłaniu | +| `game.project` | plik ustawień projektu; zawiera konfigurację Androida | +| `AndroidManifest.xml` | plik manifestu Androida z uprawnieniami i metadanymi aplikacji | +| permission | uprawnienie wymagane przez system Android | +| `android.permission.INTERNET` | uprawnienie do korzystania z sieci | +| `android.permission.ACCESS_NETWORK_STATE` | uprawnienie do odczytu informacji o stanie sieci | +| `android.permission.WAKE_LOCK` | uprawnienie do blokowania usypiania urządzenia | +| `adb` | `Android Debug Bridge`, narzędzie do komunikacji z urządzeniem Android | +| USB debugging | debugowanie USB; wymagane do instalacji i uruchamiania z edytora | +| `logcat` | narzędzie do podglądu logów systemu Android | +| `bundletool` | narzędzie Google do pracy z pakietami AAB i generowania APK | +| `AndroidX` | `AndroidX`, współczesny zestaw bibliotek zastępujący Android Support Library | +| `Android Support Library` | starsza biblioteka wsparcia Androida | + +## `manuals/animation.md` + +This glossary covers the most relevant terms from the animation manual and keeps literal Defold/API identifiers in English. + + +| English term | Polish translation / explanation | +|---|---| +| animation | animacja | +| built-in support | wbudowane wsparcie | +| component | komponent | +| flip-book animation | animacja poklatkowa; odtwarzanie serii statycznych obrazów po kolei | +| model animation | animacja modelu 3D | +| properties | właściwości; angielska forma może pozostać bez tłumaczenia jako nazwa pojęcia używana w manualu | +| property animation | animacja właściwości, czyli zmienianie wartości takich jak pozycja, skala i rotacja | +| Rive animation | animacja Rive; wektorowa animacja 2D oparta na szkielecie | +| Spine animation | animacja Spine; teksturowana animacja 2D oparta na szkielecie | +| graphics source | źródło grafiki używane przez komponent | +| extension | rozszerzenie | + +## `manuals/application-lifecycle.md` + +This glossary covers the most relevant terms from the application lifecycle manual and keeps literal Defold/API identifiers in English. + + +| English term | Polish translation / explanation | +|---|---| +| application lifecycle | cykl życia aplikacji | +| initialization | inicjalizacja | +| update loop | pętla aktualizacyjna | +| finalization | finalizacja | +| `init()` | funkcja inicjalizacji wywoływana na starcie komponentu | +| `update()` | funkcja aktualizacji wywoływana co klatkę | +| `late_update()` | późna aktualizacja wykonywana po `update()` | +| `fixed_update()` | aktualizacja wykonywana stałokrokowo, zwykle dla fizyki | +| `final()` | funkcja czyszcząca wywoływana przed usunięciem komponentu | +| game object | obiekt gry | +| component | komponent | +| collection | kolekcja | +| collection proxy | pełnomocnik kolekcji | +| render script | skrypt do renderowania; angielska nazwa może pozostać bez tłumaczenia | +| view frustum | bryła widokowa | +| clipping plane | płaszczyzna odcięcia; angielska nazwa może pozostać bez tłumaczenia | +| `@render` | socket renderera, do którego trafiają wiadomości związane z renderowaniem | +| `@system` | socket systemowy używany do komunikatów sterujących silnikiem | +| `game.project` | plik konfiguracyjny projektu | +| `set_update_frequency` | wiadomość ustawiająca liczbę aktualizacji na sekundę | +| `set_time_step` | wiadomość ustawiająca krok czasowy kolekcji | +| `dispatch messages` | etap rozsyłania wiadomości | +| `message dispatcher` | mechanizm rozsyłania wiadomości | +| `spawn dynamic objects` | tworzenie dynamicznych obiektów | +| post update | etap po aktualizacji, w którym silnik przetwarza usuwanie i tworzenie obiektów | +| input bindings | wiązania wejść | +| acquired input focus | przechwycone wejście; stan, w którym obiekt otrzymuje zdarzenia wejściowe | +| transform / transforms | transformacja: pozycja, obrót i skala obiektu | +| collision object | obiekt kolizji | +| triggers | wyzwalacze | +| ray_cast | rzut promienia | +| socket | gniazdo silnika; angielska nazwa może pozostać bez tłumaczenia | +| factory | fabryka | +| time step | krok czasowy | +| physics | fizyka | +| frame render | końcowe renderowanie klatki | +| Advanced topics | sekcja "Advanced topics"; angielska nazwa sekcji może pozostać bez tłumaczenia | + +## `manuals/atlas.md` + +This glossary covers the most relevant terms from the atlas manual and keeps literal Defold/API identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| atlas | atlas, czyli zasób łączący wiele obrazów w jedną teksturę | +| sprite | sprite / obraz używany jako źródło grafiki | +| particlefx | ParticleFX, komponent efektów cząsteczkowych | +| Assets | `Assets`, widok projektu z plikami zasobów | +| Outline | `Outline`, widok struktury atlasu | +| Properties | `Properties`, panel właściwości atlasu i obrazów | +| Add Images | `Add Images`, polecenie dodawania pojedynczych obrazów do atlasu | +| Add Animation Group | `Add Animation Group`, polecenie tworzenia grupy animacji flipbook | +| flipbook animation | animacja klatkowa odtwarzana z kolejnych obrazów | +| frame selection | dopasowanie widoku do zaznaczenia | +| Margin | margines między obrazami w atlasie | +| Inner Padding | wewnętrzny margines wokół każdego obrazu | +| Extrude Borders | powielanie pikseli krawędzi, aby ograniczyć „przeciekanie” sąsiednich obrazów | +| Max Page Size | maksymalny rozmiar strony w atlasie wielostronicowym | +| Rename Patterns | wzorce wyszukiwania i zamiany używane do zmiany nazw obrazów | +| Pivot | punkt zakotwiczenia obrazu | +| Sprite Trim Mode | tryb przycinania sprite'a | +| Fps | liczba klatek na sekundę; nazwa właściwości animacji | +| Playback | sposób odtwarzania animacji | +| `resource.create_texture()` | funkcja tworząca zasób tekstury w czasie działania programu | +| `resource.set_texture()` | funkcja ustawiająca piksele tekstury lub jej fragmentu | +| `resource.create_atlas()` | funkcja tworząca atlas w czasie działania programu | +| `go.set()` | funkcja ustawiająca właściwość komponentu, np. teksturę modelu lub sprite'a | +| `sprite.play_flipbook()` | funkcja odtwarzająca animację flipbook | +| `texturec` | skompilowany zasób tekstury | +| `texturesetc` | skompilowany zasób atlasu tekstur | + +## `manuals/building-blocks.md` + +Zakres: najważniejsze pojęcia z instrukcji o blokach budujących Defold. + + +| English term | Polish translation / explanation | +| --- | --- | +| Collection | kolekcja; plik służący do budowania hierarchii obiektów gry i innych kolekcji | +| bootstrap collection | główna kolekcja uruchamiana na starcie gry | +| Game object | obiekt gry; pojemnik na komponenty z własnym `id`, pozycją, rotacją i skalą | +| Component | komponent; element dodawany do obiektu gry, np. `sprite`, `script` lub `sound` | +| path | ścieżka adresowania obiektu; angielska forma może pozostać bez tłumaczenia | +| waypoint / startpoint / checkpoint | znacznik pozycji; w instrukcji występują jako literalne nazwy `waypoint`, `startpoint` i `checkpoint` | +| blueprint / prototype | prototyp lub szablon pliku bazowego, na którym opiera się instancja; angielskie nazwy mogą pozostać bez tłumaczenia | +| instance | instancja; konkretne wystąpienie obiektu, kolekcji lub komponentu w projekcie | +| factory | fabryka; komponent używany do dynamicznego tworzenia obiektów gry | +| parent-child hierarchy | hierarchia rodzic-dziecko; relacja wpływająca na transformacje obiektów | +| `Outline` | `Outline`; widok zawartości pliku w edytorze, angielska forma może pozostać bez tłumaczenia | +| `Add Collection File` | `Add Collection File`; polecenie dodania kolekcji jako referencji do pliku, angielska forma może pozostać bez tłumaczenia | +| `set_parent` | `set_parent`; wiadomość ustawiająca rodzica obiektu w czasie działania gry, angielska forma może pozostać bez tłumaczenia | + +## `manuals/caching-assets.md` + +This glossary covers the most relevant terms from the caching assets manual and keeps literal Defold, API, and option names in English. + +| English term | Polish translation / explanation | +|---|---| +| asset cache | bufor zasobów | +| build | kompilacja lub budowanie projektu, zależnie od kontekstu | +| compiled assets | skompilowane zasoby | +| project cache | bufor projektu, domyślny lokalny cache w `build/default` | +| local cache | bufor lokalny; opcjonalny cache na tym samym komputerze lub w sieci | +| remote cache | bufor zdalny; opcjonalny cache na serwerze dostępnym przez HTTP | +| `build/default` | folder z plikami cache projektu | +| `clean` | polecenie usuwające dane bufora projektu | +| `resource-cache-local` | opcja włączająca lokalny cache | +| `resource-cache-remote` | opcja włączająca zdalny cache | +| checksum | suma kontrolna używana do identyfikacji poprawnych plików w cache | +| HTTP request | żądanie HTTP | +| GET / PUT / HEAD | metody HTTP używane do odczytu, zapisu i sprawdzania zasobów | + +## `manuals/camera.md` + +This glossary covers the most relevant terms from the camera manual and keeps literal Defold/API identifiers in English. + + +| English term | Polish translation / explanation | +|---|---| +| camera | kamera | +| render script | skrypt do renderowania; angielska nazwa może pozostać bez tłumaczenia | +| viewport | obszar widoku, czyli część świata gry widoczna na ekranie | +| projection | projekcja, czyli sposób odwzorowania świata na ekranie | +| perspective camera | kamera perspektywiczna | +| orthographic projection | rzut ortograficzny | +| view matrix | macierz widoku | +| projection matrix | macierz projekcji | +| frustum | bryła widokowa | +| view frustum | bryła widokowa | +| clipping plane | płaszczyzna odcięcia; angielska nazwa może pozostać bez tłumaczenia | +| field of view / `fov` | pole widzenia kamery; `fov` to nazwa właściwości i API | +| `Near Z` | bliska płaszczyzna odcięcia; nazwa właściwości w edytorze | +| `Far Z` | daleka płaszczyzna odcięcia; nazwa właściwości w edytorze | +| `Orthographic Zoom` | powiększenie dla kamery ortograficznej; nazwa właściwości w edytorze | +| `Orthographic Mode` | tryb określający sposób wyznaczania zoomu względem rozmiaru okna i rozdzielczości projektu | +| `Auto Fit` | automatyczne dopasowanie, aby cały obszar projektu zmieścił się w oknie | +| `Auto Cover` | automatyczne pokrycie, aby obszar projektu wypełnił całe okno | +| `Fixed` | stały zoom ustawiany ręcznie | +| `acquire_camera_focus` | wiadomość używana w starszym sposobie aktywowania kamery; w nowych projektach preferowane są `enable` i `disable` | +| `set_view_projection` | wiadomość wysyłana do `@render` z macierzą widoku i projekcji | +| `render.set_camera()` | funkcja renderowania ustawiająca aktywną kamerę dla rysowania | +| `camera.get_cameras()` | funkcja zwracająca listę dostępnych kamer | +| `go.set()` / `go.get()` | funkcje używane do odczytu i zmiany właściwości kamery w czasie działania | +| `@render` | socket renderera, do którego trafiają wiadomości z kamery | +| `game.project` | plik konfiguracyjny projektu; w tym kontekście zawiera ustawienia rozdzielczości i wyświetlania | +| `display.width` / `display.height` | wartości rozdzielczości projektu używane przy obliczaniu proporcji i zoomu | +| adaptive zoom | adaptacyjny zoom dopasowujący kamerę do zmiany rozdzielczości okna | +| frustum culling | odrzucanie obiektów poza bryłą widokową | + +## `manuals/collection-factory.md` + +Zakres: najważniejsze pojęcia z instrukcji o `collectionfactory` i tworzeniu kolekcji w czasie działania gry. + +| English term | Polish translation / explanation | +| --- | --- | +| Collection factory | fabryka kolekcji; komponent tworzący w grze zawartość pliku kolekcji | +| Collection | kolekcja; plik służący do opisu grup i hierarchii obiektów gry | +| game object | obiekt gry; pojedynczy element sceny, który może mieć komponenty i relacje rodzic-dziecko | +| Prototype | `Prototype`; właściwość komponentu wskazująca plik kolekcji używany jako wzorzec | +| collectionfactory.create() | `collectionfactory.create()`; funkcja tworząca instancje obiektów z kolekcji | +| collectionfactory.load() | `collectionfactory.load()`; funkcja wczytująca zasoby fabryki asynchronicznie | +| collectionfactory.unload() | `collectionfactory.unload()`; funkcja zwalniająca zasoby wczytane przez fabrykę | +| collectionfactory.set_prototype() | `collectionfactory.set_prototype()`; funkcja zmieniająca używany prototyp kolekcji | +| Load Dynamically | `Load Dynamically`; opcja odraczająca wczytanie zasobów do chwili tworzenia | +| Dynamic Prototype | `Dynamic Prototype`; opcja pozwalająca zmieniać prototyp w czasie działania | +| collection proxy | pełnomocnik kolekcji; osobny świat gry ładowany wraz z własnym socketem | +| `go.property()` | `go.property()`; deklaracja właściwości skryptu używana przy przekazywaniu danych do tworzonych obiektów | + +## `manuals/collection-proxy.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o collection proxy i zostawia literalne nazwy API oraz wiadomości w języku angielskim. + + +| English term | Polish translation / explanation | +| --- | --- | +| collection proxy | pełnomocnik kolekcji | +| collection | kolekcja | +| collection file | plik kolekcji | +| bootstrap collection | kolekcja startowa ładowana przy uruchomieniu silnika | +| game world | świat gry | +| physics world | świat fizyki | +| collection factory | fabryka kolekcji | +| `load` | wiadomość rozpoczynająca wczytywanie kolekcji do nowego świata | +| `async_load` | wiadomość rozpoczynająca asynchroniczne wczytywanie kolekcji | +| `proxy_loaded` | wiadomość zwrotna wysyłana po zakończeniu wczytywania | +| `init` | wiadomość inicjalizująca utworzone obiekty i komponenty | +| `enable` | wiadomość aktywująca obiekty i komponenty | +| `disable` | wiadomość dezaktywująca obiekty i komponenty | +| `final` | wiadomość finalizująca obiekty i komponenty | +| `unload` | wiadomość usuwająca świat z pamięci | +| `proxy_unloaded` | wiadomość zwrotna wysyłana po zakończeniu zwalniania | +| `set_time_step` | wiadomość ustawiająca krok czasowy kolekcji | +| `Name` | właściwość nazwy świata; musi być unikalna | +| `Collection` | właściwość wskazująca kolekcję do wczytania | +| `Exclude` | opcja wykluczająca zasób z kompilacji i pozwalająca pobrać go później | +| `Live update` | funkcja dynamicznego pobierania zasobów w trakcie działania gry | +| `update()` | funkcja aktualizacji wywoływana co klatkę | +| `dt` | czas kroku przekazywany do `update()` | +| loader | obiekt odpowiedzialny za wczytywanie poziomów; angielska nazwa może pozostać bez tłumaczenia | +| time step | krok czasowy | +| `factor` | współczynnik skali kroku czasowego | +| `mode` | tryb skalowania kroku czasowego | +| `input focus` | przechwycenie wejścia przez obiekt gry | + +## `manuals/components.md` + +This glossary covers the most relevant terms from the components article and keeps literal Defold/API identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| component | komponent | +| game object | obiekt gry | +| component type | typ komponentu | +| Collection factory | fabryka kolekcji | +| Collection proxy | pełnomocnik kolekcji | +| Collision object | obiekt kolizji | +| Camera | kamera | +| Factory | fabryka | +| GUI | GUI, czyli interfejs użytkownika renderowany w osobnym przebiegu | +| Label | etykieta | +| Mesh | siatka 3D | +| Model | model 3D | +| Particle FX | efekty cząsteczkowe | +| Script | skrypt | +| Sound | dźwięk | +| Sprite | sprite, czyli obraz 2D | +| Tilemap | mapa kafelków | +| enable | wiadomość włączająca komponent | +| disable | wiadomość wyłączająca komponent | +| Properties pane | panel `Properties` z właściwościami komponentu | +| Outline pane | panel `Outline` z listą struktury i zaznaczonego elementu | +| position | pozycja | +| rotation | rotacja / orientacja | +| scale | skala | +| render script | skrypt do renderowania | +| predicate | predykat w skrypcie renderowania | +| material | materiał | +| tag | tag materiału używany do dopasowania w predykacie | +| z-value | wartość Z; pozycja w osi głębi | +| GUI render order | kolejność renderowania GUI | +| near plane | płaszczyzna bliska | +| far plane | płaszczyzna daleka | + +## `manuals/debugging-game-logic.md` + +Zakres: najważniejsze pojęcia z instrukcji o debugowaniu logiki gry w Defoldzie. + +| English term | Polish translation / explanation | +| --- | --- | +| debugger | debugger; narzędzie do zatrzymywania, analizowania i wznawiania wykonania gry | +| inspection facility | narzędzie do inspekcji; pozwala podglądać stan programu podczas debugowania | +| profiling tools | narzędzia profilowania; pomagają analizować wydajność | +| print debugging | debugowanie za pomocą wydruków; używanie `print()` i `pprint()` do śledzenia wykonania | +| `print()` | `print()`; wypisuje tekst do konsoli i logu gry | +| `pprint()` | `pprint()`; czytelniej wypisuje struktury danych | +| `@render` | `@render`; socket, do którego wysyła się wiadomości rysujące debugowanie wizualne | +| `draw_text` | `draw_text`; rysuje tekst debugowania na ekranie | +| `draw_debug_text` | `draw_debug_text`; jak `draw_text`, ale z własnym kolorem | +| `draw_line` | `draw_line`; rysuje linię debugowania, np. między obiektami | +| breakpoint | punkt przerwania; miejsce, w którym debugger zatrzymuje wykonanie | +| Break | Break; zatrzymuje wykonanie gry w bieżącym miejscu | +| Continue | Continue; wznawia wykonanie do następnego zatrzymania | +| Step Over | Step Over; wykonuje bieżącą linię bez wchodzenia do funkcji | +| Step Into | Step Into; wchodzi do wywołanej funkcji i pokazuje stos wywołań | +| Step Out | Step Out; kontynuuje do wyjścia z bieżącej funkcji | +| conditional breakpoint | warunkowy punkt przerwania; uruchamia się tylko, gdy warunek jest spełniony | +| call stack | stos wywołań; lista aktywnych wywołań funkcji | +| Lua debug library | biblioteka debugowania Lua; narzędzia do analizy wnętrza środowiska Lua | +| physics debugging | debugowanie fizyki; rysowanie kształtów kolizji i punktów kontaktu | + +## `manuals/editor-keyboard-shortcuts.md` + +This glossary covers the most relevant literal editor terms from the keyboard shortcuts manual and keeps Defold UI labels and command names in English. + +| English term | Polish translation / explanation | +|---|---| +| `Add` | komenda do dodawania elementu lub akcji w bieżącym kontekście | +| `Build` | komenda budowania projektu | +| `Hot reload` | szybkie przeładowanie zmian bez pełnego restartu | +| `Open asset` | komenda otwierania zasobu w Edytorze | +| `Preferences` | preferencje Edytora; nazwa pozycji menu | +| `File ▸ Preferences` | ścieżka menu prowadząca do ustawień | +| `Path to Custom Keymap` | pole ustawień, w którym podaje się ścieżkę do własnego pliku mapy skrótów | +| `keymap.edn` | nazwa przykładowego pliku konfiguracyjnego mapy skrótów | +| `Rebuild` | komenda ponownego budowania projektu | +| `Rebundle` | komenda ponownego pakowania artefaktów projektu | +| `Search in files` | wyszukiwanie tekstu we wszystkich plikach projektu | +| `Toggle comment` | przełącza komentarz dla zaznaczonego kodu | + +## `manuals/editor-preferences.md` + +Zakres: najważniejsze terminy użyte w artykule o ustawieniach i preferencjach Edytora Defold. + +| English term | Polish translation / explanation | +|---|---| +| Preferences window | okno Preferencji, z którego zmienia się ustawienia Edytora | +| File -> Preferences | menu File -> Preferences | +| Load External Changes on App Focus | wczytywanie zewnętrznych zmian po aktywowaniu aplikacji | +| Open Bundle Target Folder | otwieranie folderu docelowego pakietu po zakończeniu bundlowania | +| Enable Texture Compression | włączenie kompresji tekstur dla buildów tworzonych z Edytora | +| Escape Quits Game | klawisz Esc kończy uruchomioną grę | +| Track Active Tab in Asset Browser | śledzenie aktywnej karty w przeglądarce zasobów | +| Lint Code on Build | sprawdzanie kodu podczas budowania projektu | +| Engine Arguments | argumenty przekazywane do `dmengine` | +| Custom Editor | zewnętrzny edytor wskazany pełną ścieżką | +| Open File at Line | wzorzec otwierania pliku wraz z numerem linii | +| Build Server | serwer budowania dla projektów z native extensions | +| Build Server Headers | dodatkowe nagłówki wysyłane do serwera budowania | +| ADB | narzędzie Android Debug Bridge do instalacji i uruchamiania APK | +| ios-deploy | narzędzie wiersza poleceń do instalacji i uruchamiania aplikacji iOS | +| Keymap | mapa skrótów klawiaturowych Edytora | +| shortcut table | tabela skrótów, w której edytuje się przypisania | + +## `manuals/editor-scripts.md` + +To są najważniejsze terminy użyte w instrukcji o skryptach Edytora. + +| English term | Polish translation / explanation | +|---|---| +| `.editor_script` | plik skryptu Edytora; plik Lua z tym rozszerzeniem definiuje komendy, haczyki cyklu życia i inne rozszerzenia | +| `hooks.editor_script` | specjalny plik w katalogu głównym projektu, który odbiera zdarzenia cyklu życia | +| `editor` package | pakiet API do komunikacji z Edytorem | +| `editor.get()` | pobiera wartość właściwości węzła lub zasobu | +| `editor.can_get()` | sprawdza, czy daną właściwość można odczytać bez błędu | +| `editor.can_set()` | sprawdza, czy daną właściwość można ustawić bez błędu | +| `editor.transact()` | wykonuje zestaw zmian w stanie Edytora jako jedną operację z możliwością cofnięcia | +| `editor.execute()` | uruchamia komendę powłoki; odpowiednik bezpieczniejszy niż `os.execute()` | +| `editor.save()` | zapisuje niezapisane zmiany na dysk | +| `get_commands()` | funkcja zwracająca definicje komend menu i menu kontekstowego | +| `active` | funkcja sprawdzająca, czy komenda jest dostępna w danym momencie | +| `run` | funkcja wykonywana po wybraniu komendy | +| `actions` | akcje opisujące zmiany, które Edytor ma wykonać | +| `undoable` | akcja, którą można cofnąć przez Undo lub `Ctrl + Z` | +| `non-undoable` | akcja, której nie można cofnąć z poziomu Edytora | +| `shell` | akcja uruchamiająca skrypt powłoki | +| `lifecycle hooks` | haki cyklu życia wywoływane podczas budowania, pakowania lub uruchamiania gry | +| `Project → Reload Editor Scripts` | polecenie do ponownego wczytania skryptów Edytora | +| `Outline` | widok struktury zasobów i węzłów; literalna nazwa interfejsu | +| `Assets` | panel zasobów; literalna nazwa interfejsu | + +## `manuals/editor-styling.md` + +Zakres: najważniejsze terminy użyte w artykule o dostosowywaniu kolorów, czcionek i arkuszy stylów Edytora Defold. + +| English term | Polish translation / explanation | +|---|---| +| `.defold` | folder w katalogu domowym użytkownika, w którym Edytor szuka własnych ustawień | +| `editor.css` | plik z własnym arkuszem stylów Edytora | +| custom stylesheet | niestandardowy arkusz stylów | +| stylesheet | arkusz stylów | +| CSS | CSS, czyli język opisu stylu znany z przeglądarek | +| JavaFX | JavaFX, technologia interfejsu używana przez Edytor | +| `root` | element główny arkusza stylów; miejsce ustawiania domyślnej czcionki | +| `_palette.scss` | plik z domyślną paletą kolorów Edytora | +| `_typography.scss` | plik z domyślnymi definicjami typografii | +| `@font-face` | reguła definiująca źródło czcionki | +| `font-family` | nazwa rodziny czcionek używana w stylach | +| `-fx-font-family` | właściwość JavaFX ustawiająca czcionkę w interfejsie | +| `Preferences` | okno ustawień, w którym osobno definiuje się czcionkę edytora kodu | + +## `manuals/editor-templates.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o dodawaniu własnych szablonów projektów do okna Nowy projekt. + +| English term | Polish translation / explanation | +| --- | --- | +| New Project window | okno New Project | +| custom project templates | własne, niestandardowe szablony projektów | +| tab | zakładka z szablonami w oknie New Project | +| `welcome.edn` | plik konfiguracyjny w katalogu `.defold` | +| `.defold` folder | folder konfiguracyjny w katalogu domowym użytkownika | +| Extensible Data Notation | format danych używany przez `welcome.edn` | +| `{:new-project ...}` | struktura konfiguracji definiująca szablony w edytorze | +| `categories` | lista kategorii szablonów | +| `templates` | lista pojedynczych szablonów projektu | +| `zip-url` | adres URL archiwum ZIP z szablonem | +| `skip-root?` | flaga pomijająca katalog główny archiwum | +| bundled with the editor | dołączone do Edytora | + +## `manuals/editor.md` + +Zakres: najważniejsze literalne terminy z artykułu o widokach, panelach i podstawowych akcjach Edytora Defold. + +| English term | Polish translation / explanation | +|---|---| +| `Editor` | Edytor Defold | +| `Open From Disk…` | opcja otwierania istniejącego projektu z dysku | +| `Create New Project` | przycisk tworzenia nowego projektu | +| `TEMPLATES` | zakładka z gotowymi szablonami projektów | +| `TUTORIALS` | zakładka z projektami instruktażowymi | +| `SAMPLES` | zakładka z przykładowymi projektami | +| `Assets` | panel zasobów z plikami i folderami projektu | +| `Outline` | panel zawartości pliku w widoku drzewiastym | +| `Properties` | panel właściwości zaznaczonego elementu | +| `Tools` | panel narzędzi, m.in. `Console`, `Build Errors` i `Search Results` | +| `Changed Files` | panel zmienionych plików w repozytorium Git | +| `Scene Editor` | edytor sceny do pracy z kolekcjami, obiektami gry i komponentami wizualnymi | +| `Move` | narzędzie przesuwania obiektów | +| `Rotate` | narzędzie obracania obiektów | +| `Scale` | narzędzie skalowania obiektów | +| `Console` | konsola; widoczna etykieta panelu Edytora, angielska forma może pozostać bez tłumaczenia | +| `Curve Editor` | edytor krzywych; widoczna etykieta panelu Edytora, angielska forma może pozostać bez tłumaczenia | +| `Build Errors` | błędy budowania; widoczna etykieta panelu Edytora, angielska forma może pozostać bez tłumaczenia | +| `Search Results` | wyniki wyszukiwania; widoczna etykieta panelu Edytora, angielska forma może pozostać bez tłumaczenia | +| `File ▸ Preferences ▸ General ▸ Editor Language` | ścieżka ustawienia języka interfejsu Edytora | +| `Update Available` | komunikat lub przycisk informujący o dostępnej aktualizacji | + +## `manuals/factory.md` + +Ten słowniczek obejmuje najważniejsze pojęcia użyte w instrukcji o komponencie `factory`. + +| English term | Polish translation / explanation | +| --- | --- | +| factory | fabryka; komponent tworzący nowe obiekty gry w czasie działania | +| game object | obiekt gry | +| Prototype | `Prototype`; właściwość wskazująca plik obiektu gry używany jako wzorzec | +| factory.create() | `factory.create()`; funkcja tworząca nowy obiekt gry | +| factory.load() | `factory.load()`; funkcja asynchronicznie wczytująca zasoby fabryki | +| factory.unload() | `factory.unload()`; funkcja zwalniająca zasoby wczytane przez fabrykę | +| Load Dynamically | `Load Dynamically`; opcja odraczająca wczytanie zasobów do chwili tworzenia | +| url | `url`; identyfikator komponentu fabryki lub utworzonego obiektu | +| position | `position`; pozycja świata dla nowego obiektu gry | +| rotation | `rotation`; obrót świata dla nowego obiektu gry | +| properties | `properties`; tabela Lua z wartościami właściwości skryptu przekazywanymi przy tworzeniu | +| scale | `scale`; skala utworzonego obiektu gry, jako `number` lub `vector3` | +| collision shapes | kształty kolizji; nie obsługują obecnie nieliniowego skalowania | +| msg.url() | `msg.url()`; funkcja budująca adres komponentu lub obiektu | +| msg.post() | `msg.post()`; funkcja wysyłająca wiadomość do obiektu lub komponentu | + +## `manuals/flash.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o Flashu i pozostawia literalne nazwy API, plików oraz komponentów w języku angielskim. + +| English term | Polish translation / explanation | +| --- | --- | +| movie clip | klip filmowy; symbol z własną osią czasu | +| timeline | oś czasu; sekwencja klatek i animacji | +| Stage | scena; najwyższy kontener projektu Flash | +| ActionScript | język skryptowy używany we Flashu | +| game object | obiekt gry | +| collection | kolekcja; kontener na obiekty gry i inne kolekcje | +| factory | fabryka; komponent tworzący instancje obiektów gry | +| collection proxy | pełnomocnik kolekcji; ładuje nowy świat gry | +| `go.animate()` | funkcja do animowania właściwości obiektu | +| `factory.create()` | funkcja tworząca instancję obiektu gry | +| `go.get_id()` | funkcja zwracająca id bieżącego obiektu gry | +| `hitTestObject()` | test kolizji na podstawie prostokątów ograniczających | +| `hitTestPoint()` | test kolizji punktu względem kształtu | +| z position | pozycja w osi Z; określa głębię renderowania | +| display list | lista wyświetlania; porządek rysowania obiektów | + +## `manuals/flipbook-animation.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o animacjach flip-book i zachowuje literalne identyfikatory API oraz nazwy własne w języku angielskim. + +| English term | Polish translation / explanation | +|---|---| +| flip-book animation | animacja poklatkowa; seria statycznych klatek odtwarzanych po kolei | +| GUI | interfejs graficzny użytkownika; gdy chodzi o nazwę widocznego elementu interfejsu, angielska forma może pozostać bez tłumaczenia | +| frame | klatka animacji | +| frames per second (FPS) | liczba klatek na sekundę; skrót FPS może pozostać bez tłumaczenia | +| sprite | sprite / obraz; komponent odtwarzający animację | +| GUI box node | węzeł GUI typu box; element interfejsu, który może odtwarzać flip-book | +| atlas | Atlas; zasób z obrazami używanymi przez animację | +| Tile Source | Tile Source; źródło kafelków z klatkami ułożonymi w sekwencji | +| `sprite.play_flipbook()` | funkcja odtwarzająca animację flip-book na sprite'cie | +| `gui.play_flipbook()` | funkcja odtwarzająca animację flip-book na węźle GUI | +| Playback mode | tryb odtwarzania | +| `once ping-pong` | tryb odtwarzania w przód i z powrotem, do drugiej klatki | +| callback | funkcja wywoływana po zakończeniu animacji | +| looping animation | animacja zapętlona | +| `go.cancel_animations()` | funkcja anulująca animacje; przerywa także wywołanie callbacka | + +## `manuals/font.md` + +Ten słowniczek obejmuje najważniejsze pojęcia użyte w instrukcji o fontach i zachowuje literalne identyfikatory Defold oraz API po angielsku. + +| English term | Polish translation / explanation | +| --- | --- | +| font | font; zasób używany do renderowania tekstu | +| Label | `Label`; komponent tekstowy | +| GUI text node | węzeł tekstowy GUI | +| TrueType | `TrueType`; format pliku czcionki | +| OpenType | `OpenType`; format pliku czcionki | +| BMFont | `BMFont`; wstępnie przygotowany format bitmapowy z plikiem `.fnt` | +| bitmap font | font bitmapowy | +| distance field font | font pola odległości | +| runtime font | font uruchamiany w czasie działania; rasteryzacja odbywa się na żądanie | +| font collection | kolekcja fontów; plik `.fontc` może grupować kilka fontów `.ttf` | +| glyph | glif; pojedynczy znak w fontcie | +| glyph cache | pamięć podręczna glifów | +| Render Mode | `Render Mode`; tryb renderowania glifów | +| MODE_SINGLE_LAYER | `MODE_SINGLE_LAYER`; jeden quad na znak | +| MODE_MULTI_LAYER | `MODE_MULTI_LAYER`; osobne quady dla kształtu, obrysu i cienia | +| Output Format | `Output Format`; format danych generowanych z fontu | +| TYPE_BITMAP | `TYPE_BITMAP`; bitmapowe dane fontu | +| TYPE_DISTANCE_FIELD | `TYPE_DISTANCE_FIELD`; dane pola odległości | +| Material | `Material`; materiał używany do renderowania fontu | +| builtins/fonts/font-df.material | `builtins/fonts/font-df.material`; materiał dla fontów pola odległości | +| builtins/fonts/font-fnt.material | `builtins/fonts/font-fnt.material`; materiał dla fontów BMFont | +| font.runtime_generation | `font.runtime_generation`; ustawienie w `game.project` włączające generowanie w czasie działania | +| font.prewarm_text() | `font.prewarm_text()`; funkcja wstępnego uzupełniania pamięci podręcznej glifów | +| texture_size_recip | `texture_size_recip`; stała shadera z metrykami pamięci podręcznej | + +## `manuals/getting-help.md` + +Zakres: najistotniejsze terminy użyte w artykule o zgłaszaniu problemów i szukaniu pomocy. + +| English term | Polish translation / explanation | +|---|---| +| forum | forum Defold, miejsce zadawania pytań i omawiania problemów | +| `Questions` | kategoria pytań na forum | +| `Bugs` | kategoria zgłoszeń błędów na forum | +| `search` | wyszukiwanie na forum przed zadaniem pytania | +| `Help->Report Issue` | polecenie w edytorze do zgłoszenia problemu | +| `Discord` | kanał do szybkiej rozmowy; nie do zgłoszeń błędów | +| issue tracker | tracker zgłoszeń, czyli system śledzenia błędów | +| GitHub account | konto GitHub wymagane do zgłoszenia problemu przez edytor | +| log files | pliki z logami potrzebne przy zgłaszaniu problemu | +| `Engine logs` | logi silnika | +| `Editor logs` | logi edytora | +| `Build server logs` | logi serwera do budowania | +| minimal reproduction case project | mały projekt pozwalający odtworzyć błąd | +| workaround | obejście problemu | +| screenshots | zrzuty ekranu pomocne przy opisie problemu | +| additional context | dodatkowy kontekst do zgłoszenia | + +## `manuals/glossary.md` + +Zakres: najważniejsze literalne terminy z ogólnego słowniczka Defold. + +| English term | Polish translation / explanation | +|---|---| +| `Graphical User Interface` | interfejs graficzny użytkownika; skrót GUI może pozostać bez tłumaczenia | +| `Head-up display` | ekranowy interfejs gracza; skrót HUD może pozostać bez tłumaczenia | +| `tiles` | kafelki; małe powtarzalne obrazki używane do budowy atlasów i źródeł kafelków | +| `polygon` | wielokąt | + +## `manuals/gui-box.md` + +Zakres: najważniejsze literalne terminy z artykułu o węzłach GUI typu box i ich teksturowaniu. + +| English term | Polish translation / explanation | +|---|---| +| box node | węzeł typu box; prostokątny element GUI | +| GUI | interfejs użytkownika Defold | +| Outline | `Outline` - widok zawartości pliku w edytorze | +| Add ▸ Box | polecenie dodania nowego węzła box | +| Textures | folder `Textures` w `Outline` | +| Add ▸ Textures... | polecenie dodania tekstur do GUI | +| Texture | właściwość przypisująca teksturę do węzła | +| atlas | atlas - zestaw obrazów używany jako źródło tekstur lub animacji | +| tile source | źródło kafelków używane jako źródło tekstur lub animacji | +| tint | barwienie obrazu przez mnożenie koloru węzła | +| alpha | kanał alfa, czyli przezroczystość | +| renderer | renderer - moduł odpowiedzialny za rysowanie | +| draw calls | wywołania rysowania | +| animation | animacja | +| flipbook animation | animacja flipbook z atlasu lub źródła kafelków | + +## `manuals/gui-clipping.md` + +Zakres: najważniejsze pojęcia z instrukcji o wycinaniu i maskowaniu GUI w Defoldzie. + +| English term | Polish translation / explanation | +|---|---| +| clipping node | węzeł wycinający, czyli węzeł GUI, który tworzy lub modyfikuje maskę wycinania | +| Clipping Mode | tryb wycinania; `None` wyłącza wycinanie, a `Stencil` zapisuje maskę w buforze stencil | +| Clipping Visible | widoczność zawartości węzła wycinającego | +| Clipping Inverted | odwrócenie kształtu węzła zapisywanego do maski | +| stencil buffer | bufor stencil, w którym przechowywana jest maska wycinania | +| stencil mask | maska wycinania określająca, które piksele mogą zostać wyrenderowane | +| inverted clipper | odwrócony węzeł wycinający; zapisuje negatyw kształtu do maski | +| layers | warstwy; kontrolują kolejność renderowania i mogą zmieniać kolejność wycinania | +| hierarchy | hierarchia węzłów; układ rodzic-dziecko, który wpływa na dziedziczenie maski | +| Box, Text, Pie | typy węzłów GUI, które mogą służyć jako węzły wycinające | + +## `manuals/gui-layouts.md` + +This glossary covers the most relevant terms from the article and keeps literal Defold/UI/API identifiers in English. + + +| English term | Polish translation / explanation | +|---|---| +| GUI layouts | układy GUI; warianty tej samej sceny GUI dla różnych orientacji i rozmiarów ekranu | +| layouts | układy; warianty układu GUI dopasowane do orientacji i rozmiaru ekranu | +| display profiles | profile wyświetlania | +| `game.project` | plik konfiguracyjny projektu | +| `Display Profiles` | ustawienie wskazujące plik profili wyświetlania | +| `Dynamic Orientation` | opcja automatycznego przełączania układów po obrocie urządzenia | +| `Auto Layout Selection` | automatyczny dobór układu na podstawie dopasowania profilu | +| layout | układ GUI | +| `Default` | domyślny układ awaryjny, używany gdy nie ma lepszego dopasowania | +| qualifier | kwalifikator profilu; zestaw parametrów dopasowania | +| width | szerokość w pikselach | +| height | wysokość w pikselach | +| device models | modele urządzeń; lista modeli, z którymi może pasować profil | +| orientation | orientacja ekranu, np. `landscape` lub `portrait` | +| `layout_changed` | wiadomość wysyłana do skryptu GUI po zmianie układu | +| `gui.set_layout()` | funkcja ręcznego przełączania układu | +| `gui.get_layouts()` | funkcja zwracająca dostępne układy i ich rozmiary | +| `Outline` | widok `Outline`, w którym dodaje się układy | +| `Assets` | widok `Assets`, gdzie można utworzyć plik profili wyświetlania | + +## `manuals/gui-particlefx.md` + +Krótki słowniczek najważniejszych terminów z artykułu o węzłach ParticleFX w GUI. + + +| English term | Polish translation / explanation | +| --- | --- | +| particle effect node | węzeł efektu cząsteczkowego | +| GUI screen space | przestrzeń ekranu GUI | +| particle effect system | system efektów cząsteczkowych | +| Outline | `Outline` (widok zawartości pliku w edytorze) | +| Particle FX | `Particle FX` (folder z zasobami efektów cząsteczkowych) | +| ParticleFX | `ParticleFX` (typ węzła GUI do odtwarzania efektów cząsteczkowych) | +| particlefx property | właściwość `Particlefx` | +| `gui.get_node()` | pobiera węzeł GUI po nazwie | +| `gui.play_particlefx()` | uruchamia efekt cząsteczkowy na węźle | +| `gui.stop_particlefx()` | zatrzymuje efekt cząsteczkowy na węźle | + +## `manuals/gui-pie.md` + +Ten słowniczek obejmuje najważniejsze terminy używane w instrukcji o węzłach GUI typu pie. + +| English term | Polish translation / explanation | +| --- | --- | +| GUI pie node | węzeł GUI typu pie; element interfejsu o kształcie okręgu, elipsy lub pierścienia | +| Nodes | `Nodes`; sekcja drzewa z węzłami w widoku `Outline` | +| Outline | `Outline` (widok zawartości) | +| Add ▸ Pie | `Add ▸ Pie`; polecenie dodania nowego węzła pie | +| Inner Radius | `Inner Radius`; wewnętrzny promień wzdłuż osi X | +| Outer Bounds | `Outer Bounds`; kształt zewnętrznej granicy węzła | +| Ellipse | `Ellipse`; zewnętrzna granica dopasowana do promienia elipsy | +| Rectangle | `Rectangle`; zewnętrzna granica dopasowana do obwiedni węzła | +| Perimeter Vertices | `Perimeter Vertices`; liczba wierzchołków tworzących obwód kształtu | +| Pie Fill Angle | `Pie Fill Angle`; kąt wypełnienia liczony przeciwnie do ruchu wskazówek zegara od prawej strony | +| texture | tekstura; obraz nakładany płasko na obszar węzła | +| gui.get_node() | `gui.get_node()`; pobiera węzeł GUI po nazwie | +| gui.get_fill_angle() | `gui.get_fill_angle()`; zwraca kąt wypełnienia | +| gui.get_perimeter_vertices() | `gui.get_perimeter_vertices()`; zwraca liczbę wierzchołków obwodu | +| gui.set_perimeter_vertices() | `gui.set_perimeter_vertices()`; ustawia liczbę wierzchołków obwodu | +| gui.set_outer_bounds() | `gui.set_outer_bounds()`; ustawia typ zewnętrznej granicy | +| gui.PIEBOUNDS_RECTANGLE | `gui.PIEBOUNDS_RECTANGLE`; stała oznaczająca granicę prostokątną | +| gui.animate() | `gui.animate()`; animuje właściwość węzła w czasie działania programu | + +## `manuals/gui-script.md` + +Zakres: najważniejsze terminy z artykułu o skryptach GUI, z zachowaniem literalnych identyfikatorów Defold i API w języku angielskim. + + +| English term | Polish translation / explanation | +|---|---| +| GUI script | skrypt GUI; skrypt Lua sterujący zachowaniem komponentu GUI | +| `gui` | moduł API do pracy z GUI | +| `go` | moduł API obiektów gry; w skryptach GUI nie jest dostępny | +| namespace | przestrzeń nazw; w tym artykule `gui`, a w skryptach GUI nie jest dostępna przestrzeń nazw `go` | +| GUI component | komponent GUI; element interfejsu sterowany przez skrypt GUI | +| GUI component prototype | prototyp komponentu GUI; plik definiujący strukturę komponentu | +| `Outline` | widok `Outline`, w którym wybiera się korzeń komponentu | +| `Properties` | panel `Properties`, gdzie ustawia się właściwości komponentu | +| `Script` | właściwość wskazująca plik skryptu GUI | +| node | węzeł GUI; element interfejsu, który można odczytywać i modyfikować | +| `Id` | unikalny identyfikator węzła ustawiany w edytorze | +| message passing | przesyłanie wiadomości między komponentami w czasie działania | +| `msg.post()` | funkcja wysyłająca wiadomość do komponentu | +| `init()`, `final()`, `update()` | funkcje cyklu życia skryptu | +| `gui.get_node()` | funkcja pobierająca referencję do węzła po `Id` | +| `gui.new_[type]_node()` | rodzina funkcji tworzących nowe węzły w czasie działania | +| `gui.clone()` | funkcja klonująca pojedynczy węzeł | +| `gui.clone_tree()` | funkcja klonująca całe drzewo węzłów | + +## `manuals/gui-spine.md` + +Zakres: najważniejsze terminy związane z węzłami GUI Spine i przekierowaniem do `/extension-spine`. + +| English term | Polish translation / explanation | +|---|---| +| GUI | interfejs użytkownika Defold | +| GUI scene | scena GUI; dokument lub układ zawierający węzły GUI | +| Spine | `Spine`, narzędzie do animacji szkieletowej 2D | +| Spine node | węzeł Spine; węzeł GUI odtwarzający animację szkieletową | +| bone animated | animowany kośćmi; oparty na szkielecie i jego kościach | +| bone animation | animacja szkieletowa; animacja sterowana kośćmi | +| `This manual has moved` | informacja, że instrukcja została przeniesiona | +| `/extension-spine` | docelowa strona z dokumentacją rozszerzenia Spine | + +## `manuals/gui-template.md` + +Ten słowniczek obejmuje tylko najważniejsze terminy z instrukcji o szablonach GUI. + + +| English term | Polish translation / explanation | +|---|---| +| GUI template | szablon GUI, czyli scena GUI używana jako wzorzec do tworzenia instancji | +| template nodes | węzły szablonu; węzły należące do sceny-szablonu, z których tworzy się instancje | +| template instance | instancja szablonu; utworzona kopia szablonu w innej scenie GUI | +| node | węzeł GUI | +| node tree | drzewo węzłów | +| Outline | `Outline`, widok zawartości sceny w edytorze | +| Nodes | `Nodes`, sekcja w `Outline` zawierająca węzły | +| Template | `Template`, właściwość wskazująca plik sceny GUI szablonu | +| Id | `Id`, identyfikator węzła lub instancji szablonu używany jako prefiks nazw | +| gui.get_node() | `gui.get_node()`, funkcja pobierająca węzeł po nazwie | +| gui.pick_node() | `gui.pick_node()`, funkcja sprawdzająca, czy punkt trafia w węzeł | + +## `manuals/gui-text.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu i zachowuje literalne identyfikatory Defold oraz API po angielsku. + +| English term | Polish translation / explanation | +|---|---| +| GUI text node | węzeł tekstowy GUI | +| GUI | interfejs użytkownika Defold | +| font | font; zasób używany do renderowania tekstu | +| Fonts | folder `Fonts` w komponencie GUI | +| Font | właściwość wskazująca font dla węzła tekstowego | +| Text | właściwość przechowująca wyświetlany tekst | +| Line Break | właściwość włączająca zawijanie tekstu do kilku linii | +| pivot / pivot setting | punkt obrotu węzła; w widoku edytora angielska nazwa może pozostać bez tłumaczenia | +| alignment mode | tryb wyrównywania tekstu; w widoku edytora angielska nazwa może pozostać bez tłumaczenia | +| Center | wyrównanie do środka | +| Left | wyrównanie do lewej | +| Right | wyrównanie do prawej | +| North | pozycja punktu obrotu traktowana jak wyrównanie do środka | +| South | pozycja punktu obrotu traktowana jak wyrównanie do środka | +| West | pozycja punktu obrotu traktowana jak wyrównanie do lewej | +| East | pozycja punktu obrotu traktowana jak wyrównanie do prawej | +| gui.set_font() | funkcja zmiany fontu węzła tekstowego | +| gui.set_line_break() | funkcja zmiany sposobu zawijania tekstu | +| gui.set_text() | funkcja zmiany treści węzła tekstowego | + +## `manuals/gui.md` + +Ten glosariusz obejmuje najważniejsze pojęcia i nazwy użyte w instrukcji GUI. + +| English term | Polish translation / explanation | +|---|---| +| GUI | graficzny interfejs użytkownika; w Defold komponent do budowy UI | +| GUI component | komponent GUI przypięty do obiektu gry | +| GUI scene | scena GUI, czyli plik prototypu komponentu GUI | +| GUI script | skrypt GUI | +| Outline | `Outline`, widok zawartości sceny i jej zależności | +| Properties | `Properties`, właściwości komponentu lub węzła | +| Script | skrypt GUI przypisany do komponentu | +| Material | materiał używany do renderowania GUI lub węzła | +| Adjust Reference | ustawienie sterujące sposobem liczenia `Adjust Mode` | +| Current Nodes | bieżąca liczba używanych węzłów | +| Max Nodes | maksymalna liczba węzłów w GUI | +| Max Dynamic Textures | maksymalna liczba tekstur tworzonych w locie | +| Box node | węzeł prostokątny z kolorem, teksturą albo animacją | +| Text node | węzeł wyświetlający tekst | +| Pie node | węzeł kołowy lub eliptyczny, częściowo wypełniany | +| Template node | węzeł oparty na innej scenie GUI | +| ParticleFX node | węzeł odtwarzający efekt cząsteczkowy | +| Id | unikalny identyfikator węzła | +| Size Mode | tryb rozmiaru, np. `Automatic` lub `Manual` | +| Enabled | stan aktywności węzła; wpływa też na `gui.pick_node()` | +| Visible | widoczność węzła bez wyłączania jego logiki | +| Texture | tekstura przypisana do węzła | +| Font | font używany przez węzeł tekstowy | +| Line Break | zawijanie tekstu do szerokości węzła | +| Slice 9 | skalowanie 9-slice bez rozciągania rogów | +| Inner Radius | wewnętrzny promień węzła `Pie` | +| Pivot | punkt obrotu i skalowania węzła | +| X Anchor / Y Anchor | kotwiczenie pozycji względem krawędzi sceny lub rodzica | +| Adjust Mode | sposób dopasowania węzła do rozmiaru ekranu | +| Fit | dopasowanie sceny lub węzła do ekranu | +| Zoom | skalowanie tak, by wypełnić obszar | +| Stretch | rozciągnięcie zawartości do obszaru | +| Clipping Mode | tryb przycinania węzła | +| Stencil | maska używana do przycinania dzieci węzła | +| Blend mode | tryb mieszania grafiki z tłem | +| child | węzeł-dziecko; jeśli odnosi się do hierarchii w edytorze, angielska forma może pozostać bez tłumaczenia | +| parent | węzeł-rodzic; jeśli odnosi się do hierarchii w edytorze, angielska forma może pozostać bez tłumaczenia | +| layers | warstwy; w edytorze angielska etykieta może pozostać bez tłumaczenia | +| draw calls | wywołania rysowania | +| rendering pipeline | potok renderowania | +| `go.get()` | odczyt właściwości komponentu GUI w runtime | +| `go.set()` | ustawianie właściwości komponentu GUI w runtime | +| `gui.new_texture()` | tworzenie dynamicznej tekstury GUI | +| `gui.pick_node()` | sprawdzanie trafienia węzła przez input | +| `gui.set_enabled()` | włącza lub wyłącza węzeł | +| `gui.is_enabled()` | sprawdza, czy węzeł jest aktywny | +| `gui.set_visible()` | ustawia widoczność węzła | +| `gui.get_visible()` | odczytuje widoczność węzła | + +## `manuals/importing-assets.md` + +This glossary covers the most relevant terms from the importing assets manual and keeps literal Defold, UI, API, file, and tool names in English. + +| English term | Polish translation / explanation | +|---|---| +| asset / assets | zasób / zasoby; plik lub materiał używany w projekcie Defold | +| external assets | zasoby zewnętrzne tworzone poza Defold, a potem importowane do projektu | +| project hierarchy | hierarchia projektu; struktura plików w projekcie Defold | +| `Assets pane` | `Assets pane`, panel edytora, do którego importuje się pliki | +| PNG | `PNG`, format obrazu obsługiwany przez Defold | +| JPEG | `JPEG`, format obrazu obsługiwany przez Defold | +| RGBA | `RGBA`, 32-bitowy tryb koloru wymagany dla obrazów PNG | +| `Sound component` | `Sound component`, komponent odtwarzający dźwięk | +| `Label component` | `Label component`, komponent wyświetlający tekst | +| `text nodes` | węzły tekstowe w GUI | +| `Model component` | `Model component`, komponent wyświetlający modele 3D | +| `Editor Scripts` | `Editor Scripts`, skrypty uruchamiane w edytorze do generowania lub modyfikowania zasobów | +| `Tiled` | `Tiled`, zewnętrzne narzędzie do tworzenia map kafelków i innych zasobów | +| `Tilesetter` | `Tilesetter`, zewnętrzne narzędzie do generowania zasobów Defold | + +## `manuals/importing-graphics.md` + +This glossary covers the most relevant terms from the importing 2D graphics manual and keeps literal Defold/API identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| 2D graphics | grafika 2D | +| import | importowanie plików graficznych do projektu | +| Assets pane | `Assets pane`, panel zasobów w edytorze Defold | +| PNG | PNG, obsługiwany format obrazu | +| JPEG | JPEG, obsługiwany format obrazu | +| Atlas | atlas, zasób łączący wiele obrazów w jedną teksturę | +| Tile Source | źródło kafelków, zasób oparty na siatce małych obrazów | +| tile | kafelek; pojedynczy element źródła kafelków | +| sprite sheet | sprite sheet, obraz źródłowy podzielony na regularną siatkę kafelków | +| Animation Groups | `Animation Groups`, grupy obrazów tworzące animację poklatkową | +| Bitmap Font | font bitmapowy, czcionka zapisana jako obraz PNG | +| glyph | glif, pojedynczy znak fontu | +| flipbook animation | animacja poklatkowa | +| sprite | sprite / obraz wyświetlany na ekranie | +| Tile map | mapa kafelków | +| particles | cząstki | +| particle emitter | emiter cząsteczek | +| particle fx | efekt cząsteczkowy | +| GUI | GUI, interfejs użytkownika w Defold | +| box nodes | `box nodes`, prostokątne węzły GUI; angielska nazwa może pozostać bez tłumaczenia | +| pie nodes | `pie nodes`, kołowe węzły GUI; angielska nazwa może pozostać bez tłumaczenia | +| bone | kość szkieletu | + +## `manuals/importing-models.md` + +Zakres: najważniejsze terminy z instrukcji importowania modeli 3D do Defold. + +| English term | Polish translation / explanation | +|---|---| +| glTF | format wymiany modeli 3D używany przez Defold | +| Collada | format 3D obsługiwany przez Defold, m.in. w plikach `.dae` | +| vertices | wierzchołki siatki modelu 3D | +| faces | ściany lub powierzchnie siatki modelu 3D | +| polygons | wielokąty siatki modelu 3D | +| Assets Pane | panel `Assets` w edytorze Defold | +| Model component | komponent `Model`, który wyświetla model 3D | +| texture image | obraz tekstury używany do pokrycia siatki modelu | +| UV coordinates | współrzędne UV, czyli mapowanie fragmentu tekstury na siatkę | +| UV mapping | mapowanie UV | +| baked animations | animacje wypiekane, przygotowane do odtwarzania bez dodatkowego przeliczania | +| animation clips | klipy animacji | +| keyframe | klatka kluczowa | +| skeleton | szkielet modelu, czyli układ kości do animacji | +| bones | kości szkieletu | +| mesh | siatka modelu 3D | +| unwrap | rozwinięcie siatki; rozwiń siatkę | +| layout | rozkład UV | +| embedded textures | osadzone tekstury zapisane wewnątrz pliku | +| Selection Only | opcja `Selection Only` w Blenderze; angielska forma może pozostać bez tłumaczenia | + +## `manuals/input-gamepads.md` + +This glossary covers the most relevant terms from the gamepad input manual and keeps literal Defold, UI, API, and file names in English. + +| English term | Polish translation / explanation | +|---|---| +| gamepad | gamepad; kontroler wejścia używany do sterowania grą | +| gamepad input | wejście z gamepada | +| gamepad trigger | wyzwalacz gamepada, czyli przypisanie akcji wejściowej do sygnału z kontrolera | +| gamepad input bindings | przypisania wejścia od gamepada; angielska forma może pozostać bez tłumaczenia | +| input binding | wiązanie wejścia; przypisanie sygnału z urządzenia do akcji | +| action | akcja wejściowa obsługiwana w `on_input()` | +| digital button | przycisk cyfrowy; generuje zdarzenia `pressed`, `released` i `repeated` | +| analog stick | analogowa gałka; wysyła wartości ciągłe po wyjściu poza `dead zone` | +| dead zone | martwa strefa; zakres ruchu ignorowany przez sterowanie analogowe | +| cardinal directions | kierunki kardynalne | +| `gamepad` field | pole `gamepad` w tabeli akcji; numer kontrolera, z którego pochodzi wejście | +| `Connected` | `Connected`; sygnał wykrycia podłączenia gamepada; angielska forma może pozostać bez tłumaczenia | +| `Disconnected` | `Disconnected`; sygnał wykrycia odłączenia gamepada; angielska forma może pozostać bez tłumaczenia | +| `Raw` | `Raw`; nieprzefiltrowane dane przycisków, osi i `hat`; angielska forma może pozostać bez tłumaczenia | +| `gamepads` file | plik `gamepads` z mapowaniami kontrolerów; angielska forma może pozostać bez tłumaczenia | +| `game.project` | plik ustawień projektu, w którym wskazuje się konfigurację gamepadów; angielska forma może pozostać bez tłumaczenia | +| `Standard Gamepad` | `Standard Gamepad`; standardowe mapowanie rozpoznawane przez przeglądarkę; angielska forma może pozostać bez tłumaczenia | +| `iframe` | `iframe`; osadzona ramka HTML wymagająca uprawnienia `gamepad`; angielska forma może pozostać bez tłumaczenia | +| `Gamepad API` | `Gamepad API`; interfejs przeglądarkowy dla kontrolerów; angielska forma może pozostać bez tłumaczenia | +| `AKEYCODE_BUTTON_*` | stałe Androida mapujące przyciski na indeksy w pliku `gamepads` | +| `AMOTION_EVENT_AXIS_*` | stałe Androida mapujące osie ruchu na indeksy w pliku `gamepads` | + +## `manuals/input-key-and-text.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu i zachowuje literalne identyfikatory Defold oraz API po angielsku. + +| English term | Polish translation / explanation | +|---|---| +| key triggers | wyzwalacze klawiszy; mapują pojedyncze klawisze na akcje gry; angielska forma może pozostać bez tłumaczenia | +| text triggers | wyzwalacze tekstowe; służą do odczytu wprowadzanego tekstu; angielska forma może pozostać bez tłumaczenia | +| text | `text`; standardowy tekst wpisywany z klawiatury; angielska forma może pozostać bez tłumaczenia | +| marked text | `marked-text`; tymczasowa sekwencja znaków wyświetlana podczas wprowadzania, np. na klawiaturach azjatyckich; angielska forma może pozostać bez tłumaczenia | +| action | akcja wejścia otrzymywana w `on_input()` | +| action_id | identyfikator akcji, np. `hash("left")` | +| action.pressed | pole oznaczające naciśnięcie klawisza | +| action.released | pole oznaczające zwolnienie klawisza | +| action.repeated | pole oznaczające powtórzone zdarzenie klawisza | +| action.text | pole z wpisanym znakiem lub sekwencją tekstu | +| input binding list | lista przypisań wejścia | +| `on_input()` | funkcja skryptowa odbierająca wejście | +| `gui.get_node()` | funkcja pobierająca węzeł GUI | +| `gui.get_text()` | funkcja odczytująca tekst z węzła GUI | +| `gui.set_text()` | funkcja ustawiająca tekst w węźle GUI | +| `hash("left")` | hashed identyfikator akcji dla przykładowego kierunku w lewo | + +## `manuals/input-mouse-and-touch.md` + +Ten glosariusz obejmuje najważniejsze pojęcia użyte w instrukcji o obsłudze myszy, dotyku i wskazywania. + +| English term | Polish translation / explanation | +|---|---| +| Mouse trigger | wyzwalacz myszy, czyli przypisanie akcji do przycisku lub kółka myszy | +| Mouse button | przycisk myszy | +| Mouse wheel | kółko myszy; przewijanie jest traktowane jak akcja wejścia | +| Mouse movement | ruch myszy; zdarzenie bez `action_id`, z danymi w `action` | +| Touch trigger | wyzwalacz dotyku | +| Single-touch | pojedynczy dotyk; automatycznie mapowany z `MOUSE_BUTTON_LEFT` lub `MOUSE_BUTTON_1` | +| multitouch | wielodotyk; wiele punktów dotyku w tabeli `action.touch`; angielska forma może pozostać bez tłumaczenia | +| Input bindings | wiązania wejść, czyli przypisania akcji do źródeł wejścia | +| `action_id` | identyfikator akcji wejścia; dla ruchu myszy zwykle `nil` | +| `action` table | tabela `action` z danymi o wejściu, np. `pressed`, `released`, `value`, `x`, `y` | +| `gui.pick_node()` | funkcja sprawdzająca, czy punkt leży w granicach węzła GUI | +| GUI node | węzeł GUI | +| Collision object | obiekt kolizji; w tym artykule używany do wykrywania kliknięć lub dotknięć | +| Screen space | przestrzeń ekranu, z której trzeba przeliczyć współrzędne | +| World space | przestrzeń świata, do której przelicza się pozycję obiektu gry | +| Camera | kamera; może dostarczać konwersję screen-to-world | +| Render script | skrypt do renderowania; jego projekcja wpływa na przeliczenia współrzędnych | + +## `manuals/input.md` + +This glossary covers the most relevant terms from the input manual and keeps literal Defold/API identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| input | wejście; dane wejściowe od użytkownika lub urządzenia | +| input bindings | wiązania wejść; tabela mapująca surowe wejście na nazwane akcje | +| input bindings table | tabela wiązań wejścia; przy cytowaniu terminu angielska forma może pozostać bez tłumaczenia | +| action | akcja wejściowa z danymi o zdarzeniu, np. wciśnięciu, pozycji lub ruchu | +| input focus | skupienie wejścia; stan, w którym komponent może odbierać wejście | +| acquiring input focus | zdobywanie skupienia wejścia; termin angielski może pozostać bez tłumaczenia przy cytowaniu instrukcji | +| listener | słuchacz wejścia, czyli komponent odbierający akcje wejściowe | +| input stack | stos wejścia; kolejność słuchaczy, według której silnik rozsyła akcje | +| `on_input()` | funkcja wywoływana dla każdej akcji wejściowej | +| `acquire_input_focus` | wiadomość prosząca o przejęcie skupienia wejścia | +| `release_input_focus` | wiadomość zwalniająca skupienie wejścia | +| `game.input_binding` | domyślny plik wiązań wejścia w projekcie | +| `game.project` | plik ustawień projektu, w którym wybiera się `Game Binding` i inne opcje wejścia | +| `Game Binding` | ustawienie wskazujące aktywny plik `input binding` | +| `GUI script` | skrypt GUI; może odbierać akcje wejściowe tak jak zwykły skrypt | +| script component | komponent skryptu; komponent z funkcją `on_input()` | +| collection proxy | pełnomocnik kolekcji; może mieć własny stos wejścia dla ładowanego świata | +| trigger / triggers | typ wyzwalacza wejścia, np. klawiatura, mysz, dotyk lub gamepad | +| key trigger | wyzwalacz klawiatury dla pojedynczego klawisza | +| text trigger | wyzwalacz tekstu do odczytu wprowadzanego tekstu | +| mouse trigger | wyzwalacz myszy dla przycisków i kółka przewijania | +| touch trigger | wyzwalacz dotyku dla jednego lub wielu punktów dotyku | +| gamepad trigger | wyzwalacz gamepada dla standardowych kontrolerów | +| accelerometer input | wejście z akcelerometru; dane z `acc_x`, `acc_y` i `acc_z` | +| consume input | skonsumować wejście; zatrzymać propagację akcji dalej w stosie | +| `pressed` | pole akcji oznaczające wciśnięcie przycisku | +| `action_id` | haszowana nazwa akcji | +| `action.x`, `action.y` | współrzędne akcji, zwykle dla myszy lub dotyku | + +## `manuals/install.md` + +Zakres: najistotniejsze terminy użyte w artykule o instalacji edytora Defold. + +| English term | Polish translation / explanation | +|---|---| +| installation | instalacja | +| Defold editor | edytor Defold | +| download | pobrać; pobieranie wersji dla danego systemu | +| operating system | system operacyjny | +| extract | wypakować archiwum | +| copy | skopiować pliki do wybranej lokalizacji | +| version built for your operating system | wersja skompilowana dla Twojego systemu operacyjnego | +| suitable location | odpowiednia lokalizacja do zainstalowania plików | + +## `manuals/introduction.md` + +Zakres: najważniejsze pojęcia z artykułu wprowadzającego do Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| `Defold` | Defold; silnik i środowisko do tworzenia gier | +| turn-key solution | gotowe rozwiązanie do tworzenia, budowania i wydawania gier | +| `Product Overview` | przegląd funkcji i możliwości produktu | +| `editor` | edytor; wizualne środowisko pracy z projektami Defold | +| tutorials | tutoriale; instrukcje krok po kroku do nauki przez praktykę | +| manuals | instrukcje / podręczniki; dokumentacja opisująca funkcje i workflow | +| API documentation | dokumentacja API; opis funkcji, klas i symboli programistycznych | +| forum | forum społeczności Defold | +| `Lua` | Lua; język używany do logiki gry | +| `C++` | C++; język, w którym napisany jest silnik | +| building blocks | podstawowe elementy budowy gry; proste części składowe projektu | +| `IDE` | zintegrowane środowisko programistyczne | +| 3D modelling programs | programy do modelowania 3D | + +## `manuals/label.md` + +Poniższy słowniczek obejmuje najważniejsze terminy z instrukcji o komponentach `Label`. + +| English term | Polish translation / explanation | +| --- | --- | +| Label | etykieta; komponent renderujący tekst w przestrzeni gry, a jako nazwa komponentu w edytorze angielska forma może pozostać bez tłumaczenia | +| component | komponent | +| game object | obiekt gry | +| text | tekst | +| font | font; zasób czcionki używany przez `Label` | +| material | materiał renderowania | +| size | rozmiar pola tekstu | +| color | kolor | +| outline | obrys | +| shadow | cień | +| leading | interlinia | +| tracking | odstęp między literami | +| pivot | punkt zakotwiczenia tekstu | +| alignment | wyrównanie | +| line break | łamanie linii | +| blend mode | tryb mieszania | +| `Assets` | `Assets`; widok zasobów w edytorze, angielska nazwa może pozostać bez tłumaczenia | +| `Add Component ▸ Label` | `Add Component ▸ Label`; polecenie dodania komponentu etykiety, angielska nazwa menu może pozostać bez tłumaczenia | +| `New... ▸ Label` | `New... ▸ Label`; polecenie utworzenia nowego pliku komponentu etykiety, angielska nazwa menu może pozostać bez tłumaczenia | +| `label.set_text()` | `label.set_text()`; ustawia tekst etykiety w czasie działania | +| `go.set()` | `go.set()`; ustawia właściwości komponentu | +| `vector4` | `vector4`; wektor czteroskładnikowy, np. dla koloru RGBA | +| `vector3` | `vector3`; wektor trójskładnikowy, np. dla skali lub rozmiaru | + +## `manuals/libraries.md` + +Krótki słownik najważniejszych pojęć z instrukcji o bibliotekach. + +| English term | Polish translation / explanation | +|---|---| +| Libraries | biblioteki, czyli sposób udostępniania zasobów między projektami | +| library project | projekt biblioteki, z którego można pobierać współdzielone zasoby | +| asset | zasób | +| shared folder | udostępniony folder z plikami widocznymi dla innych projektów | +| `include_dirs` | klucz w `game.project`, który wskazuje foldery przeznaczone do udostępniania | +| `dependencies` | klucz w `game.project`, w którym podaje się adresy bibliotek | +| Library URL | adres biblioteki używany do wskazania konkretnego projektu lub wydania | +| release | konkretne wydanie biblioteki, lepsze niż śledzenie gałęzi `master` | +| `Project ▸ Fetch Libraries` | polecenie w edytorze do odświeżenia zależności bibliotek | +| Assets pane | panel `Assets`, w którym pojawiają się udostępnione foldery | +| `builtins` | wbudowana biblioteka silnika Defold | +| name collision | kolizja nazw, gdy kilka bibliotek ma folder o tej samej nazwie | + +## `manuals/live-update.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o Live update i pozostawia literalne nazwy API, plików oraz ustawień w języku angielskim. + +| English term | Polish translation / explanation | +|---|---| +| Live update | aktualizacja na żywo; mechanizm pobierania i zapisywania zasobów po zbudowaniu paczki | +| collection proxy | pełnomocnik kolekcji | +| Exclude | opcja wykluczająca zasób z paczki podczas bundlowania | +| bundle | paczka aplikacji tworzona dla konkretnej platformy | +| excluded resources | zasoby pominięte w paczce bazowej i dostarczane później | +| manifest | manifest; plik z metadanymi i zależnościami zasobów | +| `liveupdate.game.dmanifest` | nazwa pliku manifestu używanego przez Live update | +| `bundle.ver` | plik identyfikujący wersję paczki | +| `game.graph.json` | wygenerowany graf zależności zasobów | +| resource graph | graf zasobów opisujący zależności między plikami | +| `resource.store_resource()` | funkcja zapisująca pobrany zasób w pamięci lokalnej | +| `resource.store_manifest()` | funkcja weryfikująca i zapisująca nowy manifest | +| `collectionproxy.missing_resources()` | funkcja zwracająca brakujące zasoby dla pełnomocnika kolekcji | +| `liveupdate.add_mount()` | funkcja montująca archiwum w systemie zasobów silnika | +| mount | zamontowane archiwum dostępne dla silnika z określonym priorytetem | +| archive | archiwum z zasobami, zwykle `.zip` | +| Zip | format archiwum używany do publikacji zasobów Live update | +| Amazon S3 | usługa przechowywania plików używana do hostowania zasobów | +| engine version check | sprawdzenie zgodności wersji silnika z archiwum lub manifestem | +| content verification | weryfikacja, czy zasoby i manifest są zgodne z uruchomionym silnikiem | +| supported engine versions | obsługiwane wersje silnika dopuszczone przez ustawienia Live update | + +## `manuals/lua.md` + +Ten słowniczek obejmuje najważniejsze pojęcia użyte w instrukcji o Lua w Defoldzie. + +| English term | Polish translation / explanation | +| --- | --- | +| LuaJIT | zoptymalizowana implementacja Lua używana przez Defold; zgodna z Lua 5.1 | +| dynamic typing | dynamiczne typowanie, czyli typ ma wartość, a nie zmienna | +| bytecode interpreter | interpreter kodu bajtowego | +| incremental garbage collection | inkrementalne zbieranie śmieci, czyli automatyczne zarządzanie pamięcią | +| standard libraries | standardowe biblioteki Lua | +| scope | zasięg; zakres widoczności zmiennych i nazw | +| coroutines | korutyny; współbieżne przebiegi wykonania sterowane przez `coroutine` | +| Lua runtime context | kontekst uruchomienia Lua; wspólne środowisko wykonywania skryptów | +| garbage collection | gromadzenie śmieci; automatyczne zwalnianie pamięci | +| closure object | obiekt zamknięcia; obiekt tworzony przez deklarację funkcji | +| `nil` | brak wartości; zwykle oznacza nieprzypisaną zmienną | +| `boolean` | typ logiczny z wartościami `true` i `false` | +| `number` | liczba, czyli wartość całkowita albo zmiennoprzecinkowa | +| `string` | niemutowalny ciąg bajtów; tekst w cudzysłowie | +| `function` | funkcja jako wartość pierwszej klasy | +| `table` | podstawowy typ struktury danych w Lua; tabela asocjacyjna | +| `userdata` | obiekt do przechowywania danych C w Lua | +| `thread` | wątek wykonania używany do implementacji coroutine | +| `if --- then --- else` | instrukcja warunkowa z opcjonalnym `else` i `elseif` | +| `for` | pętla numeryczna lub ogólna | +| `break` | przerywa pętlę | +| `return` | zwraca wartość z funkcji | + +## `manuals/mesh.md` + +Zakres: najważniejsze pojęcia z instrukcji o komponencie Mesh. + +| English term | Polish translation / explanation | +| --- | --- | +| Mesh component | komponent Mesh; komponent do renderowania siatki 3D | +| Mesh file | plik Mesh; zasób siatki używany przez komponent | +| game object | obiekt gry | +| collection | kolekcja | +| material | materiał; określa sposób renderowania siatki | +| vertices | wierzchołki; dane geometrii przekazywane do siatki | +| primitive type | typ prymitywu; np. `Lines`, `Triangles` lub `Triangle Strip` | +| position stream | strumień pozycji; nazwa strumienia `position` w buforze | +| normal stream | strumień normalnych; nazwa strumienia `normal` w buforze | +| `tex0` | nazwa slotu tekstury używanego przez siatkę | +| buffer | bufor Defold; przechowuje dane geometrii w czasie działania | +| vertex shader | shader wierzchołków; przetwarza dane wierzchołków na GPU | +| `AABB` | axis-aligned bounding box; prostopadłościenne obramowanie do `frustum culling` | +| frustum culling | odrzucanie obiektów spoza bryły widoku | +| `Vertex Space` | ustawienie materiału określające przestrzeń wierzchołków | +| `Local Space` | przestrzeń lokalna; dane trafiają do shadera bez przekształcenia | +| `World Space` | przestrzeń świata; silnik przekształca dane do układu świata | + +## `manuals/message-passing.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o przekazywaniu wiadomości i zachowuje literalne nazwy API, identyfikatory oraz nazwy wiadomości w języku angielskim. + +| English term | Polish translation / explanation | +| --- | --- | +| message passing | przekazywanie wiadomości | +| message | wiadomość | +| `msg.post()` | funkcja wysyłająca wiadomość do kolejki | +| `on_message()` | funkcja odbierająca i obsługująca wiadomości | +| `message_id` | identyfikator wiadomości, zwykle hash nazwy | +| `sender` | nadawca wiadomości, pełny URL źródła | +| `receiver` | odbiorca wiadomości, adres komponentu lub obiektu gry | +| game object / game objects | obiekt gry; w liczbie mnogiej także `game objects` | +| component | komponent | +| script | skrypt; ogólna nazwa kodu wykonywanego w Defoldzie | +| script component | komponent skryptowy | +| GUI script | skrypt GUI | +| render script | skrypt do renderowania | +| collection proxy | pełnomocnik kolekcji | +| game world | świat gry | +| collection hierarchy | hierarchia kolekcji | +| relative addressing | adresowanie względne | +| absolute address | adres bezwzględny | +| `socket` | pole URL wskazujące świat gry | +| `punch` | wiadomość o ciosie; w tym przykładzie sama nazwa wystarcza | +| `update_score` | wiadomość aktualizująca licznik punktów | +| `update_minimap` | wiadomość aktualizująca pozycję na minimapie | +| `enable` / `disable` / `set_parent` | przykładowe wiadomości systemowe obsługiwane przez silnik | +| `collision_response` | wiadomość systemowa wysyłana przy kolizji | +| `wake_up` | wiadomość budząca obiekt w nowym świecie gry | +| `main:/my_object#script` | przykład pełnego URL nadawcy | + +## `manuals/model-animation.md` + +To zestawienie obejmuje tylko kluczowe terminy z instrukcji o animacji modeli 3D. + +| English term | Polish translation / explanation | +| --- | --- | +| 3D model | model 3D | +| skeletal animation | animacja szkieletowa | +| bones | kości, czyli elementy szkieletu modelu | +| vertices | wierzchołki siatki modelu | +| baked animations | animacje wypieczone; dane przygotowane wcześniej przez eksportera | +| Model component | komponent `Model` | +| `model.play_anim()` | funkcja do uruchamiania animacji modelu | +| `model.get_go()` | funkcja zwracająca `game object` powiązany z kością | +| cursor | kursor animacji, czyli wartość postępu od `0` do `1` | +| `go.animate()` | funkcja do animowania właściwości, także kursora | +| `go.cancel_animations()` | funkcja anulująca animacje | +| Playback mode | tryb odtwarzania animacji | +| `go.PLAYBACK_LOOP_PINGPONG` | tryb zapętlenia naprzemiennego przód-tył | +| callback | funkcja zwrotna wywoływana po zakończeniu animacji | + +## `manuals/model.md` + +This glossary covers the most relevant terms from the model manual and keeps literal Defold, API, file, and menu identifiers in English. + +| English term | Polish translation / explanation | +|---|---| +| `Model component` | komponent Model; komponent obiektu gry służący do wyświetlania modelu 3D | +| `glTF` | format plików 3D używany do modeli, siatek, szkieletów i animacji | +| `Mesh` | siatka 3D; geometria modelu w pliku `gltf` | +| `Skeleton` | szkielet; hierarchia kości używana do animacji | +| `Animation Set File` | plik zestawu animacji; zawiera animacje używane przez model | +| `Default Animation` | domyślna animacja odtwarzana automatycznie po uruchomieniu | +| `Material` | materiał renderujący model; łączy shadery z parametrami | +| `Texture` | tekstura nakładana na model | +| `model.play_anim()` | funkcja API do uruchamiania animacji modelu | +| `go.get()` / `go.set()` | funkcje do odczytu i zmiany właściwości modelu w czasie działania | +| `cursor` | znormalizowany kursor animacji | +| `playback_rate` | prędkość odtwarzania animacji | +| `model.material` | wbudowany materiał dla statycznych modeli bez instancji | +| `model_skinned.material` | wbudowany materiał dla animowanych modeli ze szkieletem | +| `render.predicate()` | funkcja tworząca predykat renderowania dla modeli | +| `render.STATE_DEPTH_TEST` | tryb testu głębi potrzebny do renderowania 3D | + +## `manuals/modules.md` + +Ten glosariusz obejmuje tylko kluczowe terminy potrzebne do zrozumienia artykułu o modułach Lua. + +| English term | Polish translation / explanation | +|---|---| +| module | moduł; zwykła tabela Lua używana do grupowania funkcji i danych | +| `require` | `require`; nazwa funkcji API pozostaje po angielsku; wczytuje moduł i zwraca jego wartość | +| `package.loaded` | `package.loaded`; tabela z pamięcią podręczną już załadowanych modułów | +| loader | ładowacz; mechanizm używany do wczytywania i wykonywania pliku modułu | +| hot reloading | szybkie przeładowanie; ponowne wczytanie kodu podczas pracy bez restartu programu | +| stateful module | moduł ze stanem; przechowuje wspólny stan wewnętrzny dla wszystkich użytkowników | +| stateless module | moduł bezstanowy; nie trzyma stanu wewnętrznego, a dane przekazuje na zewnątrz | +| constructor function | funkcja konstruktora; tworzy nową instancję lub tabelę stanu | +| metatables | metatabele; tabela używana do rozszerzania zachowania innych tabel | +| closure | domknięcie; funkcja zachowująca dostęp do zmiennych z otaczającego zakresu | +| local scope | zakres lokalny; widoczność ograniczona do bieżącego bloku lub pliku | +| global scope | zakres globalny; widoczność współdzielona w całym programie | + +## `manuals/particlefx.md` + +Ten słowniczek obejmuje najważniejsze terminy używane w instrukcji o efektach cząsteczkowych i w powiązanym edytorze. + +| English term | Polish translation / explanation | +|---|---| +| particle effects | efekty cząsteczkowe; w edytorze może pojawić się też nazwa `Particle FX` | +| Emitter | emiter; nazwa w edytorze może pozostać po angielsku i oznacza źródło emitujące cząsteczki z określonego kształtu | +| Modifier | modyfikator; nazwa w edytorze może pozostać po angielsku i zmienia prędkość lub ruch cząsteczek | +| Outline | widok drzewa zasobu w edytorze; nazwa panelu może pozostać po angielsku i pokazuje emitery oraz modyfikatory | +| Properties | panel właściwości; nazwa panelu może pozostać po angielsku i służy do edycji ustawień zaznaczonego elementu | +| Curve Editor | edytor krzywych; nazwa widoku może pozostać po angielsku i służy do animowania właściwości w czasie | +| Spawn Rate | liczba cząsteczek emitowanych na sekundę | +| Particle Life Time | czas życia cząsteczki w sekundach | +| Initial Speed | początkowa prędkość cząsteczki | +| Life Scale | skala cząsteczki zmieniająca się w trakcie jej życia | +| `particlefx.play()` | funkcja API uruchamiająca efekt cząsteczkowy | +| `particlefx.stop()` | funkcja API zatrzymująca efekt cząsteczkowy | +| `particlefx.set_constant()` | ustawia stałą materiału, np. `tint` | +| `game.project` | plik konfiguracji projektu; zawiera ustawienia związane z Particle FX | + +## `manuals/physics-groups.md` + +Ten glosariusz obejmuje kluczowe terminy z instrukcji o grupach i maskach kolizji w silniku fizyki Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| physics engine | silnik fizyki | +| physics object | obiekt fizyczny | +| collision object | obiekt kolizji | +| properties | właściwości | +| collision group | grupa kolizji, używana do filtrowania interakcji | +| Group | `Group`, czyli grupa przypisana do obiektu kolizji; nazwa pola w edytorze może pozostać po angielsku | +| Mask | `Mask`, czyli lista grup, z którymi obiekt może kolidować; nazwa pola w edytorze może pozostać po angielsku | +| collision | kolizja, zderzenie dwóch obiektów | +| collision messages | wiadomości o kolizji generowane przez silnik | +| detect collisions | wykrywać kolizje | + +## `manuals/physics-joints.md` + +Zakres: najważniejsze terminy z instrukcji o łączeniach fizycznych w 2D. + +| English term | Polish translation / explanation | +|---|---| +| joints | łączenia; w pierwszym użyciu warto podać też angielskie `joints` | +| joint | łączenie fizyczne łączące dwa obiekty kolizji | +| collision object | obiekt kolizji | +| constraint | ograniczenie narzucone na ruch obiektów | +| Fixed (`physics.JOINT_TYPE_FIXED`) | połączenie linowe; ogranicza maksymalną odległość między punktami | +| Hinge (`physics.JOINT_TYPE_HINGE`) | połączenie zawiasowe/obrotowe; pozwala na obrót wokół punktu kotwiczenia | +| Weld (`physics.JOINT_TYPE_WELD`) | połączenie spawane; blokuje względny ruch obiektów | +| Spring (`physics.JOINT_TYPE_SPRING`) | połączenie sprężynowe/dystansowe; utrzymuje stałą odległość | +| Slider (`physics.JOINT_TYPE_SLIDER`) | połączenie przesuwne/pryzmatyczne; pozwala na ruch wzdłuż osi | +| rope joint | połączenie linowe; w Box2D odpowiada typowi `Fixed` | +| motor | silnik połączenia; jeśli chodzi o literalny element fizyki, angielska forma może pozostać bez tłumaczenia | +| revolute joint | połączenie obrotowe | +| weld joint | połączenie spawane | +| distance joint | połączenie dystansowe | +| prismatic joint | połączenie pryzmatyczne | +| `physics.create_joint()` | funkcja tworząca połączenie programowo | +| `physics.destroy_joint()` | funkcja usuwająca połączenie | +| `physics.get_joint_properties()` | funkcja odczytu właściwości połączenia | +| `physics.set_joint_properties()` | funkcja ustawiania właściwości połączenia | +| `physics.get_joint_reaction_force()` | odczyt siły reakcji działającej na połączenie | +| `physics.get_joint_reaction_torque()` | odczyt momentu reakcji działającego na połączenie | + +## `manuals/physics-messages.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o wiadomościach kolizji i zachowuje literalne nazwy wiadomości, pól oraz API w języku angielskim. + +| English term | Polish translation / explanation | +| --- | --- | +| collision messages | wiadomości kolizji | +| event callback | funkcja zwrotna wywoływana przy zdarzeniu | +| default message handler | domyślny handler wiadomości | +| event filtering | filtrowanie zdarzeń | +| Generate Collision Events | `Generate Collision Events`, czyli przełącznik generowania wiadomości o kolizji | +| Generate Contact Events | `Generate Contact Events`, czyli przełącznik generowania wiadomości o punkcie kontaktu | +| Generate Trigger Events | `Generate Trigger Events`, czyli przełącznik generowania wiadomości wyzwalacza | +| collision object | obiekt kolizji | +| dynamic | dynamiczny obiekt fizyczny | +| kinematic | kinematyczny obiekt fizyczny | +| static | statyczny obiekt fizyczny | +| trigger | wyzwalacz, obiekt wykrywający wejście i wyjście | +| `collision_response` | wiadomość o ogólnym zderzeniu | +| `contact_point_response` | wiadomość o punkcie kontaktu, z danymi do precyzyjnego rozdzielania obiektów | +| `trigger_response` | wiadomość o wejściu do wyzwalacza i wyjściu z niego | +| contact point | punkt kontaktu | +| normal | wektor normalny punktu kontaktu | +| relative velocity | prędkość względna | +| penetration distance | odległość penetracji między obiektami | +| applied impulse | zastosowany impuls | +| `other_id` | identyfikator drugiej instancji | +| `other_position` | pozycja drugiej instancji w przestrzeni świata | +| `other_group` | grupa kolizyjna drugiego obiektu | +| `own_group` | własna grupa kolizyjna obiektu | + +## `manuals/physics-objects.md` + +Ten glosariusz obejmuje najważniejsze terminy z instrukcji o obiektach kolizji w silniku fizyki Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| collision object | obiekt kolizji | +| spatial extension | zasięg przestrzenny obiektu; termin opisuje rozmiar/obszar zajmowany przez komponent | +| shapes | kształty dołączane do obiektu kolizji | +| physics object | obiekt fizyczny | +| Static objects | obiekty statyczne, które się nie poruszają | +| Dynamic objects | obiekty dynamiczne symulowane przez silnik fizyki | +| Kinematic objects | obiekty kinematyczne sterowane ręcznie | +| Triggers | wyzwalacze, które tylko rejestrują zdarzenia | +| shape | kształt definiujący zasięg obiektu | +| ray casts | promienie sprawdzające świat fizyczny wzdłuż linii | +| Collision Shape | `Collision Shape`, czyli nazwa właściwości; angielska forma może pozostać bez tłumaczenia | +| Friction | `Friction`, czyli tarcie; nazwa właściwości może pozostać po angielsku | +| Restitution | `Restitution`, czyli sprężystość / współczynnik odbicia; nazwa właściwości może pozostać po angielsku | +| Linear damping | `Linear damping`, czyli tłumienie liniowe; nazwa właściwości może pozostać po angielsku | +| Angular damping | `Angular damping`, czyli tłumienie kątowe; nazwa właściwości może pozostać po angielsku | +| Locked rotation | `Locked rotation`, czyli zablokowanie obrotu; nazwa właściwości może pozostać po angielsku | +| Bullet | `Bullet`, czyli pocisk; ta właściwość włącza ciągłe wykrywanie kolizji (Continuous Collision Detection, CCD); nazwa właściwości może pozostać po angielsku | +| Group | `Group`, czyli grupa kolizji; nazwa właściwości może pozostać po angielsku | +| Mask | `Mask`, czyli lista grup kolizji do wykrywania; nazwa właściwości może pozostać po angielsku | +| Generate Collision Events | `Generate Collision Events`, czyli generowanie zdarzeń kolizji; nazwa właściwości może pozostać po angielsku | +| Generate Contact Events | `Generate Contact Events`, czyli generowanie zdarzeń kontaktu; nazwa właściwości może pozostać po angielsku | +| Generate Trigger Events | `Generate Trigger Events`, czyli generowanie zdarzeń wyzwalacza; nazwa właściwości może pozostać po angielsku | +| `go.get()` | odczyt właściwości w czasie działania | +| `go.set()` | ustawianie właściwości w czasie działania | +| `angular_velocity` | prędkość kątowa | +| `linear_velocity` | prędkość liniowa | + +## `manuals/physics-ray-casts.md` + +Zakres: najważniejsze terminy z artykułu o odczytywaniu świata fizycznego za pomocą promienia. + +| English term | Polish translation / explanation | +|---|---| +| ray cast | rzut promienia; odczyt świata fizycznego wzdłuż linii | +| ray casts | promienie używane do testowania świata fizycznego | +| physics world | świat fizyczny | +| linear ray | promień liniowy | +| start position | pozycja początkowa promienia | +| end position | pozycja końcowa promienia | +| collision groups | grupy kolizyjne, względem których wykonywany jest test | +| `physics.raycast()` | funkcja wykonująca rzut promienia w świecie fizycznym | +| physics object | obiekt fizyczny | +| dynamic object | dynamiczny obiekt fizyczny | +| kinematic object | kinematyczny obiekt fizyczny | +| static object | statyczny obiekt fizyczny | +| trigger | wyzwalacz; jeśli chodzi o literalną nazwę typu/obiektu w edytorze lub API, angielska forma może pozostać bez tłumaczenia | +| `ray_cast_response` | wiadomość z odpowiedzią na trafienie promieniem | +| hit | trafienie promienia w obiekt | +| Box2D | silnik fizyki 2D używany przez Defold; ograniczenie dotyczy promieni zaczynających się wewnątrz obiektu | + +## `manuals/physics-resolving-collisions.md` + +Ten słowniczek obejmuje tylko najważniejsze terminy z instrukcji o rozwiązywaniu kolizji kinematycznych. + +| English term | Polish translation / explanation | +| --- | --- | +| kinematic collision object | kinematyczny obiekt kolizji; obiekt, którego kolizje rozwiązujesz ręcznie w skrypcie | +| collision object | obiekt kolizji | +| `contact_point_response` | nazwa wiadomości zwrotnej z punktu kontaktu po kolizji | +| penetration distance | odległość penetracji, czyli jak głęboko obiekty na siebie nachodzą | +| penetration vector | wektor penetracji | +| separation | rozdzielenie obiektów po kolizji | +| compensation vector | wektor kompensacji, używany do wyliczenia brakującego przesunięcia | +| correction vector | wektor korekcji, czyli akumulowana poprawka ruchu | +| accumulated correction | akumulowana korekcja z poprzednich punktów kontaktu | +| projection | projekcja jednego wektora na drugi | +| `vmath.project()` | funkcja do obliczania projekcji wektora | +| `vmath.length()` | funkcja zwracająca długość wektora | +| `go.set_position()` | funkcja ustawiająca pozycję obiektu gry | + +## `manuals/physics-shapes.md` + +Ten glosariusz obejmuje najważniejsze terminy z instrukcji o kształtach kolizji w silniku fizyki Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| collision shape | kształt kolizji | +| primitive shapes | kształty podstawowe | +| complex shapes | kształty złożone | +| primitive shape | kształt podstawowy | +| complex shape | kształt złożony | +| box | `box`, czyli kształt prostopadłościanu | +| sphere | `sphere`, czyli kształt sfery | +| capsule | `capsule`, czyli kształt kapsuły | +| tilemap | `tilemap`, czyli mapa kafelków używana jako kształt kolizji | +| convex hull | wypukła otoczka | +| Collision Shape | `Collision Shape`, czyli nazwa właściwości; angielska forma może pozostać bez tłumaczenia | +| `physics.set_shape()` | funkcja do zmiany kształtu kolizji w czasie działania; nazwa API pozostaje po angielsku | +| 3D physics | fizyka 3D | +| 2D physics | fizyka 2D | +| `game.project` | plik konfiguracji projektu | +| `Allow Dynamic Transforms` | `Allow Dynamic Transforms`, czyli opcja dziedziczenia skali przez kształty; nazwa ustawienia pozostaje po angielsku | +| `Group` | `Group`, czyli grupa kolizji zdefiniowana w źródle kafelków; nazwa ustawienia pozostaje po angielsku | +| `Properties` | `Properties`, czyli ustawienia komponentu obiektu kolizji; nazwa panelu pozostaje po angielsku | + +## `manuals/physics.md` + +Ten glosariusz obejmuje najważniejsze terminy z instrukcji o fizyce w silniku Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| physics engine | silnik fizyki | +| Box2D | `Box2D`, silnik fizyki 2D | +| Bullet | `Bullet`, silnik fizyki 3D | +| collision object | obiekt kolizji | +| collision shape | kształt kolizji, który określa zasięg obiektu | +| collision group | grupa kolizji | +| collision messages | wiadomości kolizji | +| constraints | ograniczenia łączące obiekty kolizji | +| joints | łączenia, czyli constraints między dwoma obiektami | +| ray cast | test promieniem w świecie fizyki | +| `fixed_update(self, dt)` | funkcja cyklu życia do pracy z fizyką przy stałym kroku czasowym | +| `game.project` | plik konfiguracji projektu | + +## `manuals/project-settings.md` + +Krótki słownik najważniejszych pojęć z instrukcji o ustawieniach projektu. + +| English term | Polish translation / explanation | +|---|---| +| `game.project` | główny plik ustawień projektu Defold; musi leżeć w katalogu głównym projektu | +| category | kategoria ustawień, według której Defold grupuje pola | +| Project | sekcja z ogólnymi ustawieniami aplikacji, takimi jak tytuł i wydawca | +| Write Log File | ustawienie określające, kiedy silnik zapisuje plik logu | +| `project.log_dir` | ukryte ustawienie wskazujące katalog dla pliku logu | +| Bootstrap | sekcja startowa z ustawieniami uruchamiania aplikacji | +| Main Collection | główna kolekcja uruchamiana na starcie | +| Render | plik render określający potok renderowania | +| Library | sekcja z ustawieniami współdzielenia bibliotek | +| Include Dirs | katalogi udostępniane przez bibliotekę | +| Script | sekcja z ustawieniami skryptów Lua | +| Shared State | współdzielony stan Lua dla wszystkich skryptów | +| Engine | sekcja z ustawieniami pracy silnika | +| Fixed Update Frequency | częstotliwość `fixed_update(self, dt)` w hercach | +| Display | sekcja z ustawieniami okna i odświeżania obrazu | +| Vsync | synchronizacja pionowa sterująca tempem odświeżania | +| Frame Cap | limit liczby klatek; w praktyce powiązany z `display.update_frequency` | +| High Dpi | bufor o podwyższonej rozdzielczości na obsługiwanych ekranach | +| Render script | skrypt do renderowania sterujący sposobem wyświetlania obrazu | +| Physics | sekcja z ustawieniami fizyki | +| Type | wybór między fizyką `2D` i `3D` | +| In App Purchases | nazwa zakupów wewnątrz aplikacji; gdy występuje jako widoczna etykieta, angielska forma może pozostać bez tłumaczenia | + +## `manuals/project-setup.md` + +Zakres: najważniejsze terminy z artykułu o zakładaniu projektu w Defoldzie i pracy z lokalnymi projektami. + +| English term | Polish translation / explanation | +|---|---| +| `New Project` | opcja utworzenia nowego projektu | +| `Create New Project` | przycisk tworzenia nowego projektu | +| `Open From Disk` | opcja otwarcia istniejącego projektu z dysku | +| `Recent Projects` | lista ostatnio otwieranych projektów; jako widoczna etykieta w edytorze angielska forma może pozostać bez tłumaczenia | +| template | szablon projektu | +| tutorial | projekt instruktażowy z krokami do wykonania | +| sample | gotowy przykładowy projekt lub gra | +| local project | projekt lokalny, zapisany tylko na dysku | +| version control system | system kontroli wersji | +| Git | system kontroli wersji używany do śledzenia zmian | +| GitHub | usługa do przechowywania repozytoriów Git | +| repository | repozytorium | +| clone | sklonować projekt lub repozytorium na dysk | + +## `manuals/properties.md` + +Poniższy glosariusz obejmuje najważniejsze terminy z instrukcji o właściwościach w Defold. + +| English term | Polish translation / explanation | +|---|---| +| properties | właściwości obiektów gry, komponentów, węzłów GUI i shaderów | +| game object | obiekt gry | +| component | komponent | +| GUI node | węzeł GUI | +| shader constants | stałe shaderów; wartości przekazywane z materiałów i shaderów | +| `go.get()` | `go.get()`; odczyt właściwości w czasie działania | +| `go.set()` | `go.set()`; ustawianie właściwości w czasie działania | +| `go.animate()` | `go.animate()`; animowanie właściwości | +| `gui.get_color()` | `gui.get_color()`; odczyt koloru węzła GUI | +| `gui.set_color()` | `gui.set_color()`; ustawianie koloru węzła GUI | +| `position` | pozycja lokalna obiektu gry lub węzła | +| `rotation` | rotacja lokalna; dla obiektów gry jako quaternion, dla GUI jako kąty Eulera | +| `scale` | skala lokalna; może być niejednorodna | +| `color` | kolor; zwykle `vector4` z kanałami RGBA | +| `material` | materiał używany przez komponent | +| `cursor` | pozycja kursora odtwarzania, zwykle w zakresie 0-1 | +| `playback_rate` | szybkość odtwarzania animacji | +| `outline` | obrys lub kolor obrysu | +| `shadow` | cień lub kolor cienia | +| `fill_angle` | kąt wypełnienia węzła `Pie` | +| `inner_radius` | promień wewnętrzny węzła `Pie` | + +## `manuals/property-animation.md` + +Ten słowniczek obejmuje tylko kluczowe pojęcia używane w instrukcji o animacji właściwości. + +| English term | Polish translation / explanation | +| --- | --- | +| property animation | animacja właściwości | +| properties | właściwości; w tym artykule chodzi o animowalne właściwości obiektów gry, komponentów, węzłów GUI i stałych shaderów | +| `go.animate()` | funkcja do animowania właściwości obiektów gry i komponentów | +| `gui.animate()` | funkcja do animowania właściwości węzłów GUI | +| `go.cancel_animations()` | anuluje animacje właściwości obiektu gry lub komponentu | +| `gui.cancel_animation()` | anuluje animację właściwości węzła GUI | +| easing | wygładzanie, czyli sposób zmiany wartości w czasie | +| playback mode | tryb odtwarzania animacji | +| tween | płynne dopasowanie wartości między punktem startowym i docelowym | +| GUI node | węzeł GUI | +| game object | obiekt gry | +| component property | właściwość komponentu | +| `go.PLAYBACK_LOOP_PINGPONG` | tryb pętli, w którym animacja odbija się między wartościami | +| `go.EASING_OUTBOUNCE` | stała wygładzania typu „odbicie” | +| `gui.PROP_COLOR` | stała wskazująca właściwość koloru węzła GUI | +| `hash("position.x")` | hashowana nazwa właściwości, używana zamiast tekstu | +| `vmath.vector()` | tworzy wektor używany m.in. do własnych krzywych wygładzania | + +## `manuals/refactoring.md` + +Ten słowniczek obejmuje najważniejsze terminy użyte w instrukcji o refaktoryzacji projektu w Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| Refactoring | refaktoryzacja, czyli reorganizacja istniejącego kodu i zasobów | +| asset | zasób | +| rename | zmienić nazwę; w edytorze zmiana nazw jest uwzględniana automatycznie | +| move | przenieść; w edytorze przenoszenie zasobów aktualizuje odwołania | +| reference | odwołanie do zasobu | +| editor | Defold Editor | +| automatically update references | automatycznie aktualizować odwołania | +| Build Errors | panel błędów budowania w edytorze | +| error signal | sygnał błędu | +| atlas | atlas | +| animation | animacja | +| game | gra | + +## `manuals/resource.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o zarządzaniu zasobami i zostawia literalne nazwy API, plików oraz opcji w języku angielskim. + +| English term | Polish translation / explanation | +| --- | --- | +| resource management | zarządzanie zasobami | +| resource tree | drzewo zasobów, czyli statyczny zestaw wszystkich zasobów dołączanych do gry | +| bootstrap collection | kolekcja startowa uruchamiana jako punkt wejścia gry; w źródle pojawia się też zapis `bootrstrap collection` | +| bootstrap root | korzeń drzewa startowego gry | +| bundle | paczka gry tworzona na potrzeby dystrybucji | +| memory footprint | zużycie pamięci przez grę | +| bundle size | rozmiar paczki gry | +| collection proxy | pełnomocnik kolekcji | +| custom resources | niestandardowe zasoby deklarowane w `game.project` | +| `sys.load_resource()` | funkcja do ręcznego ładowania zasobów z `game.project` | +| factory | fabryka | +| collection factory | fabryka kolekcji | +| factory components | komponenty fabryki | +| `Load Dynamically` | opcja opóźniająca automatyczne ładowanie zasobów fabryki | +| `factory.create()` | synchronizuje ładowanie i tworzy nowe obiekty | +| `factory.load()` | asynchronicznie ładuje zasoby fabryki | +| `factory.unload()` | zwalnia odniesienie fabryki do zasobu | +| `Exclude` | opcja wykluczająca zasób z paczki gry | +| Live update | mechanizm pobierania wykluczonych zasobów w trakcie działania gry | + +## `manuals/script-properties.md` + +Ten słowniczek obejmuje najistotniejsze terminy z instrukcji o właściwościach skryptów i zachowuje literalne nazwy API, identyfikatory oraz etykiety edytora w języku angielskim. + +| English term | Polish translation / explanation | +|---|---| +| script property | właściwość skryptu; niestandardowa wartość przypisana do instancji komponentu skryptu | +| script component | komponent skryptu | +| `go.property()` | funkcja definiująca właściwość skryptu na poziomie najwyższym pliku | +| `self` | odwołanie do instancji skryptu; tu przechowywane są zdefiniowane właściwości | +| `go.get()` | funkcja odczytująca właściwość po adresie lub `url` | +| `go.set()` | funkcja ustawiająca właściwość po adresie lub `url` | +| `go.animate()` | funkcja animująca właściwość | +| `factory.create()` | funkcja tworząca obiekt gry z możliwością przekazania tabeli `properties` | +| `collectionfactory.create()` | funkcja tworząca hierarchię obiektów gry z tabelami właściwości | +| `properties` | tabela Lua z wartościami właściwości przekazywanymi przy tworzeniu | +| `msg.url()` | funkcja budująca `url` wskazujący obiekt lub komponent | +| `hash` | hash; typ używany m.in. dla nazw wiadomości i niektórych właściwości | +| `msg.url` | typ właściwości wskazujący adres komponentu lub obiektu | +| `resource property` | właściwość zasobu; właściwość wskazująca plik lub zasób silnika | +| `resource.atlas()` | literalny identyfikator typu zasobu atlasu | +| `resource.font()` | literalny identyfikator typu zasobu czcionki | +| `resource.material()` | literalny identyfikator typu zasobu materiału | +| `resource.texture()` | literalny identyfikator typu zasobu tekstury | +| `resource.tile_source()` | literalny identyfikator typu zasobu źródła kafelków | +| `Properties` | widok `Properties` w edytorze, gdzie edytuje się właściwości instancji | +| `Outline` | widok `Outline` w edytorze, z którego wybiera się komponent | + +## `manuals/script.md` + +Ten słowniczek obejmuje tylko kluczowe pojęcia z artykułu o skryptach w Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| script component | komponent skryptu | +| script | skrypt; nazwa techniczna typu komponentu może pozostać bez tłumaczenia | +| game object script | skrypt obiektu gry | +| GUI script | skrypt GUI | +| render script | skrypt do renderowania | +| lifecycle callbacks | funkcje wywołania zwrotnego cyklu życia | +| `self` | bieżąca instancja komponentu; używana do przechowywania stanu | +| `init(self)` | wywoływane przy inicjalizacji komponentu | +| `final(self)` | wywoływane przy usuwaniu komponentu | +| `update(self, dt)` | wywoływane raz na klatkę; `dt` to czas delta | +| `fixed_update(self, dt)` | aktualizacja niezależna od liczby klatek | +| `on_message(self, message_id, message, sender)` | obsługa wiadomości wysyłanych przez `msg.post()` | +| `on_input(self, action_id, action)` | obsługa wejścia po przejęciu fokusu wejścia | +| `on_reload(self)` | wywoływane przy szybkim przeładowaniu skryptu | +| reactive logic | logika reaktywna, oparta na zdarzeniach zamiast na ciągłym odpytywaniu | +| preprocessing | przetwarzanie wstępne kodu przed kompilacją | +| `timer.delay()` | opóźnione wywołanie funkcji po określonym czasie | + +## `manuals/sound.md` + +Ten słownik obejmuje kluczowe terminy używane w instrukcji o dźwięku w Defoldzie. + +| English term | Polish translation / explanation | +| --- | --- | +| Sound component | komponent dźwięku | +| Sound group | grupa dźwiękowa; zbiór komponentów sterowanych wspólnie | +| game object | obiekt gry | +| `sound.play()` | odtwarza dźwięk; wywołanie API pozostaje w języku angielskim | +| `sound.stop()` | zatrzymuje dźwięk; wywołanie API pozostaje w języku angielskim | +| `sound.set_gain()` | ustawia wzmocnienie głosu lub dźwięku | +| `sound.set_group_gain()` | ustawia wzmocnienie grupy | +| `sound.get_groups()` | zwraca wszystkie dostępne grupy dźwięku | +| `sound.get_group_name()` | zwraca nazwę grupy jako `string` w trybie debug | +| `sound.get_rms()` | zwraca średnią kwadratową RMS sygnału | +| `sound.get_peak()` | zwraca wzmocnienie szczytowe | +| peak gain | wzmocnienie szczytowe; w tym miejscu angielska forma może pozostać bez tłumaczenia | +| gain | wzmocnienie; w praktyce głośność | +| pan | panorama stereo, czyli balans lewo/prawo | +| speed | prędkość odtwarzania | +| looping | odtwarzanie w pętli | +| loopcount | liczba powtórzeń odtwarzania | +| master group | wbudowana grupa nadrzędna `master` | +| gating | filtrowanie powtórnych odtworzeń w krótkim czasie | +| phase shift | przesunięcie fazowe | +| streaming sounds | dźwięki strumieniowane | + +## `manuals/spine.md` + +Ten glosariusz obejmuje tylko najistotniejsze terminy z tej instrukcji. + +| English term | Polish translation / explanation | +| --- | --- | +| Spine | Spine | +| Spine bone animation | animacja szkieletowa Spine | +| bone animation | animacja szkieletowa | +| Defold | Defold | +| extension-spine | `extension-spine`, rozszerzenie dla integracji Spine z Defold | +| manual | instrukcja / podręcznik | + +## `manuals/sprite.md` + +Ten słowniczek obejmuje najważniejsze terminy z artykułu o komponencie Sprite i zachowuje literalne identyfikatory Defold, API oraz nazwę UI w języku angielskim. + +| English term | Polish translation / explanation | +|---|---| +| Sprite | komponent wyświetlający obraz 2D albo animację poklatkową | +| atlas | atlas, czyli zestaw obrazów używany przez sprite | +| Tile Source | źródło kafelków używane jako grafika sprite'a | +| flipbook animation | animacja poklatkowa odtwarzana klatka po klatce | +| Image | pole wyboru atlasu lub `Tile Source` dla sprite'a | +| Default Animation | domyślna animacja używana przez sprite | +| Material | materiał używany do renderowania sprite'a | +| Blend Mode | tryb mieszania używany podczas renderowania | +| Size Mode | tryb określający, czy rozmiar ustawia edytor, czy użytkownik | +| Automatic | tryb automatycznego ustawiania rozmiaru | +| Manual | tryb ręcznego ustawiania rozmiaru | +| Slice 9 | zachowanie 9-slice, które chroni narożniki i krawędzie przy skalowaniu | +| `sprite.play_flipbook()` | funkcja odtwarzająca animację sprite'a | +| `sprite.set_hflip()` | funkcja ustawiająca odbicie poziome | +| `sprite.set_vflip()` | funkcja ustawiająca odbicie pionowe | +| `go.get()` | funkcja odczytu właściwości obiektu gry lub komponentu | +| `go.set()` | funkcja ustawiania właściwości obiektu gry lub komponentu | +| `cursor` | znormalizowany kursor animacji | +| `image` | identyfikator obrazu sprite'a | +| `material` | identyfikator materiału sprite'a | +| `playback_rate` | tempo odtwarzania animacji | +| `scale` | skala sprite'a | +| `size` | rozmiar sprite'a | +| `tint` | zabarwienie koloru sprite'a | +| `game.project` | plik ustawień projektu, w którym znajdują się opcje sprite'ów | +| `rename patterns` | wzorce zmiany nazw używane przy wielu teksturach | +| UVs | współrzędne UV określające mapowanie tekstury | +| texture bleeding | przebijanie tekstury; artefakty na styku źle dopasowanych obrazów | + +## `manuals/texture-filtering.md` + +Zakres: najważniejsze terminy z instrukcji o filtrowaniu i próbkowaniu tekstur w grafice. + +| English term | Polish translation / explanation | +|---|---| +| texture filtering | filtrowanie tekstur; sposób wyznaczania koloru piksela z danych tekstury | +| texture sampling | próbkowanie tekstur; pobieranie wartości z tekstury dla piksela na ekranie | +| texel | texel, czyli pojedynczy piksel w teksturze | +| Nearest | `Nearest`; wybiera najbliższy texel bez uśredniania | +| Linear | `Linear`; uśrednia texel z sąsiednimi texelami dla gładszego obrazu | +| minifying filtering | filtrowanie przy pomniejszaniu | +| magnifying filtering | filtrowanie przy powiększaniu | +| `default_texture_min_filter` | ustawienie w `game.project` dla filtrowania przy pomniejszaniu | +| `default_texture_mag_filter` | ustawienie w `game.project` dla filtrowania przy powiększaniu | +| samplers | samplery; obiekty pobierające próbki tekstury w materiale | +| `game.project` | plik projektu, w którym zapisuje się domyślne ustawienia filtrowania | +| `Project Settings` | `Project Settings` (Ustawienia projektu) | + +## `manuals/texture-profiles.md` + +Zakres: najważniejsze terminy z instrukcji profili teksturowania w Defoldzie. + +| English term | Polish translation / explanation | +|---|---| +| texture profile | profil teksturowania, czyli zestaw reguł kompresji dla tekstur | +| texture profiles file | plik `.texture_profiles` z konfiguracją profili | +| path settings | ustawienia ścieżek, które przypisują profile do wzorców plików | +| profile | profil używany do przetwarzania zasobów pasujących do wzorca | +| platform | platforma docelowa, np. `OS_ID_WINDOWS` lub `OS_ID_IOS` | +| formats | formaty tekstury generowane dla danego profilu | +| compressor | kompresor używany do kodowania tekstury | +| compressor preset | predefiniowany poziom kompresji, np. `LOW`, `MEDIUM`, `HIGH`, `HIGHEST` | +| mipmaps | mipmapy generowane dla tekstury | +| premultiply alpha | premnożenie kanału alfa w danych tekstury | +| max texture size | maksymalny rozmiar tekstury po skalowaniu | +| BasisU | skrót od Basis Universal; format pośredni transkodowany w czasie działania | +| ASTC | sprzętowy format kompresji tekstur o blokach stałego rozmiaru | +| `TEXTURE_FORMAT_RGBA_ASTC_4X4` | literał formatu tekstury ASTC; nazwa pozostaje po angielsku | +| `game.project` | plik projektu Defold, w którym wskazuje się `texture_profiles` | +| `Enable texture profiles` | opcja edytora włączająca profile teksturowania | + +## `manuals/tilemap.md` + +Zakres: najważniejsze pojęcia z instrukcji o mapach kafelków. Literalne nazwy UI, API i identyfikatory kodu pozostają po angielsku. + +| English term | Polish translation / explanation | +|---|---| +| Tile map | mapa kafelków; komponent do układania kafelków na siatce | +| Tile Source | źródło kafelków; zasób zawierający kafelki i ich kształty kolizji | +| Layer | warstwa mapy, na której maluje się kafelki | +| Assets | `Assets`, widok zasobów w edytorze | +| Outline | `Outline`, widok struktury mapy i warstw | +| Tile Source property | właściwość `Tile Source`, wskazująca używany plik źródła kafelków | +| Material | `Material`, materiał używany do renderowania mapy | +| Blend Mode | `Blend Mode`, tryb mieszania używany podczas renderowania | +| Collision Shapes | kształty kolizji dostępne w źródle kafelków | +| tilemap.get_tile() | `tilemap.get_tile()`, funkcja odczytu kafelka z mapy w runtime | +| tilemap.set_tile() | `tilemap.set_tile()`, funkcja zapisu kafelka w mapie w runtime | +| go.get() | `go.get()`, funkcja odczytu właściwości komponentu | +| go.set() | `go.set()`, funkcja ustawiania właściwości komponentu | +| tile_source | `tile_source`, właściwość komponentu z hashowanym odwołaniem do źródła kafelków | +| material | `material`, właściwość komponentu z hashowanym odwołaniem do materiału | +| tint | `tint`, kolor zabarwienia mapy jako `vector4` | +| game.project | `game.project`, plik konfiguracji projektu | +| Tiled | `Tiled`, zewnętrzny edytor map, który może eksportować do Defold | +| Tilesetter | `Tilesetter`, zewnętrzny edytor i generator tilesetów | + +## `manuals/tilesource.md` + +Krótki słownik najważniejszych pojęć używanych w artykule o `Tile Source`. + +| English term | Polish translation / explanation | +|---|---| +| Tile Source | źródło kafelków | +| Tilemap component | komponent `Tilemap` służący do rysowania kafelków na siatce | +| Sprite | `Sprite`, czyli źródło grafiki dla pojedynczego elementu | +| Particle Effect component | komponent `Particle Effect` używający źródła grafiki | +| Collision Shapes | kształty kolizji generowane z obrazu kafelków | +| spacing | odstęp między kafelkami | +| margin | margines wokół kafelka | +| Inner Padding | wewnętrzny margines dodawany automatycznie do tekstury wynikowej | +| Extrude Border | automatyczne powielanie pikseli krawędzi wokół kafelka | +| Outline | `Outline`, widok struktury źródła w edytorze | +| Properties | `Properties`, panel właściwości | +| Playback | sposób odtwarzania animacji | +| Fps | liczba klatek na sekundę | +| Collision | obraz używany do automatycznego generowania kształtów kolizji | +| convex | wypukły | +| collision group | grupa kolizji | +| anim | domyślna animacja utworzona dla nowego `Tile Source` | + +## `manuals/writing-code.md` + +Zakres: najważniejsze terminy z instrukcji o pisaniu kodu w Defold. + +| English term | Polish translation / explanation | +|---|---| +| game logic | logika gry | +| Lua | język skryptowy używany do logiki gry | +| Lua 5.1 | konkretna wersja Lua używana przez Defold | +| LuaJIT | wariant Lua używany na części platform | +| native code | kod natywny dla danej platformy | +| native extensions | rozszerzenia natywne do pracy z kodem natywnym | +| transpiler | narzędzie tłumaczące inny język na Lua | +| statically-checked Lua | Lua z analizą statyczną, czyli sprawdzaniem błędów przed uruchomieniem | +| built-in code editor | wbudowany edytor kodu w Defold | +| code completion | autouzupełnianie kodu | +| code linting | linting, czyli automatyczne sprawdzanie jakości i błędów kodu | +| Luacheck | narzędzie do lintingu Lua | +| Lua language server | serwer języka Lua do analiz i podpowiedzi | +| `.luacheckrc` | plik konfiguracyjny Luacheck | +| external code editor | zewnętrzny edytor kodu | +| Preferences window | okno `Preferences` | +| Code tab | karta `Code` | +| Visual Studio Code | edytor Visual Studio Code | +| Defold Kit | wtyczka Defold Kit do Visual Studio Code | +| `go.animate()` | API Defold; identyfikator pozostaje w oryginale | + +## `shared/blend-modes.md` + +Glosariusz najważniejszych terminów związanych z mieszaniem kolorów w właściwości `Blend Mode`. + +| English term | Polish translation / explanation | +| --- | --- | +| `Blend Mode` | właściwość określająca sposób mieszania grafiki komponentu z tłem | +| `Alpha` | normalne blendowanie z uwzględnieniem kanału alfa | +| `Add` | dodawanie wartości kolorów, które rozjaśnia tło | +| `Multiply` | mnożenie wartości kolorów, które przyciemnia tło | +| `Screen` | odwrotność `Multiply`; rozjaśnia tło | +| `src` | kolor i alfa aktualnego źródła, czyli grafiki komponentu | +| `dst` | kolor pikseli tła, czyli obrazu znajdującego się pod spodem | + +## `shared/components.md` + +To są najważniejsze terminy z artykułu o komponentach i ich polskie odpowiedniki lub objaśnienia. + +| English term | Polish translation / explanation | +|---|---| +| component | komponent | +| game object | obiekt gry | +| position | pozycja | +| rotation | rotacja | +| scale | skala | +| type specific properties | właściwości specyficzne dla typu komponentu | +| runtime | w czasie działania programu | +| Outline | `Outline` (widok zawartości pliku) | +| Add Component | `Add Component` (dodaj komponent w obiekcie gry) | +| Add Component File | `Add Component File` (dodaj jako odwołanie do pliku komponentu) | +| Script | `Script` | +| GUI | `GUI` | +| Particle FX | `Particle FX` | +| Tile Map | `Tile Map` | + +## `shared/install.md` + +Zakres: najistotniejsze terminy z artykułu o pobieraniu, instalacji i uruchamianiu edytora Defold. + +| English term | Polish translation / explanation | +|---|---| +| `download page` | strona pobierania | +| `Download` | przycisk pobierania | +| `installation` | instalacja | +| `DMG image` | obraz DMG, czyli format instalacyjny używany w macOS | +| `ZIP archive` | archiwum ZIP do wypakowania | +| `Extract All` | polecenie wypakowania wszystkich plików w Windows | +| `Applications` | folder Aplikacje w macOS | +| `Defold` | nazwa aplikacji i folderu z edytorem; zostaje w języku angielskim | +| `Defold.exe` | plik wykonywalny edytora w Windows | +| `unzip` | polecenie w terminalu do rozpakowania archiwum ZIP | +| `Help > Create Desktop Entry` | pozycja menu do utworzenia skrótu na pulpicie w Linux | +| `FAQ` | sekcja często zadawanych pytań; w artykule chodzi o część dotyczącą Linux | +| `GitHub` | serwis, na którym dostępne są starsze wersje Defold | + +## `shared/material-constants.md` + +Glosariusz najważniejszych terminów z artykułu o stałych materiału i ich zmianie w `go.set()` oraz `go.animate()`. + +| English term | Polish translation / explanation | +| --- | --- | +| `material` | materiał; zasób określający wygląd renderowania | +| `constants` | stałe materiału, czyli wartości parametryczne możliwe do zmiany w czasie | +| `go.set()` | funkcja ustawiająca wartość stałej lub innej właściwości komponentu | +| `go.animate()` | funkcja animująca wartość stałej lub innej właściwości komponentu | +| `component` | komponent, np. ten wskazywany przez `{{ include.component }}` | +| `variable` | nazwa stałej w materiale, np. `{{ include.variable }}` | +| `Material manual` | instrukcja do materiałów; opisuje m.in. stałe wierzchołków i fragmentów | +| `vertex and fragment constants` | stałe wierzchołków i fragmentów, czyli wartości dostępne w shaderze materiału | +| `vmath.vector4()` | tworzy wektor czteroelementowy używany jako przykładowa wartość | +| `go.PLAYBACK_LOOP_PINGPONG` | tryb odtwarzania animacji ping-pong w pętli | +| `go.EASING_LINEAR` | liniowy przebieg interpolacji animacji | + +## `shared/url-shorthands.md` + +Ten słowniczek obejmuje najważniejsze terminy z krótkiego artykułu o skrótach URL w silniku Defold. + +| English term | Polish translation / explanation | +| --- | --- | +| shorthand | skrót | +| current game object | bieżący obiekt gry | +| current component | bieżący komponent | +| `.` | skrót wskazujący bieżący obiekt gry | +| `#` | skrót wskazujący bieżący komponent | +| `msg.post()` | funkcja `msg.post()`, używana tutaj do wysyłania wiadomości do bieżącego obiektu lub komponentu | +| `acquire_input_focus` | nazwa wiadomości; oznacza przejęcie fokusu wejścia | +| `reset` | nazwa wiadomości wysyłanej do bieżącego skryptu | diff --git a/docs/pl/manuals/adapting-graphics-to-screen-size.md b/docs/pl/manuals/adapting-graphics-to-screen-size.md index 6c0fd366..29ea1af2 100644 --- a/docs/pl/manuals/adapting-graphics-to-screen-size.md +++ b/docs/pl/manuals/adapting-graphics-to-screen-size.md @@ -1,120 +1,126 @@ --- -title: Adaptacja do różnych wielkości ekranów -brief: Instrukcja opisuje jak dopasować grę i grafikę do różnych wielkości ekranów. +title: Dostosowywanie grafiki do różnych rozmiarów ekranu +brief: Ta instrukcja wyjaśnia, jak dopasować grę i grafikę do różnych rozmiarów ekranu. --- # Wprowadzenie -Jest wiele elementów do przemyślenia podczas dopasowywania gry do różnych wielkości ekranów: +Podczas dostosowywania gry i grafiki do różnych rozmiarów ekranu warto wziąć pod uwagę kilka kwestii: -* Czy jest to gra retro w niskiej rozdzielczości (pixel art)? Czy może nowoczesna gra z grafiką HD wysokiej jakości? -* Jak gra powinna zachowywać się na różnej wielkości ekranach uruchomiona na pełnym ekranie? - * Czy gracz powinien widzieć większy fragment mapy/gry przy większej rozdzielczości? Czy może grafika powinna być skalowana do rozdzielczości, ąby zawsze pokazywać ten sam fragment? -* Jak gra powinna sobie radzić z różnymi proporcjami ekranu niż ta, którą podasz w ustawieniach *game.project*? - * Czy gracz powinien widzieć większy fragment mapy/gry przy większej rozdzielczości? Czy może fragmenty poza proporcjami powinny być zasłonięte przez czarne paski? Czy elementy interfejsu (GUI) powinny być przeskalowane? -* Jaki rodzaj menu i elementów interfejsu potrzebujesz? Jak powinny się adaptować do zmian rozdzielczości i orientacji? - * Czy menu i elementy interfejsu powinny zmieniać rozplanowanie wraz ze zmianą orientacji i rozdzielczości czy utrzymywać stałą pozycję? +* Czy jest to gra retro z niską rozdzielczością i pikselową grafiką, czy nowoczesna gra z grafiką HD wysokiej jakości? +* Jak gra powinna się zachowywać w trybie pełnoekranowym na ekranach o różnych rozmiarach? + * Czy gracz powinien widzieć więcej zawartości gry na ekranie o wysokiej rozdzielczości, czy grafika powinna skalować się adaptacyjnie, aby zawsze pokazywać ten sam obszar? +* Jak gra powinna radzić sobie z proporcjami obrazu innymi niż te ustawione w pliku *game.project*? + * Czy gracz powinien widzieć więcej zawartości gry? A może powinny pojawić się czarne pasy? A może elementy GUI powinny zostać przeskalowane? +* Jakiego rodzaju menu i elementy GUI na ekranie są potrzebne i jak powinny się dostosowywać do różnych rozmiarów ekranu oraz orientacji? + * Czy menu i inne elementy GUI powinny zmieniać układ po zmianie orientacji, czy raczej zachowywać ten sam układ niezależnie od orientacji? -Ta instrukcja próbuje odpowiedzieć na poniższe pytania i wskazać najlepsze praktyki. +Ta instrukcja omawia część z tych zagadnień i podaje zalecane praktyki. -## Jak zmienić sposób wyświetlania grafiki +## Jak zmienić sposób renderowania zawartości -Defold wykorzystuje skrypt do renderowania (opracowywania, rysowania i wyświetlania grafiki), tzw. "*render script*", który daje całkowitą kontrolę nad sposobem wyświetlania grafiki na ekranie. Render script definiuje kolejność rysowania elementów oraz co i jak ma być rysowane. Domyślne zachowanie skryptu to rysowanie takiej samej ilości pikseli określonej przez wysokość i szerokość wpisaną w ustawieniach w pliku *game.project* file, niezależnie od tego, czy rozmiar okna został zmieniony lub rozdzielczość urządzenia jest inna. Powoduje to rozciągnięcie obrazu, gdy współczynnik proporcji ekranu się zmieni oraz przeskalowany, kiedy rozmiar okna ulegnie zmianie. W niektórych grach jest to oczywiście akceptowalne, ale jest bardziej prawdopodobne, że chcesz pokazać w takich przypadkach większą lub mniejszą część zawartości ekranu lub przynajmniej przeskalować grafikę bez zmieniania współczynnika proporcji. Domyślny sposób renderowania może więc być z łatwością zmieniony, a więcej o tym możesz się dowiedzieć tutaj: [Instrukcja renderowania](https://www.defold.com/manuals/render/#default-view-projection). +Skrypt do renderowania Defold daje pełną kontrolę nad całym potokiem renderowania. Skrypt renderowania decyduje zarówno o kolejności, jak i o tym, co oraz w jaki sposób jest rysowane. Domyślne zachowanie skryptu renderowania polega na tym, że zawsze rysuje ten sam obszar pikseli, zdefiniowany przez szerokość i wysokość w pliku *game.project*, niezależnie od tego, czy rozmiar okna został zmieniony albo rzeczywista rozdzielczość ekranu się nie zgadza. W efekcie zawartość rozciągnie się, jeśli zmieni się proporcja obrazu, albo zostanie przybliżona lub oddalona, jeśli zmieni się rozmiar okna. W niektórych grach może to być akceptowalne, ale częściej zależy nam na pokazaniu większej lub mniejszej części zawartości gry, gdy rozdzielczość lub proporcje obrazu są inne, albo przynajmniej na zachowaniu proporcji podczas skalowania. Domyślne zachowanie rozciągania można łatwo zmienić, a więcej informacji na ten temat znajdziesz w [instrukcji renderowania](https://www.defold.com/manuals/render/#default-view-projection). -## Retro/Grafika 8-bitowa/Pixel art +## Grafika retro/8-bitowa -Retro grafika często odnosi się do gier naśladujących styl graficzny starych gier z okresy urządzeń z ekranami o niskiej rozdzielczości i ograniczonej palecie barw. Jako przykład Nintendo Entertainment System (NES) ma rozdzielczość 256x240, Commodore 64 - 320x200, a Gameboy - 160x144, a rozdzielczości te są tylko ułamkiem rozdzielczości współczesnych ekranów. Aby umożliwić wyświetlanie takiej grafiki na nich musi ona być przeskalowana kilkukrotnie. Jednym z prostszych sposobów na wyświetlanie takiej grafiki jest wyrysowanie całej grafiki w niskiej rozdzielczości i przybliżenie widoku w momencie renderowania. Można to łatwo zrobić w Defoldzie używając render scriptu i [Stałej Projekcji](/manuals/render/#fixed-projection) ustawionej z odpowiednim zoomem. +Grafika retro/8-bitowa często oznacza gry naśladujące styl graficzny starych konsol i komputerów, z ich niską rozdzielczością oraz ograniczoną paletą kolorów. Na przykład Nintendo Entertainment System (NES) miał rozdzielczość 256x240, Commodore 64 - 320x200, a Gameboy - 160x144, czyli wszystkie te wartości stanowią tylko ułamek rozdzielczości współczesnych ekranów. Aby gry naśladujące ten styl graficzny i taką rozdzielczość były grywalne na nowoczesnym ekranie o wysokiej rozdzielczości, grafikę trzeba kilkukrotnie przeskalować lub przybliżyć. Jednym z prostych sposobów jest tworzenie całej grafiki w niskiej rozdzielczości i stylu, który chcesz naśladować, a następnie powiększanie jej podczas renderowania. W Defold można to łatwo osiągnąć, używając skryptu renderowania i [Fixed Projection](/manuals/render/#fixed-projection) ustawionej na odpowiednią wartość zoom. -Weźmy ten zestaw kafelków i postać ([stąd](https://ansimuz.itch.io/grotto-escape-game-art-pack)) i użyjmy do stworzenia gry w rozdzielczości 320x200: +Weźmy ten tileset i postać ([źródło](https://ansimuz.itch.io/grotto-escape-game-art-pack)) i użyjmy ich w 8-bitowej grze retro w rozdzielczości 320x200: ![](images/screen_size/retro-player.png) ![](images/screen_size/retro-tiles.png) -Ustaw rozdzielczość 320x200 w pliku *game.project* i uruchom grę - po uruchomieniu ujrzysz: +Ustawienie 320x200 w pliku *game.project* i uruchomienie gry da taki efekt: ![](images/screen_size/retro-original_320x200.png) -Okno na nowoczesnym monitorze o wysokiej rozdzielczości jest niezwykle małe! Powiększając rozmiar okna czterokrotnie do 1280x800 będzie bardziej przystępne: +Okno jest na nowoczesnym ekranie o wysokiej rozdzielczości bardzo małe! Zwiększenie rozmiaru okna czterokrotnie, do 1280x800, sprawia, że staje się ono bardziej odpowiednie dla współczesnego monitora: ![](images/screen_size/retro-original_1280x800.png) -Rozmiar okna jest w porządku, więc teraz potrzeba zmienić sposób wyświetlania grafiki wewnątrz, ponieważ w chwili oecnej jest zbyt mała i ciężko jest zobaczyć cokolwiek co się dzieje w grze. Możemy użyć render scriptu aby ustawić stałą i przybliżoną projekcję: +Skoro rozmiar okna jest już bardziej sensowny, musimy jeszcze zrobić coś z grafiką. Jest tak mała, że trudno zorientować się, co dzieje się w grze. Możemy użyć skryptu renderowania, aby ustawić stałą, powiększoną projekcję: ```Lua msg.post("@render:", "use_fixed_projection", { zoom = 4 }) ``` -Co da nam rezultat: +::: sidenote +Ten sam efekt można uzyskać, podłączając [komponent Camera](manuals/camera/) do obiektu gry, zaznaczając *Orthographic Projection* i ustawiając *Orthographic Zoom* na 4.0: + +![](images/screen_size/retro-camera_zoom.png) +::: + +To da następujący wynik: ![](images/screen_size/retro-zoomed_1280x800.png) -Jest lepiej. Okno i grafika mają odpowiedni rozmiar, ale po przyjrzeniu się bliżej widzimy problem: +Jest lepiej. Okno i grafika mają już sensowny rozmiar, ale po bliższym przyjrzeniu się widać wyraźny problem: ![](images/screen_size/retro-zoomed_linear.png) -Obraz jest rozmazany! Jest to spowodowane domyślnym sposobem próbkowania grafiki renderowanej przez GPU podczas przybliżania widoku. Domyślne ustawienie w pliku *game.project* w sekcji *Graphics* to *linear* (liniowe): +Grafika jest rozmyta! Wynika to ze sposobu próbkowania powiększonej grafiki z tekstury podczas renderowania przez GPU. Domyślne ustawienie w pliku *game.project* w sekcji Graphics to *linear*: ![](images/screen_size/retro-settings_linear.png) -Zmiana na *nearest* (najbliższy) da nam rezultat: +Zmiana tego ustawienia na *nearest* daje oczekiwany rezultat: ![](images/screen_size/retro-settings_nearest.png) ![](images/screen_size/retro-zoomed_nearest.png) -I mamy przejrzystą grafikę pikselową do naszej gry retro! Jest nawet więcej elementów do rozważenia, jak na przykład wyłączenie sub-pikseli dla sprite'ów w *game.project*: +Teraz mamy ostrą, pikselową grafikę naszej retro gry. Jest jeszcze więcej rzeczy do rozważenia, na przykład wyłączenie subpikseli dla sprite'ów w pliku *game.project*: ![](images/screen_size/retro-subpixels.png) -Gdy opcja Subpixels jest wyłączona grafiki nigdy nie będą wyświetlana w częściach piskeli, a zamiast tego przystosowane do siatki pełnych pikseli. +Gdy opcja Subpixels jest wyłączona, sprite'y nigdy nie są renderowane na półpikselach i zawsze są przyciągane do najbliższego pełnego piksela. -## Grafika w wysokiej rozdzielczości (HD) +## Grafika o wysokiej rozdzielczości -Podczas pracy z grafiką w wysokiej rozdzielczości należy podejść do ustawień w inny sposób niż do grafiki retro. Z grafiką bitmapową musisz przygotować obrazy w takiej rozdzielczości, aby wyglądały ostro i przejrzyście na monitorach o wysokiej rozdzielczości wyświetlone w skali 1:1. +W przypadku grafiki o wysokiej rozdzielczości trzeba podejść do konfiguracji projektu i zawartości inaczej niż przy grafice retro/8-bitowej. W przypadku grafiki bitmapowej należy tworzyć zasoby w taki sposób, aby dobrze wyglądały na ekranie o wysokiej rozdzielczości przy skali 1:1. -Tutaj również należy wprowadzić zmiany w skrypcie renderowania. W tym przypadku należy skalować grafikę razem ze zmianą rozdzielczości z zachowaniem oryginalnego współczynnika proporcji ekranu: +Podobnie jak w przypadku grafiki retro/8-bitowej trzeba zmienić skrypt renderowania. Tutaj zależy nam na tym, aby grafika skalowała się wraz z rozmiarem ekranu, zachowując oryginalne proporcje obrazu: ```Lua msg.post("@render:", "use_fixed_fit_projection") ``` -Zapewni to zmianę przybliżenia widoku w taki sposób, że na ekranie będzie widoczna zawsze taka sama część grafiki/zawartości określona w pliku *game.project*, lub tylko z dodatkowym obszarem wyświetlonym nad i pod lub obok oryginalnego obrazu w zależności od tego czy współczynnik proporcji ekranu będzie inny niż oryginalny. +Dzięki temu ekran będzie się zmieniał tak, aby zawsze pokazywać tę samą ilość zawartości określoną w pliku *game.project*, ewentualnie z dodatkową zawartością widoczną nad i pod głównym obszarem albo po bokach, zależnie od tego, czy proporcje obrazu są inne. -Powinno się określić wysokość i szerokość obrazu w pliku *game.project* do rozmiaru, który pozwoli na wyświetlenie Twoich grafik bez przeskalowania. +Powinieneś skonfigurować szerokość i wysokość w pliku *game.project* na taki rozmiar, który pozwoli wyświetlać zawartość gry bez skalowania. ### Ustawienie High DPI i ekrany Retina -Jeśli chcesz również wspierać ekrany Retina możesz to włączyć w pliku *game.project* w sekcji *Display*(Wyświetlacz): +Jeśli chcesz także wspierać ekrany Retina, możesz włączyć tę opcję w pliku *game.project* w sekcji Display: ![](images/screen_size/highdpi-enabled.png) -Pozwoli to na tworzenie bufora High DPI na wyświetlaczach/ekranach, które wspierają taką technologię. Gra będzie wyświetlana w rozdzielczości dwukrotnie większej niż ta ustawiona oryginalnie, która jednak nadal pozostanie rozdzielczościa postrzeganą przez logikę gry. Oznacza to, że wszystkie pomiary pozostają takie same i zawartość renderowana w skali 1x również. Ale gdy zaimportujesz obrazy w wysokiej rozdzielczości i zmniejszysz dwukrotnie, będą nadal wyświetlane jako High DPI na ekranie. +Spowoduje to utworzenie bufora wysokiego DPI na ekranach, które to obsługują. Gra będzie renderowana w rozdzielczości dwukrotnie większej niż ta ustawiona w polach Width i Height, które nadal pozostaną logiczną rozdzielczością używaną w skryptach i właściwościach. Oznacza to, że wszystkie wartości pomiarów pozostaną takie same, a zawartość renderowana w skali 1x będzie wyglądała tak samo. Jeśli jednak zaimportujesz obrazy w wysokiej rozdzielczości i przeskalujesz je do 0.5x, będą one wyświetlane na ekranie jako High DPI. -## Tworzenie interfejsu adaptacyjnego +## Tworzenie adaptacyjnego GUI -System do tworzenia elementów interfejsu użytkownika (GUI - ang. Graphical User Interface) opiera się na kilku podstawowych blokach, tzw. [węzłach](/manuals/gui/#node-types), i mimo, że wygląda na uproszczony, można dzięki niemu stworzyć zaawansowane elementy, przyciski, indykatory, menusy i pop-upy. Tworzone przez Ciebie GUI może być skonfigurowane do automatycznej adaptacji do różnych wielkości ekranów i zmian orientacji. Możesz przykłądowo zachować węzły zakotwiczone do góru, dołu lub boków ekranu i mogą one zachowywać lub zmieniać swój rozmiar i skalę. Zależności pomiędzy węzłami, jak i również ich rozmiarami mogą być również skonfigurowane, aby dostosować się do zmian rozdzielczości i orientacji. +System tworzenia komponentów GUI opiera się na kilku podstawowych elementach, czyli [węzłach](/manuals/gui/#node-types). Choć może wydawać się uproszczony, można go wykorzystać do tworzenia wszystkiego, od przycisków po złożone menu i popupy. Tworzone GUI można skonfigurować tak, aby automatycznie dostosowywało się do zmian rozmiaru ekranu i orientacji. Na przykład można przypinać węzły do górnej, dolnej lub bocznych krawędzi ekranu, a węzły mogą zachowywać swój rozmiar albo się rozciągać. Relację między węzłami, a także ich rozmiar i wygląd, można również skonfigurować tak, aby zmieniały się wraz ze zmianą rozmiaru ekranu lub orientacji. ### Właściwości węzłów -Każdy węzeł w systemie GUI ma swoją oś (ang. pivot), horyzontalne i wertykalne zakotwiczenie (ang. anchor) oraz tryb dopasowania (ang. adjust mode). +Każdy węzeł w GUI ma punkt pivot, poziome i pionowe zakotwiczenie oraz tryb dopasowania. -* *Pivot* definiuje punkt środkowy węzła. -* *Anchor* (kotwica) kontroluje zmianę położenia pionowego lub poziomego kiedy granice sceny, lub granice węzła-rodzica są rozciągnięte, aby dostosować się do zmiany rozmiaru ekranu. -* *Adjust mode* (tryb dopasowania) kontroluje co dzieje się z węzłem, gdy granice sceny lub węzła-rodzica są dopasowane do wypełnienia ekranu. +* Punkt pivot określa środek węzła. +* Tryb anchor określa, jak zmienia się pozycja pionowa i pozioma węzła, gdy granice sceny lub granice węzła nadrzędnego są rozciągane tak, aby dopasować się do fizycznego rozmiaru ekranu. +* Ustawienie adjust mode określa, co dzieje się z węzłem, gdy granice sceny lub granice węzła nadrzędnego są dopasowywane do fizycznego rozmiaru ekranu. -Więcej o tych właściwościach możesz przeczytać [w tej instrukcji do GUI](/manuals/gui/#node-properties). +Więcej informacji o tych właściwościach znajdziesz w [instrukcji GUI](/manuals/gui/#node-properties). -### Rozplanowanie elementów (Layouts) +### Układy -Defold oferuje interfejsy GUI, które automatycznie dopasowują się do różnych wielkości ekranów i orientacji na urządzeniach mobilnych. Używając tych właściwości możesz zaprojektować GUI, które adaptuje się do zmian współczynnika proporcji i orientacji ekranu na ekranach o różnych rozmiarach. Można również skonfigurować rozplanowanie elementów dla konkretnych modeli urządzeń. Możesz się dowiedzieć o tym więcej [w tej instrukcji do layout'ów GUI](/manuals/gui-layouts/) +Defold obsługuje GUI, które automatycznie dostosowują się do zmian orientacji ekranu na urządzeniach mobilnych. Dzięki tej funkcji możesz zaprojektować GUI, które dopasowuje się do orientacji i proporcji obrazu na szerokim zakresie rozmiarów ekranów. Można też tworzyć układy odpowiadające konkretnym modelom urządzeń. Więcej informacji o tym systemie znajdziesz w [instrukcji GUI Layouts](/manuals/gui-layouts/) -## Testowanie ekranów o różnych wielkościach +## Testowanie różnych rozmiarów ekranu -Defold oferuje menu do debugowania, które zawiera opcję symulowania rozdzielczości konretnego urządzenia lub dowolnej rozdzielczości. Gdy aplikacja jest uruchomiona możesz kliknąć Debug->Simulate Resolution i wybrać jedno z urządzeń z listy. Okno aplikacji zmieni rozmiar i będziesz widzieć, jak Twoja gra wygląda na ekranie o danej rozdzielczości z danym współczynnikiem proporcji. +Menu Debug zawiera opcję symulowania rozdzielczości konkretnego modelu urządzenia albo własnej rozdzielczości. Gdy aplikacja jest uruchomiona, możesz wybrać Debug->Simulate Resolution i wskazać jeden z modeli urządzeń z listy. Okno uruchomionej aplikacji zmieni rozmiar i będziesz mógł sprawdzić, jak gra wygląda w innej rozdzielczości lub przy innych proporcjach obrazu. ![](images/screen_size/simulate-resolution.png) diff --git a/docs/pl/manuals/addressing.md b/docs/pl/manuals/addressing.md index 9b16485b..7564b9a5 100644 --- a/docs/pl/manuals/addressing.md +++ b/docs/pl/manuals/addressing.md @@ -1,15 +1,15 @@ --- -title: Adresowanie w silniku Defold -brief: Instrukcja wyjaśnia sposób adresowania w silniku Defold. +title: Adresowanie w Defold +brief: Niniejsza instrukcja wyjaśnia, jak Defold rozwiązał problem adresowania. --- # Adresowanie -Kod, który steruje działającą grą, musi mieć możliwość dotarcia do każdego obiektu gry i komponentu, aby przesuwać, skalować, animować, usuwać i manipulować tym, co gracz widzi i słyszy. Mechanizm adresowania w silniku Defold sprawia, że jest to możliwe. +Kod sterujący działającą grą musi mieć możliwość dotarcia do każdego obiektu gry i komponentu, aby przesuwać, skalować, animować, usuwać i manipulować tym, co gracz widzi i słyszy. Mechanizm adresowania w Defold sprawia, że jest to możliwe. ## Identyfikatory -Defold wykorzystuje adresy (czyli URL-e, ale na razie odłóżmy tę kwestię na bok), aby odnosić się do obiektów gry i komponentów. Adresy te składają się z identyfikatorów. Poniżej znajdziesz przykłady zastosowań adresów w silniku Defold; w tej instrukcji przyjrzymy się im dokładnie: +Defold używa adresów (albo URL-i, ale na razie pomińmy ten szczegół), aby odwoływać się do obiektów gry i komponentów. Adresy te składają się z identyfikatorów. Poniżej znajdują się przykłady użycia adresów w Defold. W tej instrukcji przyjrzymy się dokładnie, jak działają: ```lua local id = factory.create("#enemy_factory") @@ -22,72 +22,71 @@ msg.post("#", "hello_there") local id = go.get_id(".") ``` -Zacznijmy od bardzo prostego przykładu. Załóżmy, że masz obiekt gry zawierający pojedynczy komponent typu sprite. Pod tym obiektem znajduje się komponent typu skrypt, który go kontroluje. Taki układ w edytorze wygląda mniej więcej tak: +Zacznijmy od bardzo prostego przykładu. Załóżmy, że masz obiekt gry z jednym komponentem typu sprite. Masz też komponent skryptu, który steruje tym obiektem gry. Taki układ w edytorze wygląda mniej więcej tak: ![bean in editor](images/addressing/bean_editor.png) -Chcesz wyłączyć sprite na starcie gry, żeby potem pokazać go ponownie. Wystarczy umieścić poniższy kod w pliku "controller.script": +Chcesz wyłączyć sprite na początku gry, aby móc pokazać go później. Wystarczy umieścić poniższy kod w pliku "controller.script": ```lua function init(self) msg.post("#body", "disable") -- <1> end ``` +1. Nie przejmuj się na razie znakiem '#'. Wrócimy do niego za chwilę. -1. Nie przejmuj się na razie znakiem '#'. Wrócimy do tego za moment. - -Działa to zgodnie z oczekiwaniami. Gdy gra startuje, komponent skryptowy adresuje komponent sprite po identyfikatorze "body" i używa tego adresu, aby wysłać do niego wiadomość "disable". Efektem tej specjalnej wiadomości silnika jest to, że komponent sprite ukrywa grafikę. Schematycznie sytuacja wygląda następująco: +To działa zgodnie z oczekiwaniami. Gdy gra się uruchamia, komponent skryptowy *adresuje* komponent sprite po identyfikatorze "body" i używa tego adresu, aby wysłać do niego *wiadomość* "disable". Efektem tej specjalnej wiadomości silnika jest ukrycie grafiki sprite. Schematycznie wygląda to tak: ![bean](images/addressing/bean.png) -Identyfikatory w tym ustawieniu są dowolne. Tutaj zdecydowaliśmy się nadać obiektowi gry identyfikator "bean", jego komponentowi sprite identyfikator "body", a skrypt kontrolujący postać nazwaliśmy "controller". +Identyfikatory w tym układzie są dowolne. Tutaj obiekt gry ma identyfikator "bean", jego komponent sprite ma identyfikator "body", a skrypt sterujący postacią nosi nazwę "controller". ::: sidenote -Jeśli nie wybierzesz własnego identyfikatora, edytor zrobi to za Ciebie. Kiedy tworzysz nowy obiekt gry lub komponent, automatycznie ustawiane jest unikalne *Id*. +Jeśli nie wybierzesz własnego identyfikatora, zrobi to za Ciebie edytor. Gdy tworzysz nowy obiekt gry lub komponent, automatycznie ustawiane jest unikalne *Id*. -- Obiekty gry (ang. game objects) otrzymują domyślnie identyfikator "go" z kolejnym numerem ("go2", "go3" itd.). -- Komponenty dostają identyfikator odpowiadający typowi ("sprite", "sprite2", "label", "sound" itd.). +- Obiekty gry automatycznie dostają identyfikator "go" z kolejnym numerem ("go2", "go3" itd.). +- Komponenty dostają identyfikator odpowiadający typowi komponentu ("sprite", "sprite2" itd.). -Możesz pozostać przy tych automatycznie przypisanych nazwach, ale zachęcamy do zmiany ich na opisowe, celowe identyfikatory. +Możesz pozostać przy tych automatycznie przypisanych nazwach, ale zachęcamy do nadawania identyfikatorom dobrych, opisowych nazw. ::: Teraz dodajmy kolejny komponent sprite i wyposażmy fasolkę w tarczę: ![bean](images/addressing/bean_shield_editor.png) -Nowy komponent musi mieć unikatowy identyfikator w obrębie obiektu gry. Gdybyś ponownie nazwał go "body", kod byłby niejednoznaczny – nie wiadomo, do którego sprite'a wysłać wiadomość "disable". Dlatego wybieramy unikalny, opisowy identyfikator "shield". W ten sposób możemy włączać i wyłączać sprite'y "body" i "shield" niezależnie. +Nowy komponent musi mieć unikalny identyfikator w obrębie obiektu gry. Gdybyś nadał mu nazwę "body", kod byłby niejednoznaczny, bo nie byłoby jasne, do którego sprite'a wysłać wiadomość "disable". Dlatego wybieramy unikalny i opisowy identyfikator "shield". Dzięki temu możemy włączać i wyłączać sprite'y "body" i "shield" według potrzeb. ![bean](images/addressing/bean_shield.png) ::: sidenote -Jeśli spróbujesz użyć tego samego identyfikatora dwa razy, edytor zgłosi błąd, więc w praktyce nigdy nie ma z tym problemu: +Jeśli spróbujesz użyć tego samego identyfikatora dwa razy, edytor zgłosi błąd, więc w praktyce nie stanowi to problemu: ![bean](images/addressing/name_collision.png) ::: -Przyjrzyjmy się teraz, co się stanie, gdy dodasz kolejne obiekty. Załóżmy, że chcesz połączyć dwie fasolki w mały zespół. Nazwijmy jeden obiekt "bean", a drugiemu nadajmy nazwę "buddy". Chcemy też, żeby gdy "bean" przez chwilę stoi w miejscu, powiedział "buddy", żeby zaczął tańczyć. Robimy to wysyłając niestandardową wiadomość "dance" ze skryptu "controller" obiektu "bean" do skryptu "controller" obiektu "buddy": +Przyjrzyjmy się teraz temu, co się stanie, gdy dodasz więcej obiektów. Załóżmy, że chcesz połączyć dwie fasolki w mały zespół. Jeden obiekt nazwij "bean", a drugi "buddy". Gdy "bean" przez chwilę pozostaje bezczynny, ma powiedzieć "buddy", żeby zaczął tańczyć. Robi się to przez wysłanie niestandardowej wiadomości "dance" ze skryptu "controller" obiektu "bean" do skryptu "controller" obiektu "buddy": ![bean](images/addressing/bean_buddy.png) ::: sidenote -Widzimy tu dwa komponenty skryptowe o nazwie "controller", ale każdy w innym obiekcie gry, więc jest to całkowicie legalne. Dla każdego obiektu tworzy się nowy kontekst nazewniczy. +Widać tu dwa komponenty skryptowe o nazwie "controller", po jednym w każdym obiekcie gry, i to jest całkowicie poprawne, ponieważ każdy obiekt gry tworzy nowy kontekst nazewniczy. ::: -Ponieważ adresat wiadomości znajduje się poza obiektem wysyłającym ("bean"), kod musi określić, który komponent "controller" powinien ją otrzymać. Trzeba więc podać zarówno identyfikator (Id) obiektu gry, jak i identyfikator komponentu. Pełny adres komponentu to `"buddy#controller"` i składa się z dwóch części. +Ponieważ adresat wiadomości znajduje się poza obiektem wysyłającym ("bean"), kod musi określić, który komponent "controller" ma ją otrzymać. Trzeba więc podać zarówno identyfikator obiektu gry, jak i identyfikator komponentu. Pełny adres komponentu to `"buddy#controller"` i składa się z dwóch części. -- Najpierw określamy identyfikator obiektu gry ("buddy"), -- następnie wstawiamy znak oddzielający obiekt i komponent ("#"), +- Najpierw podajemy identyfikator obiektu gry ("buddy"), +- następnie wpisujemy znak oddzielający obiekt od komponentu ("#"), - a na końcu podajemy identyfikator komponentu ("controller"). -Wracając do poprzedniego przykładu z jednym obiektem gry, widzimy, że pomijając część identyfikującą obiekt (czyli nie wpisując nic przed "#"), kod odwołuje się do komponentów we *własnym obiekcie*. +Wracając do poprzedniego przykładu z jednym obiektem gry, widać, że jeśli pominiemy część identyfikującą obiekt docelowy, kod może adresować komponenty w *bieżącym obiekcie gry*. -Na przykład `"#body"` to adres komponentu "body" wewnątrz tego samego obiektu gry. To bardzo wygodne uproszczenie, ponieważ pozwala pisać generyczny kod, który będzie działał dla *dowolnego* obiektu, jeśli tylko zawiera komponent "body". +Na przykład `"#body"` oznacza adres komponentu "body" w bieżącym obiekcie gry. To bardzo przydatne, ponieważ ten kod zadziała w *dowolnym* obiekcie gry, o ile tylko taki komponent "body" istnieje. ## Kolekcje -Kolekcje (ang. collections) pozwalają tworzyć grupy lub hierarchie obiektów gry i korzystać z nich wielokrotnie w kontrolowany sposób. W edytorze używa się plików kolekcji jako szablonów (czyli "prototypów" albo "prefabów") przy dodawaniu zawartości do gry. +Kolekcje pozwalają tworzyć grupy lub hierarchie obiektów gry i używać ich wielokrotnie w kontrolowany sposób. W edytorze nowego *pliku kolekcji* używa się jako szablonu, czyli "prototypu" albo "prefabu", gdy dodajesz zawartość do gry. -Załóżmy, że chcesz wygenerować dużą liczbę duetów bean/buddy. Dobrym sposobem jest stworzenie nowego pliku kolekcji (nazwa "team.collection"), zbudowanie w nim obiektów i zapisanie go. Następnie umieść instancję tego pliku w głównej kolekcji bootstrapowej i nadaj instancji identyfikator, na przykład "team_1": +Załóżmy, że chcesz utworzyć dużą liczbę duetów bean/buddy. Dobrym sposobem jest przygotowanie nowego pliku kolekcji (nazwij go "team.collection"), zbudowanie w nim obiektów i zapisanie pliku. Następnie umieść instancję zawartości tego pliku w głównej kolekcji bootstrapowej i nadaj tej instancji identyfikator, na przykład "team_1": ![bean](images/addressing/team_editor.png) @@ -95,35 +94,35 @@ Dzięki takiej strukturze obiekt "bean" nadal może odwoływać się do komponen ![bean](images/addressing/collection_team.png) -Jeśli dodasz drugą instancję "team.collection" (nazwij ją "team_2"), kod działający wewnątrz komponentów skryptowych tej instancji zadziała dokładnie tak samo. Obiekt "bean" z instancji "team_2" dalej może wysyłać wiadomości do komponentu "controller" obiektu "buddy" przez adres `"buddy#controller"`. +Jeśli dodasz drugą instancję "team.collection" (nazwij ją "team_2"), kod uruchomiony wewnątrz komponentów skryptowych tej instancji będzie działał tak samo. Obiekt "bean" z instancji "team_2" nadal może adresować komponent "controller" obiektu "buddy" przez adres `"buddy#controller"`. ![bean](images/addressing/teams_editor.png) -## Adresowanie relatywne +## Adresowanie względne -Adres `"buddy#controller"` działa dla obiektów z obu kolekcji, ponieważ jest *relatywny*. Każda instancja kolekcji "team_1" i "team_2" tworzy własny kontekst nazewniczy, czyli przestrzeń nazw. Defold unika kolizji nazw, uwzględniając ten kontekst przy adresowaniu: +Adres `"buddy#controller"` działa dla obiektów z obu kolekcji, ponieważ jest *względny*. Każda instancja kolekcji "team_1" i "team_2" tworzy własny kontekst nazewniczy, czyli przestrzeń nazw. Defold unika kolizji nazw, uwzględniając ten kontekst podczas adresowania: ![relative id](images/addressing/relative_same.png) - W ramach kontekstu nazewniczego kolekcji "team_1" obiekty "bean" i "buddy" mają unikalne identyfikatory. -- W analogiczny sposób w kontekście kolekcji "team_2" identyfikatory "bean" i "buddy" również są unikatowe. +- Analogicznie, w kontekście kolekcji "team_2" identyfikatory "bean" i "buddy" również są unikalne. -Adresowanie relatywne działa dzięki temu, że podczas rozwiązywania adresu Defold automatycznie dopisuje aktualny kontekst nazewniczy. To bardzo praktyczne, ponieważ pozwala tworzyć grupy obiektów z taką samą logiką i wielokrotnie wykorzystywać je w grze. +Adresowanie względne działa dzięki temu, że podczas rozwiązywania adresu Defold automatycznie dopisuje bieżący kontekst nazewniczy. To bardzo wygodne i pozwala tworzyć grupy obiektów z kodem, który można wielokrotnie wykorzystywać w całej grze. ### Skróty -Defold udostępnia dwa przydatne skróty, które pozwalają wysyłać wiadomości bez określania pełnego URL: +Defold udostępnia dwa przydatne skróty, których możesz użyć do wysyłania wiadomości bez podawania pełnego URL: -:[Shorthands](../shared/url-shorthands.md) +:[Skróty](../shared/url-shorthands.md) -## Ścieżki do obiektów +## Ścieżki obiektów gry -Aby zrozumieć mechanizm nazewnictwa, spójrzmy, co się dzieje po zbudowaniu i uruchomieniu projektu: +Aby poprawnie zrozumieć mechanizm nazewnictwa, zobaczmy, co dzieje się po zbudowaniu i uruchomieniu projektu: -1. Edytor wczytuje kolekcję bootstrapową ("main.collection") i całą zawartość (obiekty gry i inne kolekcje). -2. Dla każdego statycznego obiektu gry kompilator tworzy identyfikator. Tworzy się ścieżka, która zaczyna się w "źródle" (ang. root - korzeń) kolekcji bootstrapowej i schodzi przez kolejne kolekcje aż do obiektu. Na każdym poziomie hierarchii dokleja się znak '/'. +1. Edytor odczytuje kolekcję bootstrapową ("main.collection") i całą jej zawartość, czyli obiekty gry oraz inne kolekcje. +2. Dla każdego statycznego obiektu gry kompilator tworzy identyfikator. Identyfikatory te są budowane jako "ścieżki" zaczynające się od korzenia kolekcji bootstrapowej i schodzące przez hierarchię kolekcji do obiektu. Na każdym poziomie dodawany jest znak '/'. -W naszym przykładzie gra uruchomi się z czterema obiektami: +W naszym przykładzie gra uruchomi się z następującymi czterema obiektami gry: - /team_1/bean - /team_1/buddy @@ -131,34 +130,34 @@ W naszym przykładzie gra uruchomi się z czterema obiektami: - /team_2/buddy ::: sidenote -Identyfikatory są przechowywane jako wartości hashowane (ang. hashed - od nazwy (funkcji skrótu -hash)[https://pl.wikipedia.org/wiki/Funkcja_skrótu]). Runtime przechowuje również stan hashowania dla każdej kolekcji, co pozwala kontynuować przeliczanie relatywnych ciągów na identyfikatory absolutne. +Identyfikatory są przechowywane jako wartości haszowane. Runtime przechowuje też stan haszowania dla każdego identyfikatora kolekcji, co służy do dalszego haszowania względnego ciągu znaków do identyfikatora bezwzględnego. ::: -W czasie działania grupowanie kolekcji znika. Nie da się ustalić, do której kolekcji należał dany obiekt przed kompilacją. Nie można też w prosty sposób manipulować wszystkimi obiektami z kolekcji naraz. Jeśli potrzebujesz takich operacji, samodzielnie je śledź w kodzie. Identyfikator każdego obiektu jest stały przez cały czas życia obiektu. Oznacza to, że bezpiecznie można go przechować i użyć później. +W czasie działania grupowanie kolekcji nie istnieje. Nie da się ustalić, do której kolekcji należał dany obiekt przed kompilacją. Nie można też manipulować wszystkimi obiektami w kolekcji naraz. Jeśli potrzebujesz takich operacji, możesz łatwo śledzić je samodzielnie w kodzie. Identyfikator każdego obiektu jest statyczny i pozostaje niezmienny przez cały czas jego życia. Oznacza to, że możesz go bezpiecznie przechowywać i używać później. -## Adresowanie absolutne +## Adresowanie bezwzględne -Można też używać pełnych identyfikatorów opisanych powyżej. W większości przypadków preferuje się adresowanie relatywne, bo umożliwia ponowne użycie zawartości, ale zdarzają się sytuacje, gdy konieczne jest adresowanie absolutne. +Można też używać pełnych identyfikatorów opisanych powyżej. W większości przypadków preferowane jest adresowanie względne, ponieważ ułatwia ponowne wykorzystanie zawartości, ale bywają sytuacje, w których potrzebne jest adresowanie bezwzględne. -Na przykład wyobraź sobie menedżera AI, który śledzi stan każdej fasolki. Chcesz, żeby fasolki raportowały swój status do menedżera, a on na podstawie tych informacji podejmował decyzje i wydawał rozkazy. W takim przypadku sensowne jest stworzenie jednego obiektu gry z komponentem skryptowym i umieszczenie go w głównej kolekcji bootstrapowej obok instancji zespołów. +Na przykład wyobraź sobie menedżera AI, który śledzi stan każdego obiektu bean. Chcesz, aby beany raportowały mu swój status, a menedżer na tej podstawie podejmował decyzje taktyczne i wydawał im polecenia. W takim przypadku sensowne jest utworzenie jednego obiektu gry z komponentem skryptowym i umieszczenie go w głównej kolekcji bootstrapowej obok instancji zespołów. ![manager object](images/addressing/manager_editor.png) -Każda "fasolka" odpowiada za wysyłanie wiadomości statusowych do menedżera: "contact" gdy zauważy wroga lub "ouch!" gdy dostanie obrażenia. Żeby to zadziałało, skrypt obiektu fasolki wykorzystuje absolutny adres, aby wysłać wiadomość do komponentu "controller" obiektu "manager". +Każdy bean odpowiada za wysyłanie wiadomości statusowych do menedżera: "contact", gdy zauważy wroga, albo "ouch!", gdy otrzyma obrażenia. Aby to zadziałało, skrypt beana używa adresowania bezwzględnego, by wysłać wiadomość do komponentu "controller" obiektu "manager". -Każdy adres rozpoczynający się od '/' jest rozwiązywany względem korzenia świata gry. Odpowiada to korzeniowi *kolekcji bootstrapowej*, która ładuje się przy starcie gry. +Każdy adres zaczynający się od '/' jest rozwiązywany względem korzenia świata gry. Odpowiada to korzeniowi *kolekcji bootstrapowej*, która jest ładowana przy starcie gry. -Absolutnym adresem skryptu menedżera jest `"/manager#controller"` i niezależnie od miejsca użycia zawsze wskaże właściwy komponent. +Bezwzględny adres skryptu menedżera to `"/manager#controller"` i niezależnie od miejsca użycia zawsze wskaże właściwy komponent. ![teams and manager](images/addressing/teams_manager.png) ![absolute addressing](images/addressing/absolute.png) -## Identyfikatory haszowane (skrócone) +## Haszowane identyfikatory -Silnik przechowuje wszystkie identyfikatory jako wartości haszowane. Wszystkie funkcje przyjmujące jako argument komponent lub obiekt gry akceptują string, hash lub obiekt URL. Powyżej pokazywaliśmy adresowanie z użyciem stringów. +Silnik przechowuje wszystkie identyfikatory jako wartości haszowane. Wszystkie funkcje przyjmujące jako argument komponent lub obiekt gry akceptują string, hash albo obiekt URL. Powyżej pokazywaliśmy adresowanie z użyciem stringów. -Kiedy pobierasz identyfikator obiektu, silnik Defold zawsze zwraca haszowaną ścieżkę absolutną: +Gdy pobierasz identyfikator obiektu, silnik Defold zawsze zwraca haszowaną ścieżkę bezwzględną: ```lua local my_id = go.get_id() @@ -168,10 +167,10 @@ local spawned_id = factory.create("#some_factory") print(spawned_id) --> hash: [/instance42] ``` -Możesz użyć takiego identyfikatora zamiast stringa albo samodzielnie go skonstruować. Pamiętaj jednak, że haszowany identyfikator odpowiada ścieżce do obiektu, czyli adresowi absolutnemu: +Możesz użyć takiego identyfikatora zamiast stringa albo samodzielnie go utworzyć. Pamiętaj jednak, że haszowany identyfikator odpowiada ścieżce obiektu, czyli adresowi bezwzględnemu: ::: sidenote -Powodem, dla którego adresy relatywne muszą być podawane jako stringi, jest fakt, że silnik buduje nowy identyfikator haszowany na podstawie stanu haszowania aktualnego kontekstu nazewniczego (kolekcji) z dopisanym ciągiem tekstowym. +Powodem, dla którego adresy względne muszą być podawane jako stringi, jest to, że silnik oblicza nowy identyfikator haszowany na podstawie stanu haszowania bieżącego kontekstu nazewniczego, czyli kolekcji, do której dodaje podany ciąg znaków. ::: ```lua @@ -182,66 +181,66 @@ go.set_position(pos, spawned_id) local other_id = hash("/path/to/the/object") go.set_position(pos, other_id) --- This will not work! Relative addresses must be given as strings. +-- To nie zadziała! Adresy względne muszą być podawane jako stringi. local relative_id = hash("my_object") go.set_position(pos, relative_id) ``` -## URL +## URL-e -Żeby dopełnić obraz, spójrzmy na pełny format adresu w silniku Defold: URL. +Żeby dopełnić obraz, spójrzmy na pełny format adresu w Defold: URL. -URL to obiekt, zwykle zapisywany jako specjalnie sformatowany string. Ogólny format URL-a wygląda tak: +URL to obiekt, zwykle zapisywany jako specjalnie sformatowany string. Ogólny format URL wygląda tak: `[socket:][path][#fragment]` socket -: Identyfikuje świat gry, do którego należy cel (instancję kolekcji). Jest to istotne podczas pracy z [Pełnomocnikami kolekcji (Collection Proxy)](/manuals/collection-proxy) i służy do określenia _dynamicznie załadowanej kolekcji_. +: Identyfikuje świat gry, do którego należy cel. Jest to ważne podczas pracy z [pełnomocnikami kolekcji](/manuals/collection-proxy) i służy do określenia _dynamicznie załadowanej kolekcji_. path -: Ta część adresu URL zawiera pełny identyfikator docelowego obiektu gry. +: Ta część URL zawiera pełny identyfikator docelowego obiektu gry. fragment -: Identyfikator komponentu znajdującego się pod wskazanym obiektem gry. +: Identyfikator komponentu w obrębie wskazanego obiektu gry. -Jak widzieliśmy wcześniej, w większości przypadków można pominąć niektóre fragmenty adresu. Zwykle nie trzeba podawać socketu, a czasami nie trzeba też podawać ścieżki. Gdy jednak chcesz odwołać się do świata innego niż aktualny, musisz określić socket. Przykładowo pełny string URL-a skryptu "controller" obiektu "manager" to: +Jak widzieliśmy wcześniej, w większości przypadków można pominąć część informacji. Zwykle nie trzeba podawać socketu, a często, ale nie zawsze, trzeba podać path. Gdy jednak musisz adresować coś w innym świecie gry, trzeba określić socket. Na przykład pełny string URL skryptu "controller" w obiekcie "manager" wygląda tak: `"main:/manager#controller"` -a kontroler kolegi z "team_2" to: +a kontroler buddy'ego z "team_2" to: `"main:/team_2/buddy#controller"` -Możemy wysyłać wiadomości do tych komponentów: +Możemy wysyłać do nich wiadomości: ```lua --- Send "hello" to the manager script and team buddy bean +-- Wyślij "hello" do skryptu menedżera i beana z zespołu msg.post("main:/manager#controller", "hello_manager") msg.post("main:/team_2/buddy#controller", "hello_buddy") ``` ## Konstruowanie obiektów URL -Obiekty URL można także tworzyć programowo w kodzie Lua: +Obiekty URL można też konstruować programowo w kodzie Lua: ```lua --- Construct URL object from a string: +-- Utwórz obiekt URL z stringa: local my_url = msg.url("main:/manager#controller") print(my_url) --> url: [main:/manager#controller] -print(my_url.socket) --> 786443 (internal numeric value) +print(my_url.socket) --> 786443 (wewnętrzna wartość numeryczna) print(my_url.path) --> hash: [/manager] print(my_url.fragment) --> hash: [controller] --- Construct URL from parameters: +-- Utwórz URL z parametrów: local my_url = msg.url("main", "/manager", "controller") print(my_url) --> url: [main:/manager#controller] --- Build from empty URL object: +-- Zbuduj z pustego obiektu URL: local my_url = msg.url() -my_url.socket = "main" -- specify by valid name -my_url.path = hash("/manager") -- specify as string or hash -my_url.fragment = "controller" -- specify as string or hash +my_url.socket = "main" -- podaj poprawną nazwę +my_url.path = hash("/manager") -- podaj jako string lub hash +my_url.fragment = "controller" -- podaj jako string lub hash --- Post to target specified by URL +-- Wyślij wiadomość do celu wskazanego przez URL msg.post(my_url, "hello_manager!") ``` diff --git a/docs/pl/manuals/android.md b/docs/pl/manuals/android.md index ea1eee07..58feb833 100644 --- a/docs/pl/manuals/android.md +++ b/docs/pl/manuals/android.md @@ -1,144 +1,103 @@ --- -title: Rzwój oprogramowania w Defoldzie na platformę Android -brief: Instrukcja odpowiada na pytania jak zbudować i uruchomić grę lub aplikację stworzoną w Defoldzie na urządzeniach z systemem Android. +title: Tworzenie aplikacji Defold na platformie Android +brief: Ta instrukcja opisuje, jak budować i uruchamiać aplikacje Defold na urządzeniach z Androidem --- -# Android development +# Programowanie na Androidzie -Urządzenia z systemem Android pozwalają na swobodne otwieranie Twoich własnych aplikacji i gier. Jest bardzo łatwo zbudować wersję gry i skopiować ją na takie urządzenie. Instrukcja ta opisuje kroki procesu pakowania aplikacji na system Android. Podczas tworzenia oprogramowania z Defoldem, otwieranie i testowanie Twojej gry poprzez specjalną aplikacją zwaną [development app](/manuals/dev-app) jest często preferowane, ponieważ umożliwia szybkie przeładowanie zawartości nawet podczas działania programu i programowanie urządzenia bezprzewodowo. +Urządzenia z Androidem pozwalają swobodnie uruchamiać na nich własne aplikacje. Bardzo łatwo jest zbudować wersję gry i skopiować ją na urządzenie z Androidem. Ta instrukcja wyjaśnia kolejne kroki pakowania gry na Androida. Podczas tworzenia często wygodniej jest uruchamiać grę przez [development app](/manuals/dev-app), ponieważ umożliwia szybkie przeładowywanie zawartości i kodu bezpośrednio na urządzeniu. -## Proces podpisywania Android i Google Play +## Proces podpisywania dla Androida i Google Play -Android wyamaga, aby aplikacje, które chcesz zainstalować na urządzeniu były cyfrowo podpisane. W przeciwieństwie do iOS, gdzie wszystkie certyfikaty są przyznawane przez Apple, Android umożliwia własnoręczne podpisanie aplikacji, więc można swobodnie tworzyć certyfikaty i klucze wymagane do podpisywania. +Android wymaga, aby wszystkie pliki APK były przed instalacją na urządzeniu lub aktualizacją cyfrowo podpisane certyfikatem. Jeśli używasz Android App Bundles, musisz podpisać tylko swój pakiet aplikacji przed przesłaniem go do Play Console, a [Play App Signing](https://developer.android.com/studio/publish/app-signing#app-signing-google-play) zajmie się resztą. Możesz też ręcznie podpisać aplikację przed wysłaniem do Google Play, do innych sklepów z aplikacjami lub do dystrybucji poza sklepami. -Proces tworzenia certyfikatów i kluczy może wyglądać na skomplikowany, ale podczas tworzenia oprogramowania Defold go automatyzuje. Kiedy tworzysz aplikację i pakujesz ją do paczki (ang. Android application bundle) możesz podać specyficzny certyfikat i klucz. Jeśli tego nie zrobisz, Defold wygeneruje je za Ciebie i podpisze aplikację automatycznie. +Gdy tworzysz pakiet aplikacji Android z edytora Defold albo za pomocą [narzędzia wiersza poleceń](/manuals/bob), możesz podać keystore, który zawiera certyfikat i klucz, oraz hasło do keystore. Te dane zostaną użyte do podpisania aplikacji. Jeśli ich nie podasz, Defold wygeneruje debug keystore i użyje go do podpisania pakietu aplikacji. -Ważne, aby zaapamiętać, że przy releasowaniu aplikacji na Google Play, będziesz musiał stworzyć certyfikat i klucz, którymi właśnie podpiszesz tę aplikację. Powodem tego jest to, że _podczas publikowania zaktualizowanej wersji aplikacji użyć musisz tego samego podpisu jak dotychczasowa wersja_. Jeśli podpiszesz aplikację innym kluczem, Google Play odrzuci aktualizację i będziesz musiał opublikować aplikację jako osobna, nowa aplikacja. +::: important +**Nigdy** nie przesyłaj aplikacji do Google Play, jeśli została podpisana za pomocą debug keystore. Zawsze używaj własnego, osobnego keystore. +::: -Możesz przeczytać więcej na ten temat na stronie [Google Play developer console](https://play.google.com/apps/publish/). +## Tworzenie keystore -## Tworzenie certyfikatów i kluczy +::: sidenote +Proces podpisywania Androida w Defold zmienił się w wersji 1.2.173: zamiast osobnego klucza i certyfikatu używa teraz keystore. [Więcej informacji w tym poście na forum](https://forum.defold.com/t/upcoming-change-to-the-android-build-pipeline/66084). +::: -Musisz stworzyć certyfikaty w formacie *.pem*, a klucze w formacie *.pk8*. Możesz je wygenerować korzystając z narzędzia `openssl`: +Keystore możesz utworzyć [w Android Studio](https://developer.android.com/studio/publish/app-signing#generate-key) albo z poziomu terminala / wiersza poleceń: -```sh -$ openssl genrsa -out key.pem 2048 -$ openssl req -new -key key.pem -out request.pem -$ openssl x509 -req -days 9999 -in request.pem -signkey key.pem -out certificate.pem -$ openssl pkcs8 -topk8 -outform DER -in key.pem -inform PEM -out key.pk8 -nocrypt +```bash +keytool -genkey -v -noprompt -dname "CN=John Smith, OU=Area 51, O=US Air Force, L=Unknown, ST=Nevada, C=US" -keystore mykeystore.keystore -storepass 5Up3r_53cR3t -alias myAlias -keyalg RSA -validity 9125 ``` -Uzyskasz dzięki temu pliki *certificate.pem* i *key.pk8*, które użyjesz do podpisania aplikacji. +To utworzy plik keystore o nazwie `mykeystore.keystore`, zawierający klucz i certyfikat. Dostęp do klucza i certyfikatu będzie chroniony hasłem `5Up3r_53cR3t`. Klucz i certyfikat będą ważne przez 25 lat, czyli 9125 dni. Wygenerowany klucz i certyfikat będą identyfikowane aliasem `myAlias`. ::: important -Upewnij się, że przechowywujesz certyfikaty i klucze w bezpiecznym miejscu. Jeśli je zgubisz, _nie będziesz mógł_ w żaden sposób zaktualizować aplikacji na Google Play. +Pamiętaj, aby przechowywać keystore i powiązane z nim hasło w bezpiecznym miejscu. Jeśli sam podpisujesz i przesyłasz aplikacje do Google Play, a keystore lub jego hasło zostanie utracone, nie będzie żadnego sposobu, aby zaktualizować aplikację w Google Play. Możesz tego uniknąć, korzystając z Google Play App Signing i pozwalając Google podpisywać aplikacje za Ciebie. ::: -## Tworzenie paczki - Android application bundle +## Tworzenie pakietu aplikacji Android -Edytor Defold umożliwia łatwe stworzenie paczki z aplikacją. Przed pakowaniem określasz, których ikon należy używać, wersję produktu itd. w pliku *game.project*. Więcej tutaj: [plik konfiguracyjny projektu](/manuals/project-settings/#android). +Edytor pozwala łatwo utworzyć samodzielny pakiet aplikacji dla gry. Przed pakowaniem możesz określić, której ikony lub których ikon użyć dla aplikacji, ustawić kod wersji itd. w pliku *game.project* [plik ustawień projektu](/manuals/project-settings/#android). -Aby stworzyć paczkę kliknij Project ▸ Bundle... ▸ Android Application... w menu. +Aby spakować grę, wybierz Project ▸ Bundle... ▸ Android Application... z menu. -Jeśli chcesz, aby Defold automatycznie stworzył certyfikat, zostaw pola *Certificate* i *Private key* puste: +Jeśli chcesz, aby edytor automatycznie tworzył losowe debug certyfikaty, pozostaw pola *Keystore* i *Keystore password* puste: ![Signing Android bundle](images/android/sign_bundle.png) -Jeśli chcesz podpisać paczkę własnym certyfikatem i kluczem, wskaż odpowiednie pliki *.pem* i *.pk8*: +Jeśli chcesz podpisać pakiet konkretnym keystore, wskaż pola *Keystore* i *Keystore password*. Oczekuje się, że *Keystore* będzie miał rozszerzenie pliku `.keystore`, a hasło ma być zapisane w pliku tekstowym z rozszerzeniem `.txt`. Można też podać *Key password*, jeśli klucz w keystore ma inne hasło niż sam keystore: ![Signing Android bundle](images/android/sign_bundle2.png) -Defold wspiera tworzenie zarówno paczek APK i AAB. Wybierz APK lub AAB z rozwijanej listy "Bundle Format". +Defold obsługuje tworzenie zarówno plików APK, jak i AAB. Wybierz APK albo AAB z listy rozwijanej Bundle Format. -Kliknij Create Bundle po skonfigurowaniu wszystkich ustawień. Będziesz poproszony o wskazanie lokalizacji na Twoim urządzeniu do zapisania zbudowanej paczki. +Naciśnij Create Bundle, gdy skonfigurujesz ustawienia pakietu aplikacji. Zostaniesz wtedy poproszony o wskazanie miejsca na komputerze, w którym pakiet ma zostać utworzony. ![Android Application Package file](images/android/apk_file.png) -:[Build Variants](../shared/build-variants.md) +:[Warianty budowania](../shared/build-variants.md) -### Instalowanie paczek na Androidzie +### Instalowanie pakietu aplikacji Android #### Instalowanie APK -Plik *.apk* może być skopiowany na Twoje urządzenie z systemem Android przy użyciu narzędzia `adb` (zobacz poniżej) lub załadowane do Google Play poprzez [Google Play developer console](https://play.google.com/apps/publish/). +Plik *`.apk`* można skopiować na urządzenie za pomocą narzędzia `adb` albo przesłać do Google Play przez [konsolę deweloperską Google Play](https://play.google.com/apps/publish/). -``` +:[Android ADB](../shared/android-adb.md) + +```bash $ adb install Defold\ examples.apk 4826 KB/s (18774344 bytes in 3.798s) pkg: /data/local/tmp/my_app.apk Success ``` -#### Instalowanie AAB - -Plik *.aab* może być załadowany do Google Play poprzez [Google Play developer console](https://play.google.com/apps/publish/). Jest również możliwe wygenerowanie pliku *.apk* z pliku *.aab*, aby zainstalować je lokalnie dzięki [Android bundletool](https://developer.android.com/studio/command-line/bundletool). +#### Instalowanie APK z poziomu edytora -## Pozwolenia +Plik *`.apk`* możesz zainstalować i uruchomić za pomocą pól wyboru edytora Install on connected device i Launch installed app w oknie Bundle: -Silnik Defold wymaga niektórych pozwoleń, aby wszystkie jego elementy mogły działać. Pozwolenia są zdefiniowane w pliku `AndroidManifest.xml`, wybranym w pliku *game.project*: [plik konfiguracyjny projektu](/manuals/project-settings/#android). Możesz dowiedzieć się więcej na temat pozwoleń w systemie Android w [oficjalnej dokumenetacji](https://developer.android.com/guide/topics/permissions/overview). Następujące pozwolenia są wymagane przy użyciu domyślnego pliku manifest: - -### android.permission.INTERNET i android.permission.ACCESS_NETWORK_STATE (Protection level: normal) -Pozwala aplikacji na otwieranie połączeń internetowych i uzyskiwaniu informacji na temat sieci. Potrzebne są przy dostępie do Internetu. ([Android official docs](https://developer.android.com/reference/android/Manifest.permission#INTERNET)) i ([Android official docs](https://developer.android.com/reference/android/Manifest.permission#ACCESS_NETWORK_STATE)). +![instalowanie i uruchamianie APK](images/android/install_and_launch.png) -### android.permission.WRITE_EXTERNAL_STORAGE (Protection level: dangerous) -Pozwala aplikacji na zapisywanie do pamięci zewnętrznej. Od poziomu 19 API to pozwolenie nie jest wymagane do zapisu i odczytu plików w lokalizacji przeznaczonej dla Twojej aplikacji (otrzymanej przez Context.getExternalFilesDir(String) i Context.getExternalCacheDir()). To pozwolenie jest wymagane, gdy chcesz zapisywać do lub odczytywać dane z plików z dysku (używając metod z io.* lub sys.save/load) poza lokalizacją wskazaną przez [sys.get_save_file()](/ref/sys/#sys.get_save_file:application_id-file_name) i mając `android:minSdkVersion` ustawione na mniejsze niż 19 w pliku manifest. ([Android official docs](https://developer.android.com/reference/android/Manifest.permission#WRITE_EXTERNAL_STORAGE)). +Aby ta funkcja działała, musisz mieć zainstalowany ADB oraz włączone USB debugging na podłączonym urządzeniu. Jeśli edytor nie potrafi wykryć lokalizacji narzędzia wiersza poleceń ADB, musisz ją wskazać w [preferencjach edytora](/manuals/editor-preferences/#tools). -### android.permission.WAKE_LOCK (Protection level: normal) -Pozwala na użwanie PowerManagera, aby powstrzymać procesor przed przyciemnianiem ekranu lub wygaszaniem. Potrzebne jest do tego, by tymczasowo powstrzymać urządzenie przed uśpieniem podczas otrzymywania powiadomień. ([Android official docs](https://developer.android.com/reference/android/Manifest.permission#WAKE_LOCK)) - - -## Narzędzie adb - Android Debug Bridge - -Narzędzie `adb` jest łatwym i wszechstronnym programem do interakcji z urządzeniami z systemem Android. Możesz ściągnąć je i zainstalować jako część Android SDK Platform-Tools, dla systemów Mac, Linux czy Windows. - -Ściągnij Android SDK Platform-Tools z: [https://developer.android.com/studio/releases/platform-tools](https://developer.android.com/studio/releases/platform-tools). Znajdziesz narzędzie *adb* w */platform-tools/*. Alternatywnie, paczki dla konkretnych platform mogą zostać zainstalowane przez odpowiednie managery paczek. - -Na Ubuntu Linux: - -``` -$ sudo apt-get install android-tools-adb -``` - -Na Fedora 18/19: - -``` -$ sudo yum install android-tools -``` - -Na macOS (Homebrew) - -``` -$ brew cask install android-platform-tools -``` +#### Instalowanie AAB -Możesz sprawdzić czy `adb` działa łącząc Twoje urządzenie z systemem Android do Twojego komputera przez USB i użyć komendy: +Plik *.aab* można przesłać do Google Play przez [konsolę deweloperską Google Play](https://play.google.com/apps/publish/). Można też wygenerować plik *`.apk`* z pliku *.aab*, aby zainstalować go lokalnie za pomocą [Android bundletool](https://developer.android.com/studio/command-line/bundletool). -``` -$ adb devices -List of devices attached -31002535c90ef000 device -``` +## Uprawnienia -Jeśli Twoje urządzenie się nie pojawi, upewnij się najpierw czy zezwolono na *USB debugging* na urządzeniu mobilnym. Otwórz ustawienia *Settings* i wyszukaj *Developer options* (lub *Development*). +Silnik Defold wymaga szeregu różnych uprawnień, aby działały wszystkie jego funkcje. Uprawnienia są definiowane w pliku `AndroidManifest.xml`, wskazanym w pliku *game.project* [plik ustawień projektu](/manuals/project-settings/#android). Więcej o uprawnieniach Androida można przeczytać w [oficjalnej dokumentacji](https://developer.android.com/guide/topics/permissions/overview). W domyślnym manifeście są wymagane następujące uprawnienia: -![Enable USB debugging](images/android/usb_debugging.png) +### android.permission.INTERNET i android.permission.ACCESS_NETWORK_STATE (Protection level: normal) +Pozwalają aplikacjom otwierać gniazda sieciowe i uzyskiwać informacje o sieciach. Te uprawnienia są potrzebne do korzystania z Internetu. ([oficjalna dokumentacja Androida](https://developer.android.com/reference/android/Manifest.permission#INTERNET)) oraz ([oficjalna dokumentacja Androida](https://developer.android.com/reference/android/Manifest.permission#ACCESS_NETWORK_STATE)). -## Debugowanie paczki z aplikacją +### android.permission.WAKE_LOCK (Protection level: normal) +Pozwala używać PowerManager WakeLocks, aby zapobiec usypianiu procesora lub wygaszaniu ekranu. To uprawnienie jest potrzebne do tymczasowego powstrzymania urządzenia przed przejściem w stan uśpienia podczas odbierania powiadomienia push. ([oficjalna dokumentacja Androida](https://developer.android.com/reference/android/Manifest.permission#WAKE_LOCK)) -Paczka zbudowana w trybie Debug silnika (czyli z opcją "Debug" zaznaczoną podczas budowania paczki) będzie wysyłać wszystkie swoje logi do systemu Android. Uzyskaj dostęp do tych logów przez narzędzie `adb` używając komendy`logcat`. Prawdopodobnie też będziesz chcieć przefiltrować wynik używając tagu (`-s [tagname]`): +## Korzystanie z AndroidX +AndroidX to duże ulepszenie oryginalnej Android Support Library, która nie jest już rozwijana. Pakiety AndroidX całkowicie zastępują Support Library, zapewniając pełną zgodność funkcji i nowe biblioteki. Większość rozszerzeń Androida w [Portalu zasobów (Asset Portal)](/assets) obsługuje AndroidX. Jeśli nie chcesz używać AndroidX, możesz je jawnie wyłączyć na rzecz starej Android Support Library, zaznaczając `Use Android Support Lib` w [manifeście aplikacji](https://defold.com/manuals/app-manifest/). -``` -$ adb logcat -s "defold" ---------- beginning of /dev/log/system ---------- beginning of /dev/log/main -I/defold ( 6210): INFO:DLIB: SSDP started (ssdp://192.168.0.97:58089, http://0.0.0.0:38637) -I/defold ( 6210): INFO:ENGINE: Defold Engine 1.2.50 (8d1b912) -I/defold ( 6210): INFO:ENGINE: Loading data from: -I/defold ( 6210): INFO:ENGINE: Initialised sound device 'default' -I/defold ( 6210): -D/defold ( 6210): DEBUG:SCRIPT: Hello there, log! -... -``` +![](images/android/enable_supportlibrary.png) ## FAQ :[Android FAQ](../shared/android-faq.md) diff --git a/docs/pl/manuals/app-manifest.md b/docs/pl/manuals/app-manifest.md new file mode 100644 index 00000000..9c0d3d3c --- /dev/null +++ b/docs/pl/manuals/app-manifest.md @@ -0,0 +1,119 @@ +--- +title: Manifest aplikacji +brief: Ta instrukcja wyjaśnia, jak manifest aplikacji służy do wykluczania funkcji z silnika. +--- + +# Manifest aplikacji + +Manifest aplikacji służy do wykluczania funkcji z silnika albo do określania, które z nich mają zostać do niego dołączone. Wykluczanie nieużywanych funkcji silnika to zalecana praktyka, ponieważ zmniejsza końcowy rozmiar pliku binarnego gry. +Manifest aplikacji zawiera też kilka opcji sterujących kompilacją kodu dla platformy HTML5, takich jak minimalna obsługiwana wersja przeglądarki i ustawienia pamięci. Te opcje również mogą wpływać na rozmiar wynikowego pliku binarnego. + +![](images/app_manifest/create-app-manifest.png) + +![](images/app_manifest/app-manifest.png) + +# Stosowanie manifestu + +W pliku `game.project` przypisz manifest w `Native Extensions` -> `App Manifest`. + +## Physics + +Określa, którego silnika fizyki użyć, albo pozwala wybrać None, aby całkowicie wykluczyć fizykę. + +## Physics 2d + +Wybiera, której wersji Box2D użyć. + +## Rig + Model + +Steruje funkcjami rig i model albo pozwala wybrać None, aby całkowicie wykluczyć model i rig. Zobacz dokumentację [`Model`](https://defold.com/manuals/model/#model-component). + + +## Exclude Record + +Wyklucza z silnika możliwość nagrywania wideo (zobacz dokumentację wiadomości [`start_record`](https://defold.com/ref/stable/sys/#start_record)). + + +## Exclude Profiler + +Wyklucza profiler z silnika. Profiler służy do zbierania danych o wydajności oraz liczników użycia. Więcej informacji o korzystaniu z profilera znajdziesz w [podręczniku profilowania](/manuals/profiling/). + + +## Exclude Sound + +Wyklucza z silnika wszystkie możliwości odtwarzania dźwięku. + + +## Exclude Input + +Wyklucza z silnika całą obsługę wejścia. + + +## Exclude Live Update + +Wyklucza z silnika [funkcję Live Update](/manuals/live-update). + + +## Exclude Image + +Wyklucza z silnika moduł skryptowy `image`. Więcej informacji znajdziesz w [dokumentacji](https://defold.com/ref/stable/image/). + + +## Exclude Types + +Wyklucza z silnika moduł skryptowy `types`. Więcej informacji znajdziesz w [dokumentacji](https://defold.com/ref/stable/types/). + + +## Exclude Basis Universal + +Wyklucza z silnika [bibliotekę kompresji tekstur Basis Universal](/manuals/texture-profiles). + + +## Use Android Support Lib + +Korzysta z przestarzałej biblioteki Android Support Library zamiast AndroidX. [Więcej informacji](https://defold.com/manuals/android/#using-androidx). + + +## Graphics + +Określa, którego backendu graficznego użyć. + +* OpenGL - Dołącza tylko OpenGL. +* Vulkan - Dołącza tylko Vulkan. +* OpenGL and Vulkan - Dołącza zarówno OpenGL, jak i Vulkan. Vulkan będzie używany domyślnie, a jeśli nie będzie dostępny, silnik przełączy się na OpenGL. + +## Use full text layout system + +Jeśli ta opcja jest włączona (`true`), umożliwia generowanie w czasie działania fontów typu SDF przy użyciu fontów TrueType (`.ttf`) w projekcie. Więcej szczegółów znajdziesz w [podręczniku fontów](https://defold.com/manuals/font/#enabling-runtime-fonts). + + +## Minimum Safari version (js-web and wasm-web only) +Nazwa pola YAML: **`minSafariVersion`** +Wartość domyślna: **90000** + +Minimalna obsługiwana wersja Safari. Nie może być mniejsza niż 90000. Więcej informacji znajdziesz w [opcjach kompilatora Emscripten](https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=environment#min-safari-version). + +## Minimum Firefox version (js-web and wasm-web only) +Nazwa pola YAML: **`minFirefoxVersion`** +Wartość domyślna: **34** + +Minimalna obsługiwana wersja Firefoxa. Nie może być mniejsza niż 34. Więcej informacji znajdziesz w [opcjach kompilatora Emscripten](https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=environment#min-firefox-version). + +## Minimum Chrome version (js-web and wasm-web only) +Nazwa pola YAML: **`minChromeVersion`** +Wartość domyślna: **32** + +Minimalna obsługiwana wersja Chrome. Nie może być mniejsza niż 32. Więcej informacji znajdziesz w [opcjach kompilatora Emscripten](https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=environment#min-chrome-version). + +## Initial memory (js-web and wasm-web only) +Nazwa pola YAML: **`initialMemory`** +Wartość domyślna: **33554432** + +Rozmiar pamięci przydzielanej aplikacji webowej. Jeśli ALLOW_MEMORY_GROWTH=0 (js-web), jest to całkowita ilość pamięci dostępna dla aplikacji webowej. Więcej informacji znajdziesz w [opcjach kompilatora Emscripten](https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=environment#initial-memory). Wartość podawana jest w bajtach. Zwróć uwagę, że musi ona być wielokrotnością rozmiaru strony WebAssembly (64KiB). +Ta opcja odnosi się do `html5.heap_size` w *game.project* ([więcej informacji](https://defold.com/manuals/html5/#heap-size)). Opcja skonfigurowana w manifeście aplikacji jest ustawiana podczas kompilacji i używana jako domyślna wartość `INITIAL_MEMORY`. Wartość z *game.project* nadpisuje wartość z manifestu aplikacji i jest używana w czasie działania. + +## Stack size (js-web and wasm-web only) +Nazwa pola YAML: **`stackSize`** +Wartość domyślna: **5242880** + +Rozmiar stosu aplikacji. Więcej informacji znajdziesz w [opcjach kompilatora Emscripten](https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=environment#stack-size). Wartość podawana jest w bajtach. diff --git a/docs/pl/manuals/application-lifecycle.md b/docs/pl/manuals/application-lifecycle.md index b0b28341..b628803d 100644 --- a/docs/pl/manuals/application-lifecycle.md +++ b/docs/pl/manuals/application-lifecycle.md @@ -1,63 +1,63 @@ --- -title: Cykl życia aplikacji w silniku Defold -brief: Przewodnik wyjaśnia cykl życia aplikacji zbudowanej w silniku Defold od uruchomienia do zamknięcia. +title: Podręcznik cyklu życia aplikacji Defold +brief: Ten podręcznik opisuje cykl życia gier i aplikacji w Defold. --- # Cykl życia aplikacji -Cykl życia aplikacji lub gry w silniku Defold jest zasadniczo prosty. Silnik przechodzi przez trzy główne fazy: inicjalizację, pętlę aktualizacyjną (gdzie aplikacja spędza większość czasu) oraz finalizację. +Cykl życia aplikacji lub gry w Defold jest w dużej skali prosty. Silnik przechodzi przez trzy etapy działania: inicjalizację, pętlę aktualizacji, w której aplikacja spędza większość czasu, oraz finalizację. ::: sidenote -Instrukcja odnosi się do wersji Defold 1.12.0. W tej wersji wprowadzono zmiany w procesie cyklu życia oraz nową funkcję `late_update()`. +Podręcznik dotyczy wersji Defold od 1.12.0. W wersji 1.12.0 wprowadzono zmiany związane z cyklem życia oraz nową funkcję `late_update()`. ::: -![Lifecycle overview](images/application_lifecycle/application_lifecycle.png) +![Przegląd cyklu życia](images/application_lifecycle/application_lifecycle.png) -W wielu przypadkach wystarczy ogólna wiedza o tym, jak działa silnik Defold. Jednak czasem trzeba poznać dokładną kolejność wykonywanych operacji. Ten dokument opisuje przebieg działania silnika od startu do zakończenia aplikacji. +W wielu przypadkach wystarcza podstawowe rozumienie wewnętrznego działania Defold. Czasem jednak można trafić na sytuacje brzegowe, w których kluczowa staje się dokładna kolejność wykonywania zadań przez silnik. Ten dokument opisuje, jak silnik uruchamia aplikację od startu do zakończenia. -Aplikacja zaczyna się od przygotowania wszystkiego, co jest potrzebne do działania silnika. Główna kolekcja zostaje załadowana, a silnik Defold wywołuje [`init()`](/ref/go#init) dla wszystkich załadowanych komponentów, które posiadają tę funkcję (zarówno w skryptach obiektów, jak i skryptach GUI). Dzięki temu można przeprowadzić własną inicjalizację. +Aplikacja zaczyna od zainicjalizowania wszystkiego, co jest potrzebne do uruchomienia silnika. Ładuje główną kolekcję i wywołuje [`init()`](/ref/go#init) na wszystkich załadowanych komponentach, które mają funkcję `init()` w Lua, czyli na komponentach skryptowych i komponentach GUI ze skryptami GUI. Dzięki temu można wykonać własną inicjalizację. -Następnie aplikacja wchodzi w pętlę aktualizacyjną, w której spędza większość swojego czasu. Każda klatka aktualizuje obiekty gry i komponenty. Wywoływane są funkcje [`update()`](/ref/go#update) zarówno w skryptach, jak i w skryptach GUI. Podczas tej fazy wiadomości są rozsyłane do odbiorców, odtwarzane są dźwięki, a wszystkie elementy graficzne są renderowane. +Następnie aplikacja przechodzi do pętli aktualizacji, w której spędza większość swojego czasu. W każdej klatce aktualizowane są obiekty gry i zawarte w nich komponenty. Wywoływane są funkcje [`update()`](/ref/go#update) w skryptach i skryptach GUI. W trakcie pętli aktualizacji wiadomości są rozsyłane do odbiorców, odtwarzane są dźwięki, a cała grafika jest renderowana. -W pewnym momencie cykl życia dobiega końca. Zanim aplikacja się zakończy, silnik wychodzi z pętli aktualizacyjnej i przechodzi do fazy finalizacyjnej. Przygotowuje wszystkie obiekty gry do usunięcia. Funkcje [`final()`](/ref/go#final) każdego komponentu są uruchamiane, co pozwala na własne procedury sprzątania. Potem obiekty są usuwane, a główna kolekcja zostaje zwolniona. +W pewnym momencie cykl życia aplikacji dobiega końca. Zanim aplikacja zostanie zamknięta, silnik wychodzi z pętli aktualizacji i wchodzi w etap finalizacji. Przygotowuje wszystkie załadowane obiekty gry do usunięcia. Wywoływane są funkcje [`final()`](/ref/go#final) wszystkich komponentów obiektów, co pozwala na własne sprzątanie. Potem obiekty są usuwane, a główna kolekcja zostaje zwolniona. -Wszystkie kroki zawarte w przejściu „dispatch messages” są pokazane osobno na końcu tego podręcznika, a na diagramach oznaczone ikoną koperty ze strzałką 📩. +Kroki wykonywane w przejściu ["rozsyłanie wiadomości"](#dispatching-messages) są dla przejrzystości pokazane na osobnym diagramie na końcu tego podręcznika i oznaczone na diagramach małą ikoną koperty ze strzałką 📩. -## Faza inicjalizacyjna +## Inicjalizacja -To tutaj zaczyna się gra, i jest to pierwszy etap uruchomienia. Można go podzielić na trzy podfazy: +To tutaj zaczyna się gra i jest to pierwszy krok działania uruchomionej aplikacji. Można go podzielić na 3 fazy: -![Initizalization](images/application_lifecycle/initialization.png) +![Inicjalizacja](images/application_lifecycle/initialization.png) -### Przedinicjalizacja (Preinitialization) +### Preinicjalizacja -W fazie `Preinitialization` silnik wykonuje wiele działań zanim załaduje główną (bootstrapową) kolekcję. Konfigurowany jest profiler pamięci, gniazda, grafika, wejścia (HID), dźwięk, fizyka i wiele innych subsystemów. Wczytywany jest także plik konfiguracyjny (*game.project*). +W fazie preinicjalizacji (`Preinitialization`) silnik wykonuje wiele kroków, zanim zostanie załadowana główna kolekcja bootstrapowa. Konfigurowane są profiler pamięci, gniazda, grafika, HID (urządzenia wejściowe), dźwięk, fizyka i wiele innych elementów. Ładowana i konfigurowana jest też konfiguracja aplikacji (*game.project*). -![Preinitialization](images/application_lifecycle/pre_init.png) +![Preinicjalizacja](images/application_lifecycle/pre_init.png) -Pierwszym punktem, w którym użytkownik kontroluje przepływ, jest wywołanie `init()` aktualnego render scriptu. +Pierwszym punktem wejścia, nad którym użytkownik ma kontrolę pod koniec inicjalizacji silnika, jest wywołanie funkcji `init()` bieżącego skryptu renderującego. -Główna kolekcja zostaje wtedy załadowana i zainicjalizowana. +Następnie ładowana i inicjalizowana jest główna kolekcja. -### Inicjalizacja kolekcji (Collection Init) +### Inicjalizacja kolekcji -Podczas fazy `Collection Init` wszystkie obiekty gry w kolekcji przypisują transformacje – przesunięcie, obrót i skalowanie – swoim dzieciom. Następnie wywoływane są funkcje `init()` wszystkich komponentów, które ją udostępniają. +W fazie inicjalizacji kolekcji (`Collection Init`) wszystkie obiekty gry w kolekcji przekazują swoje transformacje, czyli przesunięcie, obrót i skalę, swoim dzieciom. Potem wywoływane są funkcje `init()` wszystkich istniejących komponentów. -![Collection Init](images/application_lifecycle/collection_init.png) +![Inicjalizacja kolekcji](images/application_lifecycle/collection_init.png) ::: sidenote -Kolejność wywołań funkcji `init()` komponentów obiektów gry nie jest określona. Nie należy zakładać konkretnej kolejności inicjalizacji w obrębie tej samej kolekcji. +Kolejność wywoływania funkcji `init()` komponentów obiektów gry nie jest określona. Nie należy zakładać, że silnik inicjalizuje obiekty należące do tej samej kolekcji w jakiejkolwiek konkretnej kolejności. ::: -### Post Update podczas inicjalizacji +### Końcowa aktualizacja w inicjalizacji -Po inicjalizacji silnik wykonuje pełne przejście `Post Update` – to samo, które odbywa się po każdym kroku pętli `Update Loop`. Szczególnie ważne jest to, że w tej fazie można zainicjalizować nowo tworzone obiekty, wysłać wiadomości, oznaczyć obiekty do usunięcia itd. +Silnik wykonuje wtedy pełne przejście końcowej aktualizacji (`Post Update`) - dokładnie to samo, które później następuje po każdym kroku pętli aktualizacji (`Update Loop`). Jest ono wykonywane na końcu inicjalizacji, ponieważ kod w `init()` może wysyłać nowe wiadomości, polecać fabrykom tworzenie nowych obiektów, oznaczać obiekty do usunięcia i wykonywać inne działania. -![Post Update](images/application_lifecycle/post_init.png) +![Końcowa aktualizacja](images/application_lifecycle/post_init.png) -Ten etap zajmuje się dostarczeniem wiadomości, tworzeniem nowych obiektów przez fabryki oraz usuwaniem obiektów. Przejście `Post Update` zawiera sekwencję „dispatch messages”, która nie tylko rozsyła zakolejkowane wiadomości, ale także obsługuje wiadomości skierowane do pełnomocników kolekcji (collection proxies). W kolejnych krokach aktualizowane są stany proxy (enable, disable, init, final, loading, mark for unloading). +To przejście obsługuje dostarczanie wiadomości, faktyczne tworzenie obiektów przez fabryki oraz usuwanie obiektów. Zwróć uwagę, że przejście `Post Update` obejmuje sekwencję „rozsyłania wiadomości” (`dispatch messages`), która nie tylko dostarcza zakolejkowane wiadomości, ale także przetwarza wiadomości wysyłane do pełnomocników kolekcji. Wszystkie kolejne aktualizacje proxy, takie jak `enable`, `disable`, `init`, `final`, `loading` i `mark for unloading`, są wykonywane w tych krokach. -Możliwe jest załadowanie [collection proxy](/manuals/collection-proxy) w trakcie `init()`, zainicjalizowanie jego obiektów, a następnie zwolnienie kolekcji – i to wszystko jeszcze zanim zostanie wywołana pierwsza funkcja `update()` komponentu, czyli zanim silnik opuści fazę inicjalizacji i wejdzie w pętlę aktualizacyjną: +Możliwe jest załadowanie [pełnomocnika kolekcji (Collection Proxy)](/manuals/collection-proxy) w trakcie `init()`, upewnienie się, że wszystkie zawarte w nim obiekty zostały zainicjalizowane, a następnie wyładowanie kolekcji przez proxy - i wszystko to przed wywołaniem pierwszego `update()` komponentu, czyli zanim silnik opuści etap inicjalizacji i wejdzie do pętli aktualizacji: ```lua function init(self) @@ -66,7 +66,7 @@ function init(self) end function update(self, dt) - -- The proxy collection is unloaded before this code is reached. + -- Kolekcja proxy jest wyładowana, zanim ten kod zostanie wykonany. print("update()") end @@ -76,164 +76,164 @@ function on_message(self, message_id, message, sender) msg.post("#collectionproxy", "init") msg.post("#collectionproxy", "enable") msg.post("#collectionproxy", "unload") - -- The proxy collection objects’ init() and final() functions - -- are called before we reach this object’s update() + -- Funkcje init() i final() obiektów w kolekcji proxy + -- są wywoływane, zanim dotrzemy do update() tego obiektu end end ``` -## Pętla aktualizacyjna (Update Loop) +## Pętla aktualizacji -Pętla aktualizacyjna przebiega według określonej sekwencji w każdej klatce. Jej przebieg podzielony jest na pięć głównych faz: +Pętla aktualizacji przebiega w każdej klatce według określonej sekwencji. Można ją podzielić na 5 głównych faz: -![Update Loop](images/application_lifecycle/update_loop.png) +![Pętla aktualizacji](images/application_lifecycle/update_loop.png) -1. Input (odczyt i obsługa) -2. Update (obejmuje Fixed, Regular, Late oraz aktualizacje komponentów silnika) -3. Render Update -4. Post Update (zwalnianie kolekcji, tworzenie i usuwanie obiektów) -5. Frame Render (ostatnie renderowanie grafiki) +1. Wejście (przetwarzanie i obsługa) +2. Aktualizacja (w tym aktualizacje Fixed, Regular, Late oraz komponentów silnika) +3. Aktualizacja renderowania +4. Końcowa aktualizacja (wyładowywanie pełnomocników kolekcji, tworzenie i usuwanie obiektów gry) +5. Renderowanie klatki (końcowe renderowanie grafiki) -### Faza wejść (Input Phase) +### Faza wejścia -Wejścia są odczytywane z dostępnych urządzeń, mapowane zgodnie z [input bindings](/manuals/input) i rozsyłane dalej. Każdy obiekt gry, który zdobył `acquire_input_focus`, otrzymuje wejścia w funkcje `on_input()` wszystkich swoich komponentów. Jeżeli obiekt posiada zarówno skrypt komponentu, jak i komponent GUI, oba dostaną wejścia, pod warunkiem że oba mają przechwytywanie wejścia. +Wejście jest odczytywane z dostępnych urządzeń, mapowane zgodnie z [powiązaniami wejść](/manuals/input), a następnie rozsyłane. Każdy obiekt gry, który przechwycił fokus wejścia, otrzymuje wejście we wszystkich swoich komponentach przez funkcje `on_input()`. Obiekt gry ze skryptem komponentu i komponentem GUI ze skryptem GUI otrzyma wejście w obu funkcjach `on_input()`, o ile są zdefiniowane i o ile obiekt przechwycił fokus wejścia. -![Input Phase](images/application_lifecycle/input_phase.png) +![Faza wejścia](images/application_lifecycle/input_phase.png) -Jeżeli obiekt gry, który ma fokus wejścia, zawiera pełnomocników kolekcji, wejścia są przekazywane do komponentów wewnątrz tych proxy. Proces ten rekurencyjnie działa dla wszystkich włączonych proxy w obrębie włączonych proxy. +Każdy obiekt gry, który przechwycił fokus wejścia i zawiera komponenty pełnomocnika kolekcji, przekazuje wejście do komponentów wewnątrz kolekcji obsługiwanej przez tego pełnomocnika. Proces ten jest następnie wykonywany rekurencyjnie w kolejnych włączonych pełnomocnikach kolekcji. -### Faza aktualizacji (Update Phase) +### Faza aktualizacji -Faza `Update` zaczyna się dla głównej kolekcji, a następnie jest wywoływana rekurencyjnie dla każdego włączonego collection proxy. +Faza aktualizacji (`Update`) jest częścią pętli aktualizacji. Zaczyna się raz dla głównej kolekcji, a następnie działa rekurencyjnie dla każdego włączonego pełnomocnika kolekcji. -W obrębie kolekcji silnik Defold przetwarza callbacki według typu komponentu: dla każdego typu iteruje po wszystkich instancjach, które implementują daną fazę, wywołuje funkcję Lua, opróżnia wiadomości, a potem przechodzi do następnego typu. +W obrębie kolekcji Defold przetwarza callbacki według typu komponentu: iteruje po wszystkich instancjach typu komponentu, który implementuje daną fazę, wywołuje callback Lua dla każdej instancji, opróżnia wiadomości, a potem przechodzi do następnego typu komponentu. -Wysoki poziom kolejności callbacków Lua w komponentach typu *script* wygląda następująco: +Ogólna kolejność faz callbacków Lua dla komponentów *script* jest następująca: -1. `fixed_update()` – wywoływane `0..N` razy na klatkę (gdy używany jest stały krok czasu) -2. `update()` – wywoływane raz na klatkę -3. `late_update()` – wywoływane raz na klatkę +1. `fixed_update()` - wywoływane 0..N razy na klatkę (jeśli używany jest stały krok czasowy) +2. `update()` - wywoływane 1 raz na klatkę +3. `late_update()` - wywoływane 1 raz na klatkę -![Update Phase](images/application_lifecycle/update_phase.png) +![Faza aktualizacji](images/application_lifecycle/update_phase.png) -Każdy komponent obiektu gry w głównej kolekcji jest odwiedzany. Jeśli którykolwiek komponent posiada `fixed_update()`/`update()`/`late_update()`, to są one uruchamiane. Jeżeli komponent jest collection proxy, wszystkie komponenty tej kolekcji proxy są aktualizowane rekurencyjnie we wszystkich krokach fazy `Update`. +Każdy komponent obiektu gry w głównej kolekcji jest odwiedzany. Jeśli którykolwiek z tych komponentów ma skrypt z funkcją `fixed_update()`/`update()`/`late_update()`, to zostanie ona wywołana. Jeśli komponentem jest pełnomocnik kolekcji, każdy komponent w jego kolekcji jest aktualizowany rekurencyjnie we wszystkich krokach fazy `Update`. ::: sidenote -Kolejność wywołań funkcji `update()` komponentów nie jest określona. Nie należy zakładać konkretnego porządku aktualizacji obiektów należących do tej samej kolekcji. To samo dotyczy `fixed_update()` i `late_update()` (od wersji 1.12.0). +Kolejność wywoływania funkcji `update()` komponentów obiektów gry nie jest określona. Nie należy zakładać, że silnik aktualizuje obiekty należące do tej samej kolekcji w jakiejkolwiek konkretnej kolejności. To samo dotyczy `fixed_update()` i `late_update()` (od 1.12.0). ::: #### Fizyka -Dla komponentów collision object wiadomości fizyki (kolizje, wyzwalacze, odpowiedzi ray cast itd.) są rozsyłane do wszystkich komponentów, które implementują `on_message()` w obrębie danego obiektu gry. +Dla komponentów obiektów kolizji wiadomości fizyki, takich jak kolizje, wyzwalacze, odpowiedzi ray cast itd., są rozsyłane przez obejmujący je obiekt gry do wszystkich komponentów, które zawierają skrypt z funkcją `on_message()`. -Jeżeli do symulacji fizyki używany jest [fixed timestep](/manuals/physics/#physics-updates), to funkcje `fixed_update()` są wywoływane we wszystkich komponentach skryptowych. Ta funkcja jest przydatna do stabilnego sterowania obiektami fizycznymi. +Jeśli do symulacji fizyki używany jest [stały krok czasowy](/manuals/physics/#physics-updates), może też dojść do wywołania funkcji `fixed_update()` we wszystkich komponentach skryptowych. Ta funkcja jest przydatna w grach opartych na fizyce, gdy chcesz manipulować obiektami fizycznymi w regularnych odstępach czasu, aby uzyskać stabilną symulację. -#### Transformaty +#### Transformacje -Przed każdą aktualizacją typu komponentu, wielokrotnie w trakcie `Update Loop`, jeśli jest to potrzebne, aktualizowane są transformaty – przesunięcie, obrót i skala obiektów, ich komponentów i obiektów potomnych. +Przed **każdą** aktualizacją typu komponentu, wielokrotnie w trakcie pętli aktualizacji (`Update Loop`), jeśli jest to potrzebne, aktualizowane są transformacje, czyli zastosowanie ruchu, obrotu i skali obiektów gry do każdego komponentu obiektu gry i do wszystkich potomnych komponentów obiektów gry. -Na końcu `Update Loop` wykonywana jest jeszcze jedna finalna aktualizacja transformacji, jeśli jest to wymagane. +Na końcu pętli aktualizacji (`Update Loop`) wykonywana jest jeszcze jedna końcowa aktualizacja transformacji, jeśli jest to potrzebne. -#### Faza silnika bez fixed update +#### Faza aktualizacji silnika bez fixed updates -Poniższe tabele opisują aktualizacje na poziomie silnika. Pomijają dokładną kolejność priorytetów komponentów (to szczegół implementacji), ale oddają gwarancje ważne dla skryptów: +Poniższe tabele opisują przejścia aktualizacji na poziomie silnika. Celowo pomijają dokładną wewnętrzną kolejność priorytetów komponentów, ponieważ jest to szczegół implementacyjny silnika, ale pokazują gwarancje istotne dla skryptów: - `fixed_update()` działa przed `update()` - `late_update()` działa po `update()` -- wiadomości są rozsyłane między aktualizacjami typu komponentu oraz między etapami callbacków skryptowych +- wiadomości są opróżniane między aktualizacjami typów komponentów oraz między etapami callbacków skryptowych -Gdy `Use Fixed Timestep` jest ustawione na `false` i/lub `Fixed Update Frequency` wynosi `0`, na początku faza przygotowuje `dt`, a następnie przebieg jest następujący: +Gdy `Use Fixed Timestep` ma wartość `false` i/lub Fixed Update Frequency ma wartość `0`, na początku fazy przygotowywane jest `dt`, a potem przebieg wygląda tak, jak w tabeli poniżej: -::: sidenote -Po każdej aktualizacji typu komponentu wszystkie wiadomości są rozsyłane – w tabelach nie pokazano tego dla przejrzystości. +:::sidenote +Zwróć uwagę, że po **każdej** aktualizacji typu komponentu wszystkie wiadomości są rozsyłane - nie zaznaczono tego w tabeli poniżej, żeby zachować jej czytelność. ::: | Krok | Faza silnika | Callback Lua | Komentarz | |-|-|-|-| -| 1 | **Update** | `update()` | Wywoływane raz na klatkę dla każdego typu komponentu implementującego Update według wewnętrznego priorytetu. Animacje właściwości GO zaczęte przez `go.animate()` działają tu jako oddzielny typ komponentu. Aktualizowane są również komponenty fizyki. Dla każdego włączonego collection proxy cała faza `Update` jest wykonywana rekurencyjnie od kroku 1. | -| 2 | **Late Update** | `late_update()` | Wywoływane raz na klatkę dla każdego typu komponentu implementującego Late Update zgodnie z priorytetem. | -| 3 | **Transforms** | | Na końcu przeprowadzana jest dodatkowa aktualizacja transformacji dla każdego komponentu, jeśli jest to potrzebne. | +| 1 | **Update** | `update()` | Wywoływane raz na klatkę dla każdego typu komponentu, który implementuje Update, zgodnie z wewnętrzną kolejnością priorytetów. Dodatkowo animacje właściwości GO uruchomione przez `go.animate()` są tu aktualizowane jako oddzielny typ komponentu. Aktualizowane są tu również komponenty **Physics**. Dla każdego włączonego Collection Proxy cała faza `Update` jest wywoływana rekurencyjnie od kroku 1. | +| 2 | **Late Update** | `late_update()` | Wywoływane raz na klatkę dla każdego typu komponentu, który implementuje Late Update, zgodnie z wewnętrzną kolejnością priorytetów. | +| 3 | **Transformacje** | | Na końcu wykonywana jest jeszcze jedna końcowa aktualizacja transformacji dla każdego komponentu, jeśli jest to potrzebne. | -#### Faza silnika z fixed timestep +#### Faza aktualizacji silnika ze stałym krokiem czasowym -Gdy `Use Fixed Timestep` ma wartość `true`, a `Fixed Update Frequency` jest różna od zera, na początku faza przygotowuje `dt`, `fixed_dt` oraz `num_fixed_steps` (`0..N`) – czyli ile razy zostanie wywołana funkcja fixed update, określone przez czas od ostatniej aktualizacji, aby zachować stałą liczbę kroków. +Gdy `Use Fixed Timestep` ma wartość `true`, a Fixed Update Frequency jest różne od zera, na początku fazy przygotowywane są `dt` (delta time), `fixed_dt` i `num_fixed_steps` (`0..N`) - czyli liczba wywołań fixed update, wyznaczona na podstawie czasu od ostatniej aktualizacji, aby zachować stałą liczbę aktualizacji. -::: sidenote -Po każdej aktualizacji typu komponentu wszystkie wiadomości są rozsyłane – tabelki tego nie pokazują dla przejrzystości. +:::sidenote +Zwróć uwagę, że po **każdej** aktualizacji typu komponentu wszystkie wiadomości są rozsyłane - nie zaznaczono tego w tabeli poniżej, żeby zachować jej czytelność. ::: -Potem faza przebiega w pętli: +Potem faza działa w pętli: | Krok | Faza silnika | Callback Lua | Komentarz | |-|-|-|-| -| 1 | **Fixed Update** | `fixed_update()` | Wywoływana `0..N` razy na klatkę dla każdego typu komponentu implementującego Fixed Update według priorytetu. Zawiera również Fixed Update komponentów fizyki. | -| 2 | **Update** | `update()` | Wywoływana raz na klatkę dla każdego typu komponentu implementującego Update według priorytetu. Animacje właściwości GO uruchomione przez `go.animate()` działają tu jako oddzielny typ komponentu. Dla każdego włączonego collection proxy faza `Update` jest wykonywana rekurencyjnie, zaczynając od kroku 1. | -| 3 | **Late Update** | `late_update()` | Wywoływana raz na klatkę dla każdego typu komponentu implementującego Late Update według priorytetu. | -| 4 | **Transforms** | | Na końcu przeprowadzana jest dodatkowa aktualizacja transformacji dla każdego komponentu, jeśli jest to potrzebne. | +| 1 | **Fixed Update** | `fixed_update()` | Wywoływane `0..N` razy na klatkę, zależnie od czasu, dla każdego typu komponentu, który implementuje Fixed Update, zgodnie z wewnętrzną kolejnością priorytetów. Obejmuje to etapy Fixed Update komponentów *Physics*. | +| 2 | **Update** | `update()` | Wywoływane raz na klatkę dla każdego typu komponentu, który implementuje Update, zgodnie z wewnętrzną kolejnością priorytetów. Dodatkowo animacje właściwości GO uruchomione przez `go.animate()` są tu aktualizowane jako oddzielny typ komponentu. Dla każdego włączonego Collection Proxy faza `Update` jest wywoływana rekurencyjnie od kroku 1. | +| 3 | **Late Update** | `late_update()` | Wywoływane raz na klatkę dla każdego typu komponentu, który implementuje Late Update, zgodnie z wewnętrzną kolejnością priorytetów. | +| 4 | **Transformacje** | | Na końcu wykonywana jest jeszcze jedna końcowa aktualizacja transformacji dla każdego komponentu, jeśli jest to potrzebne. | -W razie potrzeby więcej informacji o wewnętrznym działaniu fazy Update można znaleźć w kodzie [`gameobject.cpp`](https://github.com/defold/defold/blob/dev/engine/gameobject/src/gameobject/gameobject.cpp). +Jeśli chcesz poznać więcej szczegółów o wewnętrznym działaniu Defold w fazie Update, warto przeczytać sam kod [`gameobject.cpp`](https://github.com/defold/defold/blob/dev/engine/gameobject/src/gameobject/gameobject.cpp). -### Faza renderowania (Render Update Phase) +### Faza aktualizacji renderowania -W bloku `Render Update` najpierw przetwarzane są wszystkie wiadomości wysłane na gniazdo `@render` (np. wiadomości `set_view_projection`, `set_clear_color` itd.). Następnie wywoływana jest funkcja `update()` skryptu renderującego. +Blok aktualizacji renderowania najpierw rozsyła wszystkie wiadomości wysłane do gniazda `@render` (na przykład wiadomości `set_view_projection`, `set_clear_color` itd.). Następnie wywoływana jest funkcja `update()` skryptu renderującego. -![Render Update Phase](images/application_lifecycle/render_update_phase.png) +![Faza aktualizacji renderowania](images/application_lifecycle/render_update_phase.png) -### Faza post-aktualizacji (Post update Phase) +### Faza post update -Po aktualizacjach uruchamiana jest sekwencja post-aktualizacji. Z pamięci są zwalniani collection proxy oznaczeni do wyładowania (co następuje podczas sekwencji `dispatch messages`). Wszystkie obiekty oznaczone do usunięcia wywołują `final()` we wszystkich komponentach je posiadających. Kod w tych funkcjach może wysyłać kolejne wiadomości, stąd po `final()` ponownie uruchamiana jest sekwencja rozsyłania wiadomości. +Po aktualizacjach uruchamiana jest sekwencja końcowej aktualizacji. Wyładowuje ona z pamięci pełnomocniki kolekcji oznaczone do wyładowania (dzieje się to podczas sekwencji „rozsyłania wiadomości” - `dispatch messages`). Każdy obiekt gry oznaczony do usunięcia wywołuje wszystkie funkcje `final()` swoich komponentów, jeśli takie istnieją. Kod w funkcjach `final()` często wysyła nowe wiadomości do kolejki, więc po tym uruchamiane jest ponownie przejście `dispatch messages`. -![Post Update Phase](images/application_lifecycle/post_update_phase.png) +![Faza post update](images/application_lifecycle/post_update_phase.png) -Następnie komponenty fabryki, które miały zostać uruchomione, tworzą obiekty. Na końcu obiekty oznaczone do usunięcia są faktycznie usuwane. +Każdy komponent fabryki, który dostał polecenie utworzenia obiektu gry, zrobi to w następnym kroku. Na końcu obiekty gry oznaczone do usunięcia są faktycznie usuwane. -### Faza renderowania (Render Phase) +### Faza renderowania -Ostatnim krokiem pętli aktualizacyjnej jest obsłużenie wiadomości wysyłanych do gniazda `@system` (`exit`, `reboot`, przełączanie profilera, uruchamianie i zatrzymywanie nagrywania wideo itd.). +Ostatni krok pętli aktualizacji obejmuje rozsyłanie wiadomości `@system` (`exit`, `reboot`, przełączanie profilera, uruchamianie i zatrzymywanie przechwytywania wideo itd.). -![Render Phase](images/application_lifecycle/render_phase.png) +![Faza renderowania](images/application_lifecycle/render_phase.png) -Następnie grafika jest renderowana, w tym wizualizacja profilera (zobacz [dokumentację debugowania](/manuals/debugging)). Zaraz po renderowaniu następuje przechwytywanie wideo. +Potem grafika jest renderowana, podobnie jak wizualizacja profilera (zobacz [dokumentację debugowania](/manuals/debugging)). Po renderowaniu grafiki wykonywane jest przechwytywanie wideo. #### Liczba klatek i krok czasowy kolekcji -Liczba klatek na sekundę (odpowiednio liczba przebiegów pętli aktualizacyjnej) jest ustawiana w ustawieniach projektu albo dynamicznie przez wysłanie wiadomości `set_update_frequency` do gniazda `@system`. Można też ustawić _time step_ dla każdego collection proxy przez `set_time_step`. Zmiana kroku kolekcji nie wpływa na liczbę klatek (czyli ilość wywołań `update()` w każdej klatce), ale zmienia czas kroków fizyki oraz wartość `dt` przekazywaną do `update()`. +Liczbę aktualizacji klatki na sekundę, czyli liczbę przebiegów pętli aktualizacji na sekundę, można ustawić w ustawieniach projektu albo programowo, wysyłając wiadomość `set_update_frequency` do gniazda `@system`. Można też osobno ustawić krok czasowy (_time step_) dla pełnomocników kolekcji, wysyłając do proxy wiadomość `set_time_step`. Zmiana kroku czasowego kolekcji nie wpływa na liczbę klatek. Wpływa natomiast na krok czasowy aktualizacji fizyki oraz na wartość `dt` przekazywaną do `update()`. Pamiętaj też, że zmiana kroku czasowego nie zmienia liczby wywołań `update()` w każdej klatce - zawsze jest ono wywoływane dokładnie raz. -(Zobacz [Instrukcję pełnomocników kolekcji](/manuals/collection-proxy) i [`set_time_step`](/ref/collectionproxy#set-time-step) po więcej szczegółów) +(Szczegóły znajdziesz w [podręczniku pełnomocnika kolekcji](/manuals/collection-proxy) oraz przy [`set_time_step`](/ref/collectionproxy#set-time-step)) #### Ograniczanie pracy silnika -W Defold 1.12.0 dodano API ograniczające pracę silnika, które może pominąć aktualizacje i renderowanie, jednocześnie wykrywając wejście. Każde wejście budzi silnik i po okresie chłodzenia można ponownie wejść w ograniczoną pracę. +W Defold 1.12.0 wprowadzono API ograniczania pracy silnika, które może całkowicie pominąć aktualizacje silnika i renderowanie, a mimo to nadal wykrywać wejście. Każde wejście wybudza silnik, a po czasie wyciszenia silnik może ponownie wejść w tryb ograniczania. -Zobacz `sys.set_engine_throttle()` dla szczegółów i przykładów użycia. +Szczegóły i przykłady użycia znajdziesz w API `sys.set_engine_throttle()`. -## Faza finalizacyjna +## Finalizacja -Gdy aplikacja kończy pracę, najpierw dokańcza ostatnią sekwencję pętli aktualizacyjnej, która zwalnia collection proxy – finalizując i usuwając obiekty wewnątrz nich. +Gdy aplikacja się zamyka, najpierw kończy ostatnią sekwencję pętli aktualizacji, która wyładuje pełnomocniki kolekcji: finalizując i usuwając wszystkie obiekty gry w każdej obsługiwanej przez nie kolekcji. -Po tym silnik przechodzi do samej finalizacji, która dotyczy głównej kolekcji i jej obiektów: +Gdy to się skończy, silnik wchodzi w sekwencję finalizacji obsługującą główną kolekcję i jej obiekty: -![Finalization](images/application_lifecycle/finalization.png) +![Finalizacja](images/application_lifecycle/finalization.png) -Na początku wywoływane są funkcje `final()` wszystkich komponentów. Później uruchamiana jest sekwencja rozsyłania wiadomości. Na końcu wszystkie obiekty są usuwane, a główna kolekcja zostaje zwolniona. +Najpierw wywoływane są funkcje `final()` komponentów. Potem następuje kolejne przejście rozsyłania wiadomości. Na końcu wszystkie obiekty gry są usuwane, a główna kolekcja zostaje zwolniona. -Silnik dalej kończy pracę wewnętrznych subsystemów, np. usuwa konfigurację projektu, zatrzymuje profiler pamięci itd. +Silnik przechodzi potem do zamykania podsystemów działających w tle: usuwa konfigurację projektu, wyłącza profiler pamięci i tak dalej. -Aplikacja jest wtedy całkowicie zamknięta. +Aplikacja jest teraz całkowicie zamknięta. -## Rozsyłanie wiadomości (Dispatching Messages) +## Rozsyłanie wiadomości -`Dispatching Messages` to specjalne przejście wykonywane po **każdej** aktualizacji typu komponentu (np. aktualizacji sprite’a, skryptów itp.). W tym kroku wszystkie zgromadzone wiadomości są rozsyłane. Diagram oznacza te działania ikoną koperty ze strzałką 📩. +**Rozsyłanie wiadomości** to specjalne przejście wykonywane po **każdej** aktualizacji typu komponentu, na przykład po aktualizacji sprite'ów, skryptów i każdej innej operacji, która może wysyłać wiadomości. W trakcie wykonywania wszystkie zakolejkowane wiadomości są rozsyłane. Na diagramach są oznaczone małymi ikonami koperty ze strzałką 📩. -![Dispatch Messages](images/application_lifecycle/dispatch_messages.png) +![Rozsyłanie wiadomości](images/application_lifecycle/dispatch_messages.png) -Po tym, jak wszystkie **wiadomości użytkownika** zostaną dostarczone przez wywołanie `on_message()`, silnik obsługuje specjalne wiadomości Defold w następującej kolejności (przy każdym collection proxy): +Po rozesłaniu wszystkich **wiadomości użytkownika** przez wywołanie `on_message()` dla każdego komponentu Defold obsługuje specjalne wiadomości w następującej kolejności, dla każdego pełnomocnika kolekcji: -1. `load` – ładuje pełnomocniki oznaczone do wczytania, wysyła z powrotem `proxy_loaded`. -2. `unload` – zwalnia pełnomocniki oznaczone do zwolnienia, wysyła `proxy_unloaded`. -3. `init` – wywołuje fazę `Collection Init` dla proxy zaznaczonych do inicjalizacji. -4. `final` – wywołuje `final()` dla wszystkich komponentów proxy oznaczonych do zamknięcia. -5. `enable` – aktywuje collection proxy, żeby w następnej klatce wykonać dla niego `Update Loop`; to też uruchamia `init()` dla składników proxy. -6. `disable` – dezaktywuje collection proxy, więc pętla aktualizacyjna nie będzie dla niego wykonywana. +1. wiadomości `load` - ładują pełnomocniki kolekcji oznaczone do wczytania i odsyłają wiadomość `proxy_loaded`. +2. wiadomości `unload` - wyładowują pełnomocniki kolekcji oznaczone do wyładowania i odsyłają wiadomość `proxy_unloaded`. +3. wiadomości `init` - uruchamiają fazę inicjalizacji kolekcji (`Collection Init`) dla wszystkich pełnomocników kolekcji, które mają zostać zainicjalizowane. +4. wiadomości `final` - wywołują `final()` na wszystkich komponentach proxy oznaczonych do finalizacji. +5. wiadomości `enable` - włączają pełnomocnika kolekcji, więc w następnej klatce zostanie dla niego wykonana pętla aktualizacji (`Update Loop`); to niejawnie uruchamia `init()` dla każdego komponentu w tej kolekcji. +6. wiadomości `disable` - wyłączają pełnomocnika kolekcji, więc w następnej klatce nie zostanie dla niego wykonana pętla aktualizacji (`Update Loop`); całkowicie zatrzymuje to działanie pętli aktualizacji dla tego proxy. -Ponieważ kod odbiorców `on_message()` może publikować kolejne wiadomości, dispatcher kontynuuje przetwarzanie kolejki aż do jej opróżnienia. Jednak dispatcher ma limit liczby przejść przez kolejkę. Więcej informacji znaleźć można w rozdziale [Message Chains](/manuals/message-passing). +Ponieważ kod komponentów odbierających wiadomości w `on_message()` może wysyłać kolejne wiadomości, dispatcher będzie dalej rozsyłał wiadomości rekurencyjnie, aż kolejka będzie pusta. Istnieje jednak limit liczby przejść przez kolejkę wiadomości. Szczegóły znajdziesz w [łańcuchach wiadomości (Message Chains)](/manuals/message-passing). diff --git a/docs/pl/manuals/application-security.md b/docs/pl/manuals/application-security.md new file mode 100644 index 00000000..c938c930 --- /dev/null +++ b/docs/pl/manuals/application-security.md @@ -0,0 +1,109 @@ +--- +title: Podręcznik bezpieczeństwa aplikacji +brief: Ten podręcznik omawia kilka obszarów związanych z bezpiecznymi praktykami tworzenia oprogramowania. +--- + +# Bezpieczeństwo aplikacji + +Bezpieczeństwo aplikacji to szeroki temat, obejmujący zarówno bezpieczne praktyki tworzenia oprogramowania, jak i zabezpieczanie zawartości gry po jej wydaniu. Ten podręcznik omawia kilka obszarów i umieszcza je w kontekście bezpieczeństwa aplikacji podczas korzystania z silnika Defold, narzędzi i usług: + +* Ochrona własności intelektualnej +* Rozwiązania przeciwdziałające oszustwom +* Bezpieczna komunikacja sieciowa +* Korzystanie z oprogramowania firm trzecich +* Korzystanie z chmurowych serwerów budowania +* Zawartość do pobrania + + +## Ochrona własności intelektualnej przed kradzieżą +Jedną z głównych obaw wielu twórców jest to, jak chronić swoją twórczość przed kradzieżą. Z prawnego punktu widzenia prawa autorskie, patenty i znaki towarowe mogą służyć do ochrony różnych aspektów własności intelektualnej gier wideo. Prawa autorskie dają właścicielowi wyłączne prawo do rozpowszechniania utworu, patenty chronią wynalazki, a znaki towarowe chronią nazwy, symbole i logotypy. + +Można też chcieć zastosować techniczne środki ostrożności, aby chronić twórczą zawartość gry. Trzeba jednak pamiętać, że gdy gra trafi już w ręce gracza, da się znaleźć sposoby na wyciągnięcie zasobów. Można to osiągnąć przez inżynierię wsteczną aplikacji i plików gry, ale też przy użyciu narzędzi do wyciągania tekstur i modeli w momencie, gdy są wysyłane do GPU albo gdy inne zasoby są ładowane do pamięci. + +Z tego powodu przyjmujemy, że jeśli użytkownicy są zdeterminowani, by wyciągnąć zasoby gry, ostatecznie będą w stanie to zrobić. + +Twórcy mogą dodać własne zabezpieczenia, aby utrudnić wyciągnięcie zasobów, __ale nie uczynić tego niemożliwym__. Zwykle obejmuje to różne metody szyfrowania i obfuskacji, które mają chronić i ukrywać zasoby gry. + +### Obfuskacja kodu źródłowego +Obfuskacja kodu źródłowego to zautomatyzowany proces, w którym kod źródłowy jest celowo przekształcany tak, aby był trudny do zrozumienia dla człowieka, bez wpływu na wynik działania programu. Celem jest zwykle ochrona przed kradzieżą, ale też utrudnienie oszukiwania. + +W Defold obfuskację kodu źródłowego można zastosować albo jako krok wykonywany przed budowaniem, albo jako zintegrowaną część procesu budowania. W przypadku obfuskacji wykonywanej przed budowaniem kod źródłowy jest przetwarzany przez narzędzie do obfuskacji, zanim rozpocznie się sam proces budowania. + +Z kolei obfuskacja w czasie budowania jest zintegrowana z procesem budowania za pomocą wtyczki budowania Lua (Lua builder plugin). Taka wtyczka pobiera surowy kod źródłowy i zwraca jego obfuskowaną wersję. Przykład obfuskacji w czasie budowania pokazano w [rozszerzeniu Prometheus](https://github.com/defold/extension-prometheus), opartym na obfuskatorze Lua Prometheus dostępnym na GitHubie. Poniżej znajduje się przykład użycia Prometheus do agresywnej obfuskacji fragmentu kodu (zwróć uwagę, że tak silna obfuskacja wpłynie na wydajność kodu Lua w czasie działania): + +Przykład: + +``` +function init(self) + print("hello") + test.greet("Bob") +end +``` + +Wynik obfuskacji: + +``` +local v={"+qdW","ZK0tEKf=";"XP/IX3+="}for o,J in ipairs({{1;3};{1,1},{2,3}})do while J[1]=J or x(X,S+1,S+1)~="="then L(H,W(h((k%65536)/256)))end break end S=S+1 end d[v]=w(H)end end end local function o(o)test[J(-45815)](o)end function init(v)print(J(-45813))o(J(-45814))end +``` + +### Szyfrowanie zasobów +Podczas budowania w Defold zasoby gry są przetwarzane i zamieniane na formaty odpowiednie do użycia przez silnik w czasie działania. Tekstury są kompilowane do formatu Basis Universal, kolekcje, obiekty gry i komponenty są konwertowane z czytelnej dla człowieka postaci tekstowej do binarnych odpowiedników, a kod źródłowy Lua jest przetwarzany i kompilowany do bajtkodu. Inne zasoby, takie jak pliki dźwiękowe, są używane bez zmian. + +Po zakończeniu tego procesu zasoby są dodawane do archiwum gry, jeden po drugim. Archiwum gry to duży plik binarny, a położenie każdego zasobu w archiwum jest zapisywane w pliku indeksu archiwum. Format opisano [tutaj](https://github.com/defold/defold/blob/dev/engine/docs/ARCHIVE_FORMAT.md). + +Zanim pliki źródłowe Lua zostaną dodane do archiwum, mogą też zostać opcjonalnie zaszyfrowane. Domyślne szyfrowanie dostępne w Defold to prosty szyfr blokowy używany po to, by ciągi znaków w kodzie nie były od razu widoczne, jeśli archiwum gry zostanie otwarte w narzędziu do podglądu plików binarnych. Nie należy go uznawać za kryptograficznie bezpieczne rozwiązanie, ponieważ kod źródłowy Defold jest dostępny na GitHubie, a klucz szyfru jest widoczny w kodzie źródłowym. + +Można dodać własne szyfrowanie do plików źródłowych Lua, implementując wtyczkę szyfrowania zasobów (resource encryption plugin). Taka wtyczka składa się z części działającej w czasie budowania, która szyfruje zasoby w ramach procesu budowania, oraz części działającej w czasie działania, która odszyfrowuje zasoby podczas odczytu z archiwum gry. Podstawowa wtyczka szyfrowania zasobów, którą można wykorzystać jako punkt wyjścia do własnego szyfrowania, jest [dostępna na GitHubie](https://github.com/defold/extension-resource-encryption). + + +### Kodowanie wartości konfiguracji projektu +Plik *game.project* zostanie dołączony bez zmian do pakietu aplikacji. Czasami możesz chcieć przechowywać publiczne klucze API lub podobne wartości, które są wrażliwe, choć niekoniecznie poufne. Aby zwiększyć bezpieczeństwo takich wartości, można umieścić je w binarnym pliku aplikacji zamiast w *game.project*, a mimo to nadal mieć do nich dostęp za pomocą funkcji API Defold, takich jak `sys.get_config_string()` i podobnych. Można to zrobić, dodając natywne rozszerzenie w *game.project* i używając makra `DM_DECLARE_CONFIGFILE_EXTENSION`, aby dostarczyć własny sposób pobierania wartości konfiguracji przez funkcje API Defold. Przykładowy projekt, który może służyć jako punkt wyjścia, jest [dostępny na GitHubie](https://github.com/defold/example-configfile-extension/tree/master). + + +## Ochrona gry przed oszustami +Oszukiwanie w grach wideo istnieje tak długo, jak sama branża gier. Kody cheatowe były kiedyś drukowane w popularnych magazynach o grach wideo, a do wczesnych komputerów domowych sprzedawano specjalne kartridże z cheatami. Wraz z rozwojem branży i samych gier ewoluowali także oszuści i ich metody. Do najpopularniejszych mechanizmów oszukiwania w grach należą: + +* przepakowywanie zawartości gry w celu wstrzyknięcia własnej logiki +* speed hacki, które przyspieszają lub spowalniają grę względem normalnego tempa +* automatyzacja i analiza obrazu do automatycznego celowania oraz botów +* wstrzykiwanie kodu i manipulowanie pamięcią w celu modyfikowania wyników, żyć, amunicji itd. + +Ochrona przed oszustami jest trudna i niemal niemożliwa. Nawet granie w chmurze, w którym gry są uruchamiane na zdalnych serwerach i strumieniowane bezpośrednio na urządzenie użytkownika, nie jest całkowicie wolne od oszustów. + +Defold nie oferuje w silniku ani w narzędziach żadnych rozwiązań anti-cheat i zamiast tego pozostawia taką pracę firmom specjalizującym się w dostarczaniu rozwiązań anti-cheat dla gier. + + +## Bezpieczna komunikacja sieciowa +Defold obsługuje bezpieczne połączenia dla komunikacji przez sockety i HTTP. Zaleca się używanie takich połączeń do każdej komunikacji z serwerem, aby uwierzytelnić serwer oraz chronić prywatność i integralność danych przesyłanych między klientem a serwerem w obu kierunkach. Defold korzysta z popularnej i szeroko stosowanej otwartoźródłowej implementacji protokołów TLS i SSL, [Mbed TLS](https://github.com/Mbed-TLS/mbedtls). Mbed TLS jest rozwijany przez ARM i ich partnerów technologicznych. + +### Weryfikacja certyfikatu SSL +Aby zapobiec atakom man-in-the-middle na komunikację sieciową, można zweryfikować łańcuch certyfikatów podczas uzgadniania połączenia SSL z serwerem. Można to zrobić, przekazując klientowi sieciowemu w Defold listę kluczy publicznych. Więcej informacji o zabezpieczaniu komunikacji sieciowej znajdziesz w sekcji o weryfikacji SSL w [instrukcji sieciowej](https://defold.com/manuals/networking/#secure-connections). + + +## Bezpieczne korzystanie z oprogramowania firm trzecich +Choć do stworzenia gry nie trzeba używać bibliotek firm trzecich ani natywnych rozszerzeń, bardzo wielu twórców korzysta z zasobów z oficjalnego [Asset Portal](https://defold.com/assets/), aby przyspieszyć pracę. Asset Portal zawiera szeroki wybór zasobów: od integracji z zewnętrznymi SDK po menedżery ekranów, biblioteki UI, kamery i wiele więcej. + +Żaden zasób z Asset Portal nie został zweryfikowany przez Defold Foundation. Fundacja nie ponosi odpowiedzialności za szkody w systemie komputerowym lub innym urządzeniu ani za utratę danych wynikające z użycia zasobów pozyskanych za pośrednictwem Asset Portal. Szczegóły znajdziesz w naszych [Warunkach i zasadach](https://defold.com/terms-and-conditions/#3-no-warranties). + +Zalecamy, aby przed użyciem sprawdzić każdy zasób, a gdy uznasz go za odpowiedni do projektu, utworzyć jego fork lub kopię, aby mieć pewność, że nie zmieni się bez Twojej wiedzy. + + +## Bezpieczne korzystanie z chmurowych serwerów budowania +Chmurowe serwery budowania Defold (czyli serwery Extender) zostały stworzone po to, by pomóc twórcom dodawać nową funkcjonalność do silnika Defold bez konieczności przebudowy samego silnika. Gdy projekt Defold zawierający kod natywny jest budowany po raz pierwszy, kod natywny i wszelkie powiązane zasoby są wysyłane do chmurowych serwerów budowania, gdzie tworzona jest niestandardowa wersja silnika Defold, a następnie odsyłana do twórcy. Ten sam proces stosuje się, gdy projekt jest budowany z użyciem własnego manifestu aplikacji, aby usunąć niewykorzystywane komponenty z silnika. + +Chmurowe serwery budowania są hostowane w AWS i tworzone zgodnie z najlepszymi praktykami bezpieczeństwa. Defold Foundation nie gwarantuje jednak, że spełnią Twoje wymagania, będą wolne od wad, wolne od wirusów, bezpieczne, bezbłędne ani że korzystanie z nich będzie nieprzerwane lub bezpieczne. Szczegóły znajdziesz w naszych [Warunkach i zasadach](https://defold.com/terms-and-conditions/#3-no-warranties). + +Jeśli martwisz się o bezpieczeństwo i dostępność serwerów budowania, zalecamy skonfigurowanie własnych prywatnych serwerów budowania. Instrukcje dotyczące konfiguracji własnego serwera znajdziesz w [głównym pliku README](https://github.com/defold/extender) repozytorium extender na GitHubie. + + +## Zabezpieczanie zawartości do pobrania +System Defold Live Update pozwala twórcom wykluczyć zawartość z głównego pakietu gry, aby można ją było pobrać i użyć później. Typowym zastosowaniem jest pobieranie dodatkowych poziomów, map lub światów w miarę postępów gracza. + +Gdy wykluczona zawartość zostanie pobrana i przygotowana do użycia w grze, silnik zweryfikuje ją kryptograficznie przed użyciem, aby upewnić się, że nie została zmodyfikowana. Weryfikacja składa się z kilku kontroli: + +* Czy format binarny jest poprawny? +* Czy pobrana zawartość jest obsługiwana przez aktualnie uruchomioną wersję silnika? +* Czy pobrana zawartość jest podpisana właściwą parą kluczy publicznego i prywatnego? +* Czy pobrana zawartość jest kompletna i nie brakuje w niej żadnych plików? + +Więcej informacji o tym procesie znajdziesz w [instrukcji Live Update](https://defold.com/manuals/live-update/#manifest-verification). diff --git a/docs/pl/manuals/atlas.md b/docs/pl/manuals/atlas.md index 0ede73d5..5abac204 100644 --- a/docs/pl/manuals/atlas.md +++ b/docs/pl/manuals/atlas.md @@ -1,128 +1,142 @@ --- -title: Atlas (Galeria obrazów) -brief: Ta instrukcja wyjaśnia jak działa atlas w Defoldzie. +title: Podręcznik atlasu +brief: Ten podręcznik wyjaśnia, jak działają zasoby atlasu w Defold. --- -# Atlas (Galeria obrazów) +# Atlas -Chociaż pojedyncze obrazy często są używane jako źródło dla sprite'ów, ze względów wydajnościowych obrazy muszą być łączone w większe zestawy obrazów, nazywane atlasy. Kombinowanie zestawów mniejszych obrazów w atlasy jest szczególnie ważne na urządzeniach mobilnych, gdzie pamięć i moc obliczeniowa są przeważnie mniejsze niż na komputerach stacjonarnych lub dedykowanych konsolach do gier. +Chociaż pojedyncze obrazy są często używane jako źródło sprite'ów, ze względów wydajnościowych obrazy trzeba łączyć w większe zestawy, zwane atlasami. Łączenie mniejszych obrazów w atlasy jest szczególnie ważne na urządzeniach mobilnych, gdzie pamięć i moc obliczeniowa są mniejsze niż na komputerach stacjonarnych lub konsolach do gier. -W Defoldzie zasób atlasu to lista oddzielnych plików obrazów, które automatycznie są łączone w większy obraz. +W Defold zasób atlasu to lista oddzielnych plików obrazów, które są automatycznie łączone w jeden większy obraz. +## Tworzenie atlasu -## Tworzenie Atlasu +Wybierz New... ▸ Atlas z menu kontekstowego w przeglądarce *Assets*. Nadaj nazwę nowemu plikowi atlasu. Edytor otworzy teraz plik w edytorze atlasu. Właściwości atlasu są widoczne w panelu *Properties*, więc możesz je edytować (szczegóły znajdziesz poniżej). -Wybierz New... ▸ Atlas z menu kontekstowego w panelu *Assets*. Nazwij nowy plik atlasu. Edytor otworzy teraz plik w edytorze atlasu. Właściwości atlasu są widoczne w -panelu *Properties* (Właściwości), dzięki czemu możesz je edytować (szczegóły poniżej). +Musisz najpierw wypełnić atlas obrazami lub animacjami, zanim użyjesz go jako źródła grafiki dla komponentów obiektu, takich jak Sprite i ParticleFX. -Musisz wypełnić atlas obrazami lub animacjami, zanim będziesz mógł go użyć jako źródła grafiki dla komponentów obiektu, takich jak Sprite'y i komponenty ParticleFX. - -Upewnij się, że dodałeś obrazy do projektu (przeciągnij i upuść pliki obrazów we właściwe miejsce w panelu *Assets*). +Upewnij się, że dodałeś obrazy do projektu, przeciągając pliki obrazów w odpowiednie miejsce w przeglądarce *Assets*. Dodawanie pojedynczych obrazów -: Kliknij prawym przyciskiem myszy główny wpis Atlas w panelu *Outline*. +: Przeciągnij obrazy z panelu *Assets* do widoku edytora. + + Alternatywnie kliknij prawym przyciskiem myszy główny wpis atlasu w panelu *Outline*. Wybierz Add Images z menu kontekstowego, aby dodać pojedyncze obrazy. - Pojawi się okno dialogowe, z którego możesz znaleźć i wybrać obrazy, które chcesz dodać do atlasu. Zauważ, że możesz filtrować pliki obrazów i wybierać je wielokrotnie. + Otworzy się okno dialogowe, w którym możesz znaleźć i zaznaczyć obrazy, które chcesz dodać do atlasu. Zwróć uwagę, że możesz filtrować pliki obrazów i wybierać wiele plików naraz. - ![Creating an atlas, adding images](images/atlas/add.png) + ![Tworzenie atlasu, dodawanie obrazów](images/atlas/add.png) - Dodane obrazy są wymienione w *Outline*, a pełny atlas można zobaczyć w centrum widoku edytora. Może być konieczne naciśnięcie F (View ▸ Frame Selection w menu), aby dopasować zaznaczenie. + Dodane obrazy są wyświetlane w *Outline*, a cały atlas można zobaczyć w środkowym widoku edytora. Może być konieczne naciśnięcie F (View ▸ Frame Selection z menu), aby dopasować widok do zaznaczenia. - ![Images added](images/atlas/single_images.png) + ![Dodane obrazy](images/atlas/single_images.png) Dodawanie animacji flipbook -: Kliknij przyciskiem myszy główny wpis Atlas w panelu *Outline*. +: Kliknij prawym przyciskiem myszy główny wpis atlasu w panelu *Outline*. Wybierz Add Animation Group z menu kontekstowego, aby utworzyć grupę animacji flipbook. - Nowa, pusta grupa animacji o domyślnej nazwie ("New Animation") zostaje dodana do atlasu. + Do atlasu zostanie dodana nowa, pusta grupa animacji z domyślną nazwą ("New Animation"). + + Przeciągnij obrazy z panelu *Assets* do widoku edytora, aby dodać je do aktualnie zaznaczonej grupy. + + Alternatywnie kliknij prawym przyciskiem myszy nową grupę i wybierz Add Images z menu kontekstowego. - Kliknij prawym przyciskiem myszy na nową grupę i wybierz dd Images z menu kontekstowego. + Otworzy się okno dialogowe, w którym możesz znaleźć i zaznaczyć obrazy, które chcesz dodać do grupy animacji. - Pojawi się okno dialogowe, z którego możesz znaleźć i wybrać obrazy, które chcesz dodać do grupy animacji. + ![Tworzenie atlasu, dodawanie obrazów](images/atlas/add_animation.png) - ![Creating an atlas, adding images](images/atlas/add_animation.png) + Naciśnij Space z zaznaczoną grupą animacji, aby ją podejrzeć, i użyj Ctrl/Cmd+T, aby zamknąć podgląd. Dostosuj *Properties* animacji według potrzeb (patrz poniżej). - Naciśnij Spację z wybraną grupą animacji, aby ją obejrzeć. Dostosuj właściwości animacji w obszarze *Properties* według potrzeb (patrz poniżej). + ![Grupa animacji](images/atlas/animation_group.png) - ![Animation group](images/atlas/animation_group.png) +Możesz zmieniać kolejność obrazów w panelu *Outline*, zaznaczając je i naciskając Alt + Up/down. Możesz też łatwo tworzyć duplikaty, kopiując i wklejając obrazy w panelu *Outline* (z menu Edit, z menu kontekstowego po kliknięciu prawym przyciskiem myszy lub skrótami klawiaturowymi). -Możesz zmieniać kolejność obrazów w Outline, wybierając je i naciskając Alt + W górę/w dół. Możesz również łatwo tworzyć duplikaty, kopiując i wklejając obrazy w zarysie (z menu Edit, menu kontekstowego po kliknięciu prawym przyciskiem myszy lub za pomocą skrótów klawiszowych). +## Właściwości atlasu -## Właściwości Atlasu +Każdy zasób atlasu ma zestaw właściwości. Są one widoczne w panelu *Properties*, gdy zaznaczysz element główny w widoku *Outline*. -Każdy zasób atlasu posiada zestaw właściwości, które są widoczne w obszarze *Properties*, gdy wybierasz główny element w panelu *Outline*. +Size +: Pokazuje obliczony łączny rozmiar wynikowego zasobu tekstury. Szerokość i wysokość są ustawiane na najbliższą potęgę dwójki. Jeśli włączysz kompresję tekstury, niektóre formaty wymagają tekstur kwadratowych. Tekstury niekwadratowe zostaną wtedy przeskalowane i wypełnione pustą przestrzenią, aby stały się kwadratowe. Szczegóły znajdziesz w [podręczniku profili tekstur](/manuals/texture-profiles/). -Size (Rozmiar) -: Pokazuje obliczony łączny rozmiar wynikowego zasobu tekstury. Szerokość i wysokość są ustawiane na najbliższą potęgę dwójki. Zauważ, że jeśli włączysz kompresję tekstury, niektóre formaty wymagają tekstur kwadratowych. Niekwadratowe tekstury zostaną wtedy zmienione rozmiarem i wypełnione pustą przestrzenią, aby stworzyć teksturę kwadratową. Szczegóły można znaleźć w [instrukcji do profilów tekstur](/manuals/texture-profiles/) +Margin +: Liczba pikseli, które należy dodać między każdym obrazem. -Margin (Margines) -: Liczba pikseli, która powinna być dodawana między każdym obrazem. +Inner Padding +: Liczba pustych pikseli, które należy dodać wokół każdego obrazu. -Inner Padding (Wewnętrzny margines) -: Liczba pustych pikseli, która powinna być wypełniana wokół każdego obrazu. +Extrude Borders +: Liczba pikseli krawędzi, które należy wielokrotnie dodać wokół każdego obrazu. Gdy fragment shader próbuje próbkować piksele na krawędzi obrazu, piksele sąsiedniego obrazu (na tej samej teksturze atlasu) mogą „przeciekać”. Wyekstrudowanie krawędzi rozwiązuje ten problem. -Extrude Borders (Wytłoczenie granic) -: Liczba krawędziowych pikseli, która powinna być wielokrotnie dodawana wokół każdego obrazu. Kiedy fragment shader próbuje pobierać piksele na krawędzi obrazu, piksele z obrazu sąsiada (na tym samym atlasie tekstury) mogą się przeniknąć. Wydłużenie krawędzi rozwiązuje ten problem. +Max Page Size +: Maksymalny rozmiar strony w atlasie wielostronicowym. Można tego użyć do podzielenia atlasu na wiele stron tego samego atlasu, aby ograniczyć jego rozmiar, a jednocześnie korzystać tylko z jednego draw call. Ta funkcja musi być używana razem z materiałami obsługującymi atlas wielostronicowy, znajdującymi się w `/builtins/materials/*_paged_atlas.material`. -Oto przykłady różnych ustawień właściwości z czterema kwadratowymi obrazami o wymiarach 64x64 pikseli dodanymi do atlasu. Zauważ, jak atlas przeskakuje do rozmiaru 256x256, kiedy tylko obrazy nie mieszczą się w 128x128, co skutkuje marnowaniem dużej przestrzeni tekstury. +![Atlas wielostronicowy](images/atlas/multipage_atlas.png) -![Atlas properties](images/atlas/atlas_properties.png) +Rename Patterns +: Przecinkiem (´,´) rozdzielona lista wzorców wyszukiwania i zamiany, gdzie każdy wzorzec ma postać `search=replace`. + Oryginalna nazwa każdego obrazu (nazwa bazowa pliku) zostanie przekształcona przy użyciu tych wzorców. Na przykład wzorzec `hat=cat,_normal=` zmieni nazwę obrazu `hat_normal` na `cat`. Jest to przydatne przy dopasowywaniu animacji między atlasami. -## Właściwości Obrazu +Oto przykłady różnych ustawień właściwości z czterema kwadratowymi obrazami 64x64 dodanymi do atlasu. Zwróć uwagę, jak atlas przeskakuje do 256x256, gdy obrazy przestają mieścić się w 128x128, co powoduje duże marnotrawstwo miejsca w teksturze. -Każdy obraz w atlasie posiada zestaw właściwości: +![Właściwości atlasu](images/atlas/atlas_properties.png) + +## Właściwości obrazu + +Każdy obraz w atlasie ma zestaw właściwości: Id -: Identyfikator obrazu (tylko do odczytu). +: Id obrazu (tylko do odczytu). -Size (Rozmiar) +Size : Szerokość i wysokość obrazu (tylko do odczytu). -Sprite Trim Mode (Trymowanie Sprite'a) -: Sposób renderowania sprite'a. Domyślnie sprite jest renderowany jako prostokąt (Trymowanie Sprite'a ustawione na Off - Wyłączone). Jeśli sprite zawiera wiele przezroczystych pikseli, może być bardziej wydajne, aby renderować sprite jako kształt nierektangularny, używając od 4 do 8 wierzchołków. Zauważ, że trymowanie sprite'a nie działa razem z sprite'ami typu slice-9. +Pivot +: Punkt pivot obrazu (w jednostkach). Lewy górny róg ma wartość (0,0), a prawy dolny (1,1). Domyślna wartość to (0.5, 0.5). Pivot może znajdować się poza zakresem 0-1. To właśnie w tym punkcie obraz zostanie wyśrodkowany, gdy będzie użyty np. w spricie. Możesz zmienić pivot, przeciągając uchwyt pivot w widoku edytora. Uchwyt będzie widoczny tylko wtedy, gdy zaznaczony jest jeden obraz. Przypinanie można włączyć, przytrzymując Shift podczas przeciągania. + +Sprite Trim Mode +: Sposób renderowania sprite'a. Domyślnie sprite jest renderowany jako prostokąt (Sprite Trim Mode ustawiony na Off). Jeśli sprite zawiera dużo przezroczystych pikseli, bardziej wydajne może być renderowanie go jako kształtu nieprostokątnego przy użyciu od 4 do 8 wierzchołków. Zwróć uwagę, że przycinanie sprite'a nie działa razem ze sprite'ami slice-9. -Image (Obraz) +Image : Ścieżka do samego obrazu. -![Image properties](images/atlas/image_properties.png) +![Właściwości obrazu](images/atlas/image_properties.png) -## Właściwości Animacji +## Właściwości animacji -Oprócz listy obrazów, które są częścią grupy animacyjnej (Animation Group), dostępny jest zestaw właściwości: +Oprócz listy obrazów należących do grupy animacji dostępny jest zestaw właściwości: Id -: Identyfikator/nazwa animacji. +: Nazwa animacji. Fps -: Szybkość odtwarzania animacji wyrażona w klatkach na sekundę (Frames Per Second). +: Szybkość odtwarzania animacji, wyrażona w klatkach na sekundę (FPS). -Flip horizontal (Odbicie w poziomie) +Flip horizontal : Odbija animację w poziomie. -Flip vertical (Odbicie w pionie) +Flip vertical : Odbija animację w pionie. -Playback (Odtwarzanie) -: Określa, w jaki sposób animacja ma być odtwarzana: +Playback +: Określa, jak animacja ma być odtwarzana: - - `None` - animacja nie jest odtwarzana wcale, wyświetlany jest pierwszy obraz. - - `Once Forward` - odtwarza animację raz od pierwszego do ostatniego obrazu. - - `Once Backward` - odtwarza animację raz od ostatniego do pierwszego obrazu. - - `Once Ping Pong` - odtwarza animację raz od pierwszego do ostatniego obrazu, a następnie z powrotem do pierwszego obrazu. - - `Loop Forward` - odtwarza animację cyklicznie od pierwszego do ostatniego obrazu. - - `Loop Backward` - odtwarza animację cyklicznie od ostatniego do pierwszego obrazu. - - `Loop Ping Pong` - odtwarza animację cyklicznie od pierwszego do ostatniego obrazu, a następnie z powrotem do pierwszego obrazu. + - `None` nie odtwarza niczego, wyświetlany jest pierwszy obraz. + - `Once Forward` odtwarza animację raz od pierwszego do ostatniego obrazu. + - `Once Backward` odtwarza animację raz od ostatniego do pierwszego obrazu. + - `Once Ping Pong` odtwarza animację raz od pierwszego do ostatniego obrazu, a następnie z powrotem do pierwszego obrazu. + - `Loop Forward` odtwarza animację wielokrotnie od pierwszego do ostatniego obrazu. + - `Loop Backward` odtwarza animację wielokrotnie od ostatniego do pierwszego obrazu. + - `Loop Ping Pong` odtwarza animację wielokrotnie od pierwszego do ostatniego obrazu, a następnie z powrotem do pierwszego obrazu. -## Tworzenie tekstury i atlasu w czasie wykonania programu (Runtime) +## Tworzenie tekstury i atlasu w czasie działania programu -Począwszy od Defold 1.4.2 możliwe jest tworzenie zasobu tekstury i atlasu w czasie wykonania. +Począwszy od Defold 1.4.2 można tworzyć teksturę i atlas w czasie działania programu. -### Tworzenie zasobu tekstury w czasie wykonania +### Tworzenie zasobu tekstury w czasie działania programu -Użyj funkcji [`resource.create_texture(path, params)`](https://defold.com/ref/stable/resource/#resource.create_texture:path-table), aby utworzyć nowy zasób tekstury: +Użyj [`resource.create_texture(path, params)`](https://defold.com/ref/stable/resource/#resource.create_texture:path-table), aby utworzyć nowy zasób tekstury: ```lua local params = { @@ -134,7 +148,7 @@ Użyj funkcji [`resource.create_texture(path, params)`](https://defold.com/ref/s local my_texture_id = resource.create_texture("/my_custom_texture.texturec", params) ``` -Kiedy tekstura jest utworzona użyj funkcji [`resource.set_texture(path, params, buffer)`](https://defold.com/ref/stable/resource/#resource.set_texture:path-table-buffer) w celu ustawienia pikseli tekstury: +Gdy tekstura zostanie utworzona, użyj [`resource.set_texture(path, params, buffer)`](https://defold.com/ref/stable/resource/#resource.set_texture:path-table-buffer), aby ustawić piksele tekstury: ```lua local width = 128 @@ -157,7 +171,7 @@ Kiedy tekstura jest utworzona użyj funkcji [`resource.set_texture(path, params, ``` ::: sidenote -Istnieje także możliwość użycia funkcji `resource.set_texture()`, aby zaktualizować podregion tekstury, korzystając z szerokości i wysokości bufora mniejszych niż pełny rozmiar tekstury i zmieniając parametry x i y w funkcji resource.set_texture(). +Możliwe jest również użycie `resource.set_texture()`, aby zaktualizować podregion tekstury, korzystając z bufora o szerokości i wysokości mniejszych niż pełny rozmiar tekstury oraz zmieniając parametry x i y przekazywane do `resource.set_texture()`. ::: Teksturę można użyć bezpośrednio na [komponencie modelu](/manuals/model/) za pomocą `go.set()`: @@ -166,9 +180,9 @@ Teksturę można użyć bezpośrednio na [komponencie modelu](/manuals/model/) z go.set("#model", "texture0", my_texture_id) ``` -### Tworzenie atlasu w czasie wykonania +### Tworzenie atlasu w czasie działania programu -Jeśli tekstura ma być używana na [komponencie sprite'a](/manuals/sprite/), musi najpierw zostać użyta w atlasie. Użyj funckji [`resource.create_atlas(path, params)`](https://defold.com/ref/stable/resource/#resource.create_atlas:path-table), aby utworzyć atlas: +Jeśli tekstura ma być używana na [komponencie sprite'a](/manuals/sprite/), najpierw musi zostać użyta przez atlas. Użyj [`resource.create_atlas(path, params)`](https://defold.com/ref/stable/resource/#resource.create_atlas:path-table), aby utworzyć atlas: ```lua local params = { @@ -202,10 +216,10 @@ Jeśli tekstura ma być używana na [komponencie sprite'a](/manuals/sprite/), mu } local my_atlas_id = resource.create_atlas("/my_atlas.texturesetc", params) - -- assign the atlas to the 'sprite' component on the same go + -- przypisz atlas do komponentu 'sprite' w tym samym obiekcie gry go.set("#sprite", "image", my_atlas_id) - -- play the "animation" + -- odtwórz "animację" sprite.play_flipbook("#sprite", "my_animation") ``` diff --git a/docs/pl/manuals/bob.md b/docs/pl/manuals/bob.md new file mode 100644 index 00000000..79f7343a --- /dev/null +++ b/docs/pl/manuals/bob.md @@ -0,0 +1,225 @@ +--- +title: Podręcznik Boba do budowania projektów w Defold +brief: Bob to narzędzie wiersza poleceń do budowania projektów w Defold. Ten podręcznik wyjaśnia, jak korzystać z narzędzia. +--- + +# Bob, narzędzie do budowania + +Bob to narzędzie wiersza poleceń służące do budowania projektów w Defold poza normalnym przepływem pracy w edytorze. + +Bob potrafi budować dane projektu (co odpowiada wybraniu w edytorze pozycji Project ▸ Build), tworzyć archiwa danych oraz tworzyć samodzielne pakiety aplikacji gotowe do dystrybucji (co odpowiada opcjom menu edytora Project ▸ Bundle ▸ ...). + +Bob jest dystrybuowany jako archiwum Java _JAR_ zawierające wszystko, czego potrzeba do budowania. Najnowszą wersję *bob.jar* znajdziesz na [stronie wydań GitHub Releases](https://github.com/defold/defold/releases). Wybierz wydanie, a następnie pobierz *bob/bob.jar*. Jeśli używasz Defold 1.12.0 lub nowszego, do uruchomienia potrzebujesz OpenJDK 25. W przypadku starszych wersji Defold potrzebujesz OpenJDK 21. + +Zgodne dystrybucje OpenJDK 25 (dla Defold 1.12.0 i nowszego): +* [OpenJDK 25 firmy Microsoft](https://learn.microsoft.com/en-us/java/openjdk/download#openjdk-25) +* [OpenJDK 25 od Adoptium Working Group](https://github.com/adoptium/temurin25-binaries/releases) / [Adoptium.net](https://adoptium.net/) + +Jeśli korzystasz z systemu Windows, wybierz instalator `.msi` OpenJDK. + +## Użycie + +Bob uruchamia się z powłoki lub z wiersza poleceń, wywołując `java` (lub `java.exe` w Windows) i podając archiwum JAR Boba jako argument: + +```text +$ java -jar bob.jar --help +usage: bob [options] [commands] + -a,--archive Build archive + -ar,--architectures Comma separated list of + architectures to include for the + platform + --archive-resource-padding The alignment of the resources in + the game archive. Default is 4 + -bf,--bundle-format Which formats to create the + application bundle in. Comma + separated list. (Android: 'apk' + and 'aab') + --binary-output Location where built engine + binary will be placed. Default is + "//" + -bo,--bundle-output Bundle output directory + -br,--build-report DEPRECATED! Use + --build-report-json instead + -brhtml,--build-report-html Filepath where to save a build + report as HTML + -brjson,--build-report-json Filepath where to save a build + report as JSON + --build-artifacts If left out, will default to + build the engine. Choices: + 'engine', 'plugins', 'library'. + Comma separated list. + --build-server The build server (when using + native extensions) + --build-server-header Additional build server header to + set + -ce,--certificate DEPRECATED! Use --keystore + instead + -d,--debug DEPRECATED! Use --variant=debug + instead + --debug-ne-upload Outputs the files sent to build + server as upload.zip + --debug-output-spirv Force build SPIR-V shaders + --debug-output-wgsl Force build WGSL shaders + --defoldsdk What version of the defold sdk + (sha1) to use + -e,--email User email + -ea,--exclude-archive Exclude resource archives from + application bundle. Use this to + create an empty Defold + application for use as a build + target + --exclude-build-folder DEPRECATED! Use '.defignore' file + instead + -h,--help This help message + -i,--input DEPRECATED! Use --root instead + --identity Sign identity (iOS) + -kp,--key-pass Password of the deployment key if + different from the keystore + password (Android) + -ks,--keystore Deployment keystore used to sign + APKs (Android) + -ksa,--keystore-alias The alias of the signing key+cert + you want to use (Android) + -ksp,--keystore-pass Password of the deployment + keystore (Android) + -l,--liveupdate Yes if liveupdate content should + be published + --manifest-private-key Private key to use when signing + manifest and archive. + --manifest-public-key Public key to use when signing + manifest and archive. + --max-cpu-threads Max count of threads that bob.jar + can use + -mp,--mobileprovisioning mobileprovisioning profile (iOS) + --ne-build-dir Specify a folder with includes or + source, to build a specific + library. More than one occurrence + is allowed. + --ne-output-name Specify a library target name + -o,--output Output directory. Default is + "build/default" + -p,--platform Platform (when building and + bundling) + -pk,--private-key DEPRECATED! Use --keystore + instead + -r,--root Build root directory. Default is + current directory + --resource-cache-local Path to local resource cache. + --resource-cache-remote URL to remote resource cache. + --resource-cache-remote-pass Password/token to authenticate + access to the remote resource + cache. + --resource-cache-remote-user Username to authenticate access + to the remote resource cache. + --settings Path to a game project settings + file. More than one occurrence is + allowed. The settings files are + applied left to right. + --strip-executable Strip the dmengine of debug + symbols (when bundling iOS or + Android) + -tc,--texture-compression Use texture compression as + specified in texture profiles + -tp,--texture-profiles DEPRECATED! Use + --texture-compression instead + -u,--auth User auth token + --use-async-build-server DEPRECATED! Asynchronous build is + now the default. + --use-lua-bytecode-delta Use byte code delta compression + when building for multiple + architectures + --use-uncompressed-lua-source Use uncompressed and unencrypted + Lua source code instead of byte + code + --use-vanilla-lua DEPRECATED! Use + --use-uncompressed-lua-source + instead. + -v,--verbose Verbose output + --variant Specify debug, release or + headless version of dmengine + (when bundling) + --version Prints the version number to the + output + --with-symbols Generate the symbol file (if + applicable) +``` + +Dostępne polecenia: + +`clean` +: Usuwa zbudowane pliki z katalogu build. + +`distclean` +: Usuwa wszystkie pliki z katalogu build. + +`build` +: Buduje wszystkie dane projektu. Dodaj opcję `--archive`, aby zbudować archiwum danych (`game.darc` w katalogu build). + +`bundle` +: Tworzy pakiet aplikacji dla konkretnej platformy. Utworzenie pakietu wymaga zbudowanego archiwum (`build` z opcją `--archive`) oraz wskazania platformy docelowej za pomocą opcji `--platform`. Bob tworzy pakiet w katalogu wyjściowym, chyba że podasz inny katalog za pomocą opcji `--bundle-output`. Nazwa pakietu jest brana z ustawienia nazwy projektu w *game.project*. Opcja `--variant` określa, jaki typ pliku wykonywalnego zbudować podczas tworzenia pakietu, a razem z opcją `--strip-executable` zastępuje opcję `--debug`. Jeśli nie podasz `--variant`, otrzymasz wersję release silnika, która na Android i iOS jest pozbawiona symboli. Ustawienie `--variant` na debug przy pominięciu `--strip-executable` daje ten sam typ pliku wykonywalnego, jaki wcześniej zapewniała opcja `--debug`. + +`resolve` +: Rozwiązuje wszystkie zależności bibliotek zewnętrznych. + +Dostępne platformy i architektury: + +`x86_64-darwin` (Defold 1.3.5 i starsze) +`x86_64-macos` (Defold 1.3.6 i nowsze) +: macOS 64-bit + +`arm64-macos` (Defold 1.5.0 i starsze) +: macOS Apple Silicon (ARM) + +`x86_64-win32` +: Windows 64-bit + +`x86-win32` +: Windows 32-bit + +`x86_64-linux` +: Linux 64-bit + +`x86_64-ios` +: iOS na macOS 64-bit (symulator iOS) + +`armv7-darwin` (Defold 1.3.5 i starsze) +`armv7-ios` (Defold 1.3.6 i nowsze) +: iOS z dostępnymi 32-bitowymi architekturami `armv7-darwin` i 64-bitowymi `arm64-darwin`. Domyślnie wartość argumentu `--architectures` to `armv7-darwin,arm64-darwin`. + +`armv7-android` +: Android z dostępnymi 32-bitowymi architekturami `armv7-android` i 64-bitowymi `arm64-android`. Domyślnie wartość argumentu `--architectures` to `armv7-android,arm64-android`. + +`js-web` +: HTML5 z dostępnymi architekturami `js-web`, `wasm-web` i `wasm_pthread-web`. Domyślnie wartość argumentu `--architectures` to `js-web,wasm-web`. + +Domyślnie Bob szuka projektu do zbudowania w bieżącym katalogu. Jeśli przejdziesz do katalogu projektu Defold i uruchomisz Boba, zbuduje dane projektu w domyślnym katalogu wyjściowym *build/default*. + +```sh +$ cd /Applications/Defold-beta/branches/14/4/main +$ java -jar bob.jar +100% +$ +``` + +Możesz łączyć polecenia, aby jednym uruchomieniem wykonać sekwencję zadań. W poniższym przykładzie najpierw rozwiązywane są zależności bibliotek, potem czyszczony jest katalog build, budowane jest archiwum danych, a na końcu tworzony jest pakiet aplikacji na macOS (o nazwie *My Game.app*): + +```sh +$ java -jar bob.jar --archive --platform x86-darwin resolve distclean build bundle +100% +$ ls -al build/default/ +total 70784 +drwxr-xr-x 13 sicher staff 442 1 Dec 10:15 . +drwxr-xr-x 3 sicher staff 102 1 Dec 10:15 .. +drwxr-xr-x 3 sicher staff 102 1 Dec 10:15 My Game.app +drwxr-xr-x 8 sicher staff 272 1 Dec 10:15 builtins +-rw-r--r-- 1 sicher staff 140459 1 Dec 10:15 digest_cache +drwxr-xr-x 4 sicher staff 136 1 Dec 10:15 fonts +-rw-r--r-- 1 sicher staff 35956340 1 Dec 10:15 game.darc +-rw-r--r-- 1 sicher staff 735 1 Dec 10:15 game.projectc +drwxr-xr-x 223 sicher staff 7582 1 Dec 10:15 graphics +drwxr-xr-x 3 sicher staff 102 1 Dec 10:15 input +drwxr-xr-x 20 sicher staff 680 1 Dec 10:15 logic +drwxr-xr-x 27 sicher staff 918 1 Dec 10:15 sound +-rw-r--r-- 1 sicher staff 131926 1 Dec 10:15 state +$ +``` diff --git a/docs/pl/manuals/buffer.md b/docs/pl/manuals/buffer.md new file mode 100644 index 00000000..260ae459 --- /dev/null +++ b/docs/pl/manuals/buffer.md @@ -0,0 +1,33 @@ +--- +title: Bufor +brief: Ta instrukcja wyjaśnia, jak działają zasoby Buffer w silniku Defold. +--- + +# Bufor + +Zasób Buffer służy do opisywania jednego lub wielu strumieni wartości, na przykład pozycji albo kolorów. Każdy strumień ma nazwę, typ danych, liczbę wartości oraz same dane. Przykład: + +``` +[ + { + "name": "position", + "type": "float32", + "count": 3, + "data": [ + -1.0, + -1.0, + -1.0, + -1.0, + -1.0, + 1.0, + ... + ] + } +] +``` + +Powyższy przykład opisuje strumień pozycji w trzech wymiarach, zapisanych jako 32-bitowe liczby zmiennoprzecinkowe. Format pliku zasobu Buffer to JSON, a jego rozszerzenie to `.buffer`. + +Zasoby Buffer są zazwyczaj tworzone przy użyciu zewnętrznych narzędzi lub skryptów, na przykład podczas eksportu z programów do modelowania, takich jak Blender. + +Zasób Buffer może być użyty jako dane wejściowe dla [komponentu Mesh](/manuals/mesh). Zasoby Buffer można też tworzyć w czasie działania przy użyciu `buffer.create()` oraz [powiązanych funkcji API](/ref/stable/buffer/#buffer.create:element_count-declaration). diff --git a/docs/pl/manuals/building-blocks.md b/docs/pl/manuals/building-blocks.md index e39d6aad..9a423b1c 100644 --- a/docs/pl/manuals/building-blocks.md +++ b/docs/pl/manuals/building-blocks.md @@ -1,112 +1,115 @@ --- -title: Podstawowe elementy silnika Defold -brief: Instrukcja ta przedstawia podstawowe elementy służące do budowania aplikacji w Defoldzie oraz opisuje jak działają obiekty, komponenty i kolekcje. +title: Podstawowe elementy Defold +brief: Ta instrukcja omawia szczegóły działania obiektów gry, komponentów i kolekcji. --- -# Podstawowe elementy do budowania aplikacji +# Podstawowe elementy -W samym sercu koncepcji silnika Defold znajduje się kilka elementów, których zrozumienie ułatwia dalszą pracę z silnikiem. Instrukcja ta wyjaśnia czym są takie bloki służące do budowania aplikacji. Po zapoznaniu się z poniższą instrukcją, warto przejść do [Instrukcji adresowania](/manuals/addressing) i [przesyłania wiadomości](/manuals/message-passing). Na stronie Defold znajdziesz również [tutoriale](/tutorials/getting-started) dla początkujących dostępne nawet z poziomu edytora, aby umożliwić Ci szybki start z silnikiem Defold. +W centrum projektu Defold stoi kilka kluczowych pojęć, które warto dobrze poznać. Ta instrukcja wyjaśnia, z czego składają się podstawowe elementy Defold. Po jej przeczytaniu przejdź do [instrukcji adresowania](/manuals/addressing) i [instrukcji przesyłania wiadomości](/manuals/message-passing). W edytorze dostępny jest też zestaw [tutoriali](/tutorials/getting-started), które pomogą szybko zacząć pracę. -![Building blocks](images/building_blocks/building_blocks.png) +![Podstawowe elementy](images/building_blocks/building_blocks.png) -Przy budowaniu gier na silniku Defold używa się trzech podstawowych elementów: +Do budowy gry w Defold używa się trzech podstawowych typów elementów: -Kolekcja (Collection) -: Kolekcja jest plikiem używanym do stworzenia struktury Twojej gry. W kolekcjach buduje się hierarchię obiektów gry (poniżej) i innych kolekcji. Kolekcja jest więc po prostu zbiorem obiektów i innych kolekcji. Zazwyczaj używa się ich do stworzenia struktury całych poziomów w grach czy też grup wrogów, postaci, pocisków czy innych elementów (wielu obiektów). +Kolekcja +: Kolekcja to plik służący do strukturyzowania gry. W kolekcjach buduje się hierarchie obiektów gry i innych kolekcji. Zwykle wykorzystuje się je do organizacji poziomów, grup przeciwników albo postaci złożonych z kilku obiektów gry. -Obiekt gry (Game object) -: Obiekty gry są pojemnikami zawierającymi identyfikator (id), pozycję, orientację i skalę oraz mogą zawierać dodatkowo tzw. komponenty (poniżej). Są używane zazwyczaj do tworzenia postaci gracza, innych pojedynczych elementów, lub systemów tworzenia zasad gry oraz jako elementy wczytujące i zwalniające dane poziomy. +Obiekt gry +: Obiekt gry to kontener z identyfikatorem, pozycją, rotacją i skalą. Służy do przechowywania komponentów. Zwykle wykorzystuje się go do tworzenia postaci gracza, pocisków, systemu zasad gry albo wczytywacza poziomów. -Komponent (Component) -: Komponenty to elementy, które są umieszczane wewnątrz obiektów, aby nadać im cechy zgodne z ich typem - reprezentację wizualną (sprite, model, particlefx), dźwiękową (sound) czy logiczną (script). Są zazwyczaj używane do stworzenia sprite'ów czy modeli postaci, dodawania skryptów do obiektów czy efektów dźwiękowych czy cząsteczkowych. +Komponent +: Komponenty to elementy umieszczane w obiekcie gry, aby nadać mu wizualną, dźwiękową i/lub logiczną reprezentację w grze. Zwykle wykorzystuje się je do tworzenia sprite'ów postaci, skryptów, efektów dźwiękowych albo efektów cząsteczkowych. ## Kolekcje -Kolekcje mają strukturę drzewa, która przechowuje obiekty i inne kolekcje. Kolekcje są zawsze przechowywane w formie pliku. +Kolekcje są strukturami drzewiastymi, które przechowują obiekty gry i inne kolekcje. Kolekcja jest zawsze zapisana w pliku. -Kiedy Defold startuje, wczytuje pojedynczą, główną _kolekcję bootrstrapową_ określoną w pliku *game.project*. Kolekcja bootstrapowa jest często nazywana "main.collection" (i tak jest też domyślnie nazwana po otwarciu każdego nowego projektu), ale oczywiście możesz używać dowolnej nazwy. +Gdy silnik Defold uruchamia się, wczytuje jedną _bootstrap collection_ zgodnie z ustawieniami w pliku *game.project*. Taka kolekcja bootstrapowa często nazywa się "main.collection", ale możesz użyć dowolnej nazwy. -Kolekcja może zawierać obiekty i inne kolekcje (przez referencję do pliku sub-kolekcji) zagnieżdżone na dowolną "głębokość". Poniżej jest przykład kolekcji "main.collection". Zawiera ona jeden obiekt gry (z id "can")i jedną sub-kolekcję (z id "bean"). Sub-kolekcja ta zawiera z kolei obiekty "bean" i "shield". +Kolekcja może zawierać obiekty gry i inne kolekcje, odwołując się do pliku podkolekcji, na dowolnej głębokości zagnieżdżenia. Oto przykład pliku "main.collection". Zawiera on jeden obiekt gry z identyfikatorem "can" oraz jedną podkolekcję z identyfikatorem "bean". Sama podkolekcja zawiera z kolei dwa obiekty gry: "bean" i "shield". ![Collection](images/building_blocks/collection.png) -Zauważ, że sub-kolekcja z id "bean" jest przechowywana w osobnym pliku nazwanym "/main/bean.collection", a kolekcja nadrzędna "main.collection" zawiera do tego pliku jedynie referencję: +Zwróć uwagę, że podkolekcja o identyfikatorze "bean" jest zapisana we własnym pliku "/main/bean.collection" i w "main.collection" występuje tylko jako odwołanie: ![Bean collection](images/building_blocks/bean_collection.png) -Nie można zaadresować kolekcji samej w sobie, ponieważ nie istnieją obiekty w czasie rzeczywistym, które reprezentują kolekcje "main" czy "bean" - nie można więc wysłać wiadomości do kolekcji samej w sobie, a tylko do obiektów i komponentów. Jednak czasem chcesz wysłać wiadomość do obiektu z innej kolekcji niż kolekcja, w której nadawca się znajduje, więc dlatego określą się ścieżkę (ang. _path_) do takiego obiektu z uwzględnieniem id kolekcji (Szczegóły znajdziesz w [Instrukcji adresowania](/manuals/addressing)): +Nie można adresować samych kolekcji, ponieważ nie ma w czasie działania obiektów odpowiadających kolekcjom "main" i "bean". Czasami jednak identyfikator kolekcji jest potrzebny jako część _ścieżki_ do obiektu gry. Szczegóły znajdziesz w [instrukcji adresowania](/manuals/addressing): ```lua --- file: can.script --- get position of the "bean" game object in the "bean" collection +-- plik: can.script +-- pozycja obiektu gry "bean" w kolekcji "bean" local pos = go.get_position("bean/bean") ``` -Kolekcja dodawana do innej kolekcji jest zawsze referencją do _pliku_ kolekcji: +Kolekcję zawsze dodaje się do innej kolekcji jako odwołanie do pliku kolekcji: -Naciśnij Prawy-przycisk-myszki na kolekcji w panelu *Outline* i wybierz Add Collection File. +Kliknij prawym przyciskiem myszy kolekcję w widoku *Outline* i wybierz Add Collection File. ## Obiekty gry -Obiekty gry to bardzo proste obiekty posiadające indywidualny czas życia w trakcie wykonywania programu. Posiadają pozycję, orientację i skalę, a parametry te mogą być manipulowane i animowane osobno w czasie działania programu. +Obiekty gry to proste obiekty, z których każdy ma własny cykl życia w czasie działania gry. Mają pozycję, rotację i skalę, którymi można sterować i które można animować w czasie działania. ```lua --- animate X position of "can" game object +-- animuje pozycję X obiektu gry "can" go.animate("can", "position.x", go.PLAYBACK_LOOP_PINGPONG, 100, go.EASING_LINEAR, 1.0) ``` -Obiekty gry mogą być używane jako puste obiekty (jako znacznik pozycji (ang. waypoint, startpoint, checkpoint etc.)), ale najczęściej zawierają komponenty, takie jak sprite'y, dźwięki, skrypty, modele, fabryki, efekty cząsteczkowe i inne. Obiekty te są tworzone albo z poziomu edytora i umieszczane bezpośrednio w plikach kolekcji (statycznie) albo dynamicznie, w kodzie, dzięki fabrykom (ang. _factory_). +Obiekty gry mogą być puste, na przykład jako znaczniki pozycji, ale zwykle wyposaża się je w różne komponenty, takie jak sprite'y, dźwięki, skrypty, modele, fabryki i inne. Obiekty gry są tworzone w edytorze, umieszczane w plikach kolekcji albo dynamicznie tworzone w czasie działania przez komponenty _factory_. -Obiekty gry są więc dodawane jako nowe obiekty zdefiniowane w pliku kolekcji lub również w pliku kolekcji, ale jako referencja do osobnego pliku z definicją obiektu gry: - -Naciśnij Prawy-przycisk-myszki na kolekcji w panelu *Outline* i wybierz Add Game Object (dodasz definicję do kolekcji) or Add Game Object File (dodasz do kolekcji referencję do pliku z definicją obiektu). - -Jest to jeszcze dogłębniej wytłumaczone poniżej. +Obiekty gry można dodać bezpośrednio w kolekcji albo jako odwołanie do pliku obiektu gry: +Kliknij prawym przyciskiem myszy kolekcję w widoku *Outline* i wybierz Add Game Object (dodanie bezpośrednio) lub Add Game Object File (dodanie jako odwołanie do pliku). ## Komponenty :[components](../shared/components.md) -Odsyłamy do osobnej [Instrukcji do komponentów](/manuals/components/), gdzie znajduje się lista wszystkich komponentów silnika Defold. +Zobacz [przegląd komponentów](/manuals/components/), aby uzyskać listę wszystkich dostępnych typów komponentów. -## Obiekty dodawane bezpośrednio i z pliku +## Obiekty dodawane bezpośrednio lub przez odwołanie -Kiedy tworzysz _plik_ kolekcji, obiektu gry lub nawet komponentu (np. w panelu *Assets*), tak naprawdę tworzysz tylko szablon, prototyp (ang. blueprint, prototype). Tworzy to tylko i wyłącznie plik w strukturze Twojego projektu, natomiast nic nie jest dodawane do samej gry. Aby stworzyć _instancję_ kolekcji, obiektu czy komponentu do gry, która bazuje na takim pliku-szablonie, dodać należy taką instancję w jednej z Twoich kolekcji. +Gdy tworzysz _plik_ kolekcji, obiektu gry lub komponentu, tworzysz to, co nazywa się prototypem (w innych silnikach spotyka się też określenia "prefab" i "blueprint"). Taki krok dodaje tylko plik do struktury projektu, nic jeszcze nie trafia do uruchomionej gry. Aby dodać instancję kolekcji, obiektu gry lub komponentu opartą na pliku prototypu, trzeba wstawić ją do jednego z plików kolekcji. -W panelu *Outline* możesz zobaczyć na jakim pliku bazuje dana instancja, jeśli była ona stworzona z pliku, a nie bezpośrednio w panelu *Outline* właśnie. Przykładowo, kolekcja "main.collection" poniżej zawiera trzy instancje, które bazują na już utworzonych plikach: +W widoku Outline możesz sprawdzić, na jakim pliku bazuje instancja obiektu. Plik "main.collection" zawiera trzy instancje oparte na plikach: -1. Sub-kolekcja "bean". -2. Komponent typu skrypt "bean" w obiekcie "bean" w sub-kolekcji "bean". -3. Komponent typu skrypt "can" w obiekcie "can". +1. Podkolekcję "bean". +2. Komponent skryptowy "bean" w obiekcie gry "bean" w podkolekcji "bean". +3. Komponent skryptowy "can" w obiekcie gry "can". ![Instance](images/building_blocks/instance.png) -Korzyścią z używania szablonów/plików jest zdecydowanie możliwość stworzenia wielu instancji obiektu gry lub kolekcji i zmiana ich wszystkich naraz w jednym pliku: +Zaleta tworzenia plików prototypów staje się szczególnie widoczna, gdy masz wiele instancji obiektu gry lub kolekcji i chcesz zmienić je wszystkie naraz: ![GO instances](images/building_blocks/go_instance.png) -Przy zmianie pliku każda instancja utworzona z tego pliku zostaje natychmiastowo zaktualizowana: +Zmieniając plik prototypu, natychmiast aktualizujesz każdą instancję, która z niego korzysta. + +![GO changing prototype](images/building_blocks/go_change_blueprint.png) + +Tutaj zmieniono obraz sprite'a w pliku prototypu i wszystkie instancje korzystające z tego pliku zostały od razu zaktualizowane: ![GO instances updated](images/building_blocks/go_instance2.png) -## Hierarchia obiektów gry - relacja rodzic-dziecko +## Hierarchie rodzic-dziecko obiektów gry -W pliku kolekcji możesz tworzyć hierarchie obiektów gry (game objects) w ten sposób, że jeden z obiektów jest dzieckiem innego obiektu - rodzica. Po prostu przeciągnij jeden z obiektów gry i upuść nad innym obiektem - zostanie on umieszczony w drzewku pod tym obiektem i stanie się jego dzieckiem: +W pliku kolekcji możesz budować hierarchie obiektów gry tak, aby jeden lub więcej obiektów gry był dzieckiem jednego obiektu-rodzica. Po prostu przeciągnij jeden obiekt gry i upuść go na drugi, a przeciągany obiekt stanie się dzieckiem celu: ![Childing game objects](images/building_blocks/childing.png) -Relacja rodzic-dziecko jest dynamiczną relacją wpływającą na zmianę pozycji, orientacji i skali obu obiektów. Każda transformacja tych wartości zaaplikowana do obiektu rodzica zostanie następnie zaaplikowana do obiektu dziecka, aby ich wzajemna, względna pozycja/orientacja/skala pozostała taka sama, 1:1, zarówno w edytorze jak i w czasie działania programu: +Hierarchia rodzic-dziecko to dynamiczna relacja wpływająca na to, jak obiekty reagują na transformacje. Każda transformacja, czyli ruch, obrót lub skalowanie, zastosowana do obiektu zostanie z kolei zastosowana do jego dzieci, zarówno w edytorze, jak i w czasie działania: ![Child transform](images/building_blocks/child_transform.png) -Z kolei wszystkie transformacje na obiekcie dziecku są wykonywane w układzie odniesienia rodzica. W edytorze Defold możesz wybrać, czy operacje na obiekcie dziecku są wykonywane w układzie lokalnym rodzica (local space) czy w głównym układzie odniesienia (world space) klikając Edit ▸ World Space (domyślnie ustawione) lub Edit ▸ Local Space. +Z kolei przesunięcia dziecka są wykonywane w lokalnej przestrzeni rodzica. W edytorze możesz wybrać, czy chcesz edytować obiekt-dziecko w przestrzeni lokalnej czy w przestrzeni świata, wybierając Edit ▸ World Space (domyślnie) albo Edit ▸ Local Space. -Jest też możliwe zmienienie rodzica danego obiektu przez wysłanie do niego wiadomości `set_parent`. +Możliwe jest też zmienienie rodzica obiektu w czasie działania przez wysłanie do obiektu wiadomości `set_parent`. ```lua local parent = go.get_id("bean") msg.post("child_bean", "set_parent", { parent_id = parent }) ``` -Częstym błędem jest postrzeganie przypisania obiektu jako dziecka innego obiektu w kolekcji jako zmiana miejsca tego obiektu w hierarchii kolekcji. Są to jednak dwie osobne rzeczy. Relacje rodzic-dziecko dynamicznie zmieniają graf w panelu *Outline*, co pozwala wizualnie ją przedstawić. Jedyną rzeczą, która określa adres obiektu jest jej miejsce w hierarchii kolekcji. Adres jest statyczny podczas całego cyklu życia obiektu. +::: important +Częstym nieporozumieniem jest myślenie, że miejsce obiektu gry w hierarchii kolekcji zmienia się wtedy, gdy staje się on częścią hierarchii rodzic-dziecko. To jednak dwie zupełnie różne rzeczy. Hierarchie rodzic-dziecko dynamicznie zmieniają graf sceny, co pozwala wizualnie łączyć obiekty. Jedyną rzeczą, która określa adres obiektu gry, jest jego miejsce w hierarchii kolekcji. Adres pozostaje statyczny przez cały czas życia obiektu. +::: diff --git a/docs/pl/manuals/bundling.md b/docs/pl/manuals/bundling.md new file mode 100644 index 00000000..a6258768 --- /dev/null +++ b/docs/pl/manuals/bundling.md @@ -0,0 +1,87 @@ +--- +title: Tworzenie pakietu aplikacji +brief: Ta instrukcja opisuje, jak utworzyć pakiet aplikacji. +--- + +# Tworzenie pakietu aplikacji + +Podczas pracy nad aplikacją warto wyrobić sobie nawyk możliwie częstego testowania gry na platformach docelowych. Pozwala to wcześnie wykryć problemy z wydajnością, gdy są jeszcze znacznie łatwiejsze do naprawienia. Zalecamy też testowanie na wszystkich platformach docelowych, aby wychwycić różnice, na przykład w shaderach. Podczas pracy nad aplikacjami mobilnymi możesz używać [aplikacji deweloperskiej na urządzenia mobilne (mobile development app)](/manuals/dev-app/) do przesyłania zawartości do aplikacji, zamiast za każdym razem tworzyć pełny pakiet i przechodzić przez cykl odinstalowania oraz ponownej instalacji. + +Pakiet aplikacji dla wszystkich platform obsługiwanych przez Defold możesz utworzyć bezpośrednio w edytorze Defold, bez potrzeby używania zewnętrznych narzędzi. Możesz też tworzyć pakiety z wiersza poleceń, korzystając z naszych narzędzi wiersza poleceń. Tworzenie pakietu aplikacji wymaga połączenia sieciowego, jeśli projekt zawiera jedno lub więcej [rozszerzeń natywnych](/manuals/extensions). + +## Tworzenie pakietu w edytorze + +Pakiet aplikacji tworzysz z menu projektu, wybierając Project ▸ Bundle...: + +![](images/bundling/bundle_menu.png) + +Wybranie dowolnej z tych opcji otworzy okno dialogowe Bundle dla tej konkretnej platformy. + +### Raporty budowania + +Podczas tworzenia pakietu gry możesz utworzyć raport budowania. To bardzo przydatne, gdy chcesz lepiej ocenić rozmiar wszystkich zasobów wchodzących w skład pakietu gry. Po prostu zaznacz pole wyboru *Generate build report* podczas tworzenia pakietu. + +![raport budowania](images/profiling/build_report.png) + +Więcej informacji o raportach budowania znajdziesz w [podręczniku profilowania](/manuals/profiling/#build-reports). + +### Android + +Tworzenie pakietu aplikacji dla Androida (.apk) opisano w [podręczniku Androida](/manuals/android/#creating-an-android-application-bundle). + +### iOS + +Tworzenie pakietu aplikacji dla iOS (.ipa) opisano w [podręczniku iOS](/manuals/ios/#creating-an-ios-application-bundle). + +### macOS + +Tworzenie pakietu aplikacji dla macOS (.app) opisano w [podręczniku macOS](/manuals/macos). + +### Linux + +Tworzenie pakietu aplikacji dla systemu Linux nie wymaga żadnej konkretnej konfiguracji ani opcjonalnych ustawień specyficznych dla platformy w *game.project* [pliku ustawień projektu](/manuals/project-settings/#linux). + +### Windows + +Tworzenie pakietu aplikacji dla systemu Windows (.exe) opisano w [podręczniku Windows](/manuals/windows). + +### HTML5 + +Tworzenie pakietu aplikacji HTML5 oraz opcjonalną konfigurację opisano w [podręczniku HTML5](/manuals/html5/#creating-html5-bundle). + +#### Facebook Instant Games + +Można utworzyć specjalną wersję pakietu aplikacji HTML5 dla Facebook Instant Games. Proces ten opisano w [podręczniku Facebook Instant Games](/manuals/instant-games/). + +## Tworzenie pakietu z wiersza poleceń + +Edytor używa naszego narzędzia wiersza poleceń [Bob](/manuals/bob/) do tworzenia pakietów aplikacji. + +Na co dzień prawdopodobnie będziesz budować projekt i tworzyć pakiety bezpośrednio w edytorze Defold. W innych sytuacjach możesz chcieć automatycznie generować pakiety, na przykład wsadowo budować je dla wszystkich platform docelowych przy wydawaniu nowej wersji albo przygotowywać nocne kompilacje najnowszej wersji gry, na przykład w środowisku CI. Budowanie i tworzenie pakietów można wykonywać poza standardowym przepływem pracy edytora, korzystając z [narzędzia wiersza poleceń Bob](/manuals/bob/). + +## Układ pakietu + +Logiczny układ pakietu wygląda tak: + +![](images/bundling/bundle_schematic_01.png) + +Pakiet jest zapisywany w folderze. W zależności od platformy ten folder może zostać też spakowany do archiwum `.apk` lub `.ipa`. Zawartość folderu zależy od platformy. + +Oprócz plików wykonywalnych proces tworzenia pakietu zbiera również wymagane zasoby dla danej platformy, na przykład pliki zasobów XML dla Androida. + +Za pomocą ustawienia [bundle_resources](https://defold.com/manuals/project-settings/#bundle-resources) możesz skonfigurować zasoby, które powinny zostać umieszczone w pakiecie bez zmian. Możesz to kontrolować osobno dla każdej platformy. + +Zasoby gry znajdują się w pliku `game.arcd` i są indywidualnie kompresowane algorytmem LZ4. +Za pomocą ustawienia [custom_resources](https://defold.com/manuals/project-settings/#custom-resources) możesz skonfigurować zasoby, które powinny zostać umieszczone w `game.arcd` z kompresją. +Możesz uzyskać do nich dostęp za pomocą funkcji [`sys.load_resource()`](https://defold.com/ref/sys/#sys.load_resource). + +## Wersje release i debug + +Podczas tworzenia pakietu możesz wybrać wariant debug lub release. Różnice między nimi są niewielkie, ale warto je znać: + +* Wersje release nie zawierają [profilera](/manuals/profiling) +* Wersje release nie zawierają [rejestratora ekranu](/ref/stable/sys/#start_record) +* Wersje release nie wyświetlają wyników działania `print()` ani danych wyjściowych z natywnych rozszerzeń +* Wersje release mają wartość `is_debug` w `sys.get_engine_info()` ustawioną na `false` +* Wersje release nie wykonują odwrotnego wyszukiwania wartości `hash` podczas wywoływania `tostring()`. W praktyce oznacza to, że `tostring()` dla wartości typu `url` lub `hash` zwróci ich numeryczną reprezentację, a nie oryginalny ciąg (`'hash: [/camera_001]'` vs `'hash: [11844936738040519888 (unknown)]'`) +* Wersji release nie można wybrać w edytorze jako celu dla [szybkiego przeładowania](/manuals/hot-reload) i podobnych funkcji diff --git a/docs/pl/manuals/camera.md b/docs/pl/manuals/camera.md index 93f522d3..8584a3e9 100644 --- a/docs/pl/manuals/camera.md +++ b/docs/pl/manuals/camera.md @@ -1,63 +1,120 @@ --- -title: Kamera -brief: Ta instrukcja opisuje komponent Kamery w Defoldzie. +title: Instrukcja komponentu Camera +brief: Ta instrukcja opisuje działanie komponentu Camera w silniku Defold. --- -# Kamera +# Kamery -Kamera (ang. camera) w Defoldzie jest komponentem, który zmienia widok i projekcję świata gry. Komponent kamery definiuje podstawową kamerę perspektywiczną lub ortograficzną, która dostarcza macierz widoku i projekcji do skryptu renderującego (ang. render script). +Kamera (ang. camera) w silniku Defold jest komponentem, który zmienia obszar widoczny i projekcję świata gry. Komponent Camera definiuje podstawową kamerę perspektywiczną albo ortograficzną i przekazuje do skryptu renderującego macierz widoku oraz macierz projekcji. -Kamera perspektywiczna jest zazwyczaj używana w grach 3D, gdzie widok kamery oraz wielkość i perspektywa obiektów oparte są na tzw. bryle widokowej (ang. view frustum) oraz odległości i kącie widzenia od kamery do obiektów w grze. +Kamera perspektywiczna jest zwykle używana w grach 3D, gdzie widok kamery oraz rozmiar i perspektywa obiektów zależą od bryły widoku (frustum), odległości od kamery i kąta patrzenia na obiekty w grze. -W grach 2D często pożądane jest renderowanie sceny za pomocą rzutu ortograficznego. Oznacza to, że widok kamery jest określany przez specjalną bryłę widokową - prostopadłościan. Rzut ortograficzny jest nierealistyczny, ponieważ nie zmienia rozmiaru obiektów na podstawie ich odległości. Obiekt oddalony o 1000 jednostek zostanie narysowany w takim samym rozmiarze jak obiekt tuż przed kamerą. +W grach 2D często pożądane jest renderowanie sceny z użyciem projekcji ortograficznej. Oznacza to, że widok kamery nie jest już wyznaczany przez bryłę widoku, lecz przez prostokątny obszar. Projekcja ortograficzna jest niefotorealistyczna, ponieważ nie zmienia rozmiaru obiektów zależnie od ich odległości. Obiekt oddalony o 1000 jednostek zostanie narysowany w takim samym rozmiarze jak obiekt znajdujący się tuż przed kamerą. -![projekcje](images/camera/projections.png) +![projections](images/camera/projections.png) ## Tworzenie kamery -Aby utworzyć kamerę, kliknij prawym przyciskiem myszy na obiekcie gry i wybierz Add Component ▸ Camera. Możesz także utworzyć plik komponentu w hierarchii projektu (*Outline*) i dodać go do obiektu gry. +Aby utworzyć kamerę, right click obiekt gry i wybierz Add Component ▸ Camera. Możesz też utworzyć plik komponentu w hierarchii projektu i dodać ten plik komponentu do obiektu gry. -![tworzenie kamery](images/camera/create.png) +![create camera component](images/camera/create.png) -Komponent kamery ma następujące właściwości, które definiują bryłę kamery (*frustum*): +Komponent Camera ma następujące właściwości definiujące jego *frustum*: -![ustawienia kamery](images/camera/settings.png) +![camera settings](images/camera/settings.png) Id -: Identyfikator komponentu +: Id komponentu. Aspect Ratio -: (**Tylko dla kamery perspektywicznej**) Współczynnik proporcji - stosunek szerokości bryły widokowej do jej wysokości. Wartość 1.0 oznacza założenie kwadratowego widoku. 1.33 jest odpowiednie dla widoku 4:3, takiego jak 1024x768. 1.78 jest odpowiednie dla widoku 16:9. To ustawienie jest ignorowane, jeśli jest ustawiony *Auto Aspect Ratio*. +: (**Tylko dla kamery perspektywicznej**) Stosunek szerokości bryły widoku do jej wysokości. 1.0 oznacza widok kwadratowy. 1.33 dobrze pasuje do widoku 4:3, takiego jak 1024x768. 1.78 dobrze pasuje do widoku 16:9. To ustawienie jest ignorowane, jeśli włączone jest *Auto Aspect Ratio*. Fov -: (**Tylko dla kamery perspektywicznej**) Pionowe pole widzenia kamery wyrażone w radianach. Im szersze pole widzenia, tym więcej zobaczy kamera. +: (**Tylko dla kamery perspektywicznej**) *Pionowe* pole widzenia kamery wyrażone w radianach. Im szersze pole widzenia, tym większy obszar zobaczy kamera. Near Z -: wartość Z bliskiej płaszczyzny odcięcia (ang. clipping plane). +: Wartość Z bliskiej płaszczyzny odcięcia. Far Z : Wartość Z dalekiej płaszczyzny odcięcia. Auto Aspect Ratio -: (**Tylko dla kamery perspektywicznej**) - Automatyczny współczynnik proporcji - ustaw tę opcję, aby kamera automatycznie obliczała współczynnik proporcji. +: (**Tylko dla kamery perspektywicznej**) Włącz tę opcję, aby kamera automatycznie obliczała współczynnik proporcji. Orthographic Projection -: Projekcja ortograficzna - ustaw tę opcję, aby przełączyć kamerę na projekcję ortograficzną (patrz niżej). +: Włącz tę opcję, aby przełączyć kamerę na projekcję ortograficzną. Orthographic Zoom -: (**Tylko dla kamery ortograficznej**) - Powiększenie używane dla rzutu ortograficznego (> 1 = przybliż, < 1 = oddal). +: (**Tylko dla kamery ortograficznej**) Powiększenie używane w projekcji ortograficznej (> 1 = przybliżenie, < 1 = oddalenie). + +Orthographic Mode +: (**Tylko dla kamery ortograficznej**) Określa, jak kamera ortograficzna wyznacza zoom względem rozmiaru okna i rozdzielczości projektowej, czyli wartości `game.project` → `display.width/height`. + - `Fixed` (stały zoom): używa bieżącej wartości `Orthographic Zoom` bez zmian. + - `Auto Fit` (contain): automatycznie dopasowuje zoom tak, aby cały obszar projektowy mieścił się w oknie. Może pokazać dodatkową zawartość po bokach albo u góry i na dole. + - `Auto Cover` (cover): automatycznie dopasowuje zoom tak, aby obszar projektowy wypełniał całe okno. Może przycinać zawartość po bokach albo u góry i na dole. + Ta opcja jest dostępna tylko wtedy, gdy włączone jest `Orthographic Projection`. ## Używanie kamery -Aby aktywować kamerę i przekazać jej macierze widoku i projekcji do skryptu renderującego, wyślij komponentowi wiadomość `acquire_camera_focus`: +Wszystkie kamery są automatycznie włączane i aktualizowane w każdej klatce, a moduł Lua `camera` jest dostępny we wszystkich kontekstach skryptowych. Od Defold 1.8.1 nie trzeba już jawnie włączać kamery przez wysłanie do komponentu wiadomości `acquire_camera_focus`. Stare wiadomości acquire i release nadal istnieją, ale zaleca się używanie wiadomości enable i disable, tak samo jak w przypadku innych komponentów, które chcesz włączać i wyłączać: + +```lua +msg.post("#camera", "disable") +msg.post("#camera", "enable") +``` + +Aby wyświetlić listę wszystkich obecnie dostępnych kamer, możesz użyć camera.get_cameras(): + +```lua +-- Uwaga: wywołania render są dostępne tylko w skrypcie renderującym. +-- Funkcji camera.get_cameras() można używać wszędzie, +-- ale render.set_camera tylko w skrypcie renderującym. + +for k,v in pairs(camera.get_cameras()) do + -- tabela kamer zawiera URL-e wszystkich kamer + render.set_camera(v) + -- tutaj wykonaj renderowanie; wszystko, co zostanie tu narysowane + -- z użyciem materiałów korzystających z macierzy widoku i projekcji, + -- będzie używać macierzy z tej kamery. +end +-- aby wyłączyć kamerę, przekaż nil (albo nie podawaj argumentów) do render.set_camera. +-- po tym wywołaniu wszystkie operacje renderowania będą używać macierzy widoku i projekcji +-- ustawionych bezpośrednio w kontekście renderowania (render.set_view i render.set_projection) +render.set_camera() +``` + +Moduł skryptowy `camera` udostępnia wiele funkcji do manipulowania kamerą. Poniżej kilka przykładów; pełną listę znajdziesz w [dokumentacji API](/ref/camera/). + +```lua +camera.get_aspect_ratio(camera) -- pobierz współczynnik proporcji +camera.get_far_z(camera) -- pobierz far z +camera.get_fov(camera) -- pobierz pole widzenia +camera.get_orthographic_mode(camera) -- pobierz tryb ortograficzny (jedna z wartości camera.ORTHO_MODE_*) +camera.set_aspect_ratio(camera, ratio) -- ustaw współczynnik proporcji +camera.set_far_z(camera, far_z) -- ustaw far z +camera.set_near_z(camera, near_z) -- ustaw near z +camera.set_orthographic_mode(camera, camera.ORTHO_MODE_AUTO_FIT) -- ustaw tryb ortograficzny +... I tak dalej +``` + +Kamera jest identyfikowana przez URL, czyli pełną ścieżkę komponentu w scenie, obejmującą kolekcję, obiekt gry, do którego należy, oraz id komponentu. W tym przykładzie do identyfikacji komponentu kamery z tej samej kolekcji użyjesz URL `/go#camera`, a przy dostępie do kamery z innej kolekcji albo ze skryptu renderującego użyjesz `main:/go#camera`. + +![create camera component](images/camera/create.png) ```lua -msg.post("#camera", "acquire_camera_focus") +-- Dostęp do kamery ze skryptu w tej samej kolekcji: +camera.get_fov("/go#camera") + +-- Dostęp do kamery ze skryptu w innej kolekcji: +camera.get_fov("main:/go#camera") + +-- Dostęp do kamery ze skryptu renderującego: +render.set_camera("main:/go#camera") ``` -Co klatkę, komponent kamery, który obecnie ma fokus kamery, wyśle wiadomość `set_view_projection` do gniazda `"@render"`, czyli dotrze to do twojego skryptu renderującego: +W każdej klatce komponent kamery, który ma aktualnie fokus kamery, wysyła wiadomość `set_view_projection` do gniazda "@render": ```lua -- builtins/render/default.render_script @@ -69,99 +126,187 @@ function on_message(self, message_id, message) end end ``` +1. Wiadomość wysyłana z komponentu kamery zawiera macierz widoku i macierz projekcji. -1. Wiadomość wysłana z komponentu kamery zawiera macierz widoku (view matrix) i macierz projekcji (projection matrix). +Komponent Camera dostarcza skryptowi renderującemu macierz projekcji perspektywicznej albo ortograficznej, zależnie od właściwości *Orthographic Projection*. Macierz projekcji uwzględnia też ustawione bliską i daleką płaszczyznę odcięcia, pole widzenia oraz współczynnik proporcji kamery. -Komponent kamery dostarcza skryptowi renderującemu macierz projekcji albo perspektywiczną, albo ortograficzną, w zależności od właściwości *Orthographic Projection* kamery. Macierz projekcji uwzględnia również określone płaszczyzny odcięcia bliskie i dalekie (near Z, far Z), pole widzenia (FOV) oraz ustawienia współczynnika proporcji kamery. +Macierz widoku dostarczana przez kamerę definiuje położenie i orientację kamery. Kamera z włączonym *Orthographic Projection* centruje widok na pozycji obiektu gry, do którego jest podłączona, natomiast kamera z *Perspective Projection* będzie miała lewy dolny róg widoku ustawiony w pozycji obiektu gry, do którego jest podłączona. -Macierz widoku dostarczana przez kamerę określa położenie i orientację kamery. Kamera z Projekcją Ortograficzną (*Orthographic Projection*) będzie miała widok wycentrowany na pozycji obiektu gry, do którego jest podłączona, podczas gdy kamera z Projekcją Perspektywiczną (*Perspective Projection*) będzie miała lewy dolny róg widoku na obiekcie gry, do którego jest podłączona. -::: important -Dla zachowania kompatybilności wstecznej domyślny skrypt renderujący ignoruje projekcję dostarczoną przez kamerę i zawsze używa rzutu ortograficznego. Dowiedz się więcej o skrypcie renderującym oraz macierzach widoku i projekcji w [instrukcji do renderowania](/manuals/render/#default-view-projection). -::: +### Skrypt do renderowania + +Podczas używania domyślnego skryptu do renderowania Defold automatycznie ustawia ostatnią włączoną kamerę, która ma być używana do renderowania. Wcześniej skrypt w projekcie musiał jawnie wysyłać do renderera wiadomość `use_camera_projection`, aby poinformować go, że ma korzystać z widoku i projekcji z komponentów kamery. Nie jest to już konieczne, ale nadal można tak robić dla zachowania zgodności wstecznej. + +Alternatywnie możesz ustawić w skrypcie do renderowania konkretną kamerę, której należy użyć do renderowania. Przydaje się to wtedy, gdy chcesz dokładniej kontrolować, która kamera jest używana, na przykład w grze wieloosobowej. + +```lua +-- render.set_camera będzie automatycznie używać macierzy widoku i projekcji +-- przy każdym renderowaniu aż do wywołania render.set_camera(). +render.set_camera("main:/my_go#camera") +``` -Możesz powiedzieć skryptowi renderującemu, aby używał projekcji dostarczonej przez kamerę, wysyłając wiadomość do skryptu renderującego. +Aby sprawdzić, czy kamera jest aktywna, możesz użyć funkcji `get_enabled` z [Camera API](https://defold.com/ref/alpha/camera/#camera.get_enabled:camera): ```lua -msg.post("@render:", "use_camera_projection") +if camera.get_enabled("main:/my_go#camera") then + -- kamera jest włączona, użyj jej do renderowania! + render.set_camera("main:/my_go#camera") +end ``` +::: sidenote +Aby używać funkcji `set_camera` razem z odrzucaniem poza bryłą widoku (frustum culling), musisz przekazać do niej taką opcję: +`render.set_camera("main:/my_go#camera", {use_frustum = true})` +::: + ### Poruszanie kamerą -Aby przesuwać kamerę po obszarze gry, należy przesuwać obiekt gry, do którego jest przypisany komponent kamery. Komponent kamery automatycznie będzie wysyłał zaktualizowaną macierz widoku na podstawie bieżącej pozycji kamery wzdłuż osi X i Y. +Kamerę przesuwa się po świecie gry przez przesuwanie obiektu gry, do którego przypisany jest komponent Camera. Komponent automatycznie wyśle zaktualizowaną macierz widoku na podstawie bieżącej pozycji kamery na osiach X i Y. ### Zoomowanie kamery -Możesz przybliżać i oddalać, używając kamery perspektywicznej, przesuwając obiekt gry, do którego jest przypisana kamera, wzdłuż osi Z. Komponent kamery automatycznie będzie wysyłał zaktualizowaną macierz widoku na podstawie bieżącej pozycji kamery wzdłuż osi Z. +Przy użyciu kamery perspektywicznej możesz przybliżać i oddalać widok, przesuwając obiekt gry, do którego przypisana jest kamera, wzdłuż osi Z. Komponent Camera automatycznie wyśle zaktualizowaną macierz widoku na podstawie bieżącej pozycji kamery na osi Z. -Możesz również przybliżać i oddalać, używając kamery ortograficznej, poprzez zmianę właściwości *Orthographic Zoom* kamery: +W przypadku kamery ortograficznej możesz przybliżać i oddalać widok przez zmianę właściwości *Orthographic Zoom*: ```lua go.set("#camera", "orthographic_zoom", 2) ``` -### Śledzenie obiektu gry +Przy użyciu kamery ortograficznej możesz też przełączać sposób wyznaczania zoomu za pomocą ustawienia `Orthographic Mode` albo z poziomu skryptu: -Kamerę można ustawić tak, aby śledziła obiekt gry, ustawiając obiekt gry, do którego przypisany jest komponent kamery, jako potomka obiektu gry, który ma być śledzony: +```lua +-- pobierz bieżący tryb (jedna z wartości camera.ORTHO_MODE_FIXED, _AUTO_FIT, _AUTO_COVER) +local mode = camera.get_orthographic_mode("#camera") -![Śledzenie obiektu gry](images/camera/follow.png) +-- przełącz na auto-fit (contain), aby cały obszar projektowy zawsze pozostawał widoczny +camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_AUTO_FIT) -Alternatywnym sposobem jest aktualizacja pozycji obiektu gry, do którego przypisany jest komponent kamery, co klatkę, w miarę jak obiekt gry do śledzenia się przemieszcza. +-- przełącz na auto-cover, aby obszar projektowy zawsze wypełniał okno +camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_AUTO_COVER) -### Konwersja współrzędnych ekranu na współrzędne świata +-- wróć do trybu fixed, aby ręcznie sterować zoomem przez orthographic_zoom +camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_FIXED) +``` -Gdy kamera jest przesunięta, przybliżona lub zmieniła projekcję względem domyślnego rozciągniętego rzutu ortograficznego, współrzędne myszy na ekranie dostarczone w funkcji cyklu życia `on_input()` nie będą już odpowiadać współrzędnym świata twoich obiektów gry. Musisz ręcznie uwzględnić zmianę widoku lub projekcji. Konwersja z współrzędnych myszy/ekranu na współrzędne świata z domyślnego skryptu renderującego wygląda tak: +### Adaptacyjny zoom + +Idea adaptacyjnego zoomu polega na dostosowywaniu wartości zoomu kamery, gdy rozdzielczość wyświetlacza zmienia się względem początkowej rozdzielczości ustawionej w *game.project*. + +Dwa częste podejścia do adaptacyjnego zoomu to: + +1. Maksymalny zoom: oblicz taką wartość zoomu, aby obszar zawartości odpowiadający początkowej rozdzielczości z *game.project* wypełniał ekran i wykraczał poza jego krawędzie, co może ukryć część zawartości po bokach albo u góry i na dole. +2. Minimalny zoom: oblicz taką wartość zoomu, aby obszar zawartości odpowiadający początkowej rozdzielczości z *game.project* w całości mieścił się w granicach ekranu, co może pokazać dodatkową zawartość po bokach albo u góry i na dole. + +Przykład: + +```lua +local DISPLAY_WIDTH = sys.get_config_int("display.width") +local DISPLAY_HEIGHT = sys.get_config_int("display.height") + +function init(self) + local initial_zoom = go.get("#camera", "orthographic_zoom") + local display_scale = window.get_display_scale() + window.set_listener(function(self, event, data) + if event == window.WINDOW_EVENT_RESIZED then + local window_width = data.width + local window_height = data.height + local design_width = DISPLAY_WIDTH / initial_zoom + local design_height = DISPLAY_HEIGHT / initial_zoom + + -- maksymalny zoom: upewnij się, że początkowe wymiary projektu + -- wypełnią ekran i wyjdą poza jego granice + local zoom = math.max(window_width / design_width, window_height / design_height) / display_scale + + -- minimalny zoom: upewnij się, że początkowe wymiary projektu + -- zmieszczą się w granicach ekranu + --local zoom = math.min(window_width / design_width, window_height / design_height) / display_scale + + go.set("#camera", "orthographic_zoom", zoom) + end + end) +end +``` + +Pełny przykład adaptacyjnego zoomu znajdziesz w [tym projekcie przykładowym](https://github.com/defold/sample-adaptive-zoom). + +Uwaga: przy użyciu kamery ortograficznej możesz teraz uzyskać zachowanie contain/cover bez własnego kodu, ustawiając `Orthographic Mode` na `Auto Fit` (contain) albo `Auto Cover` (cover). W tych trybach efektywny zoom jest obliczany automatycznie na podstawie rozmiaru okna i rozdzielczości projektowej. -::: sidenote -[Rozwiązania dla kamer od społeczności](/manuals/camera/#rozwiązania-dla-kamer-od-społeczności) wymienione w tym podręczniku oferują funkcje do konwersji między współrzędnymi ekranu a świata. -::: + +### Śledzenie obiektu gry + +Możesz sprawić, aby kamera śledziła obiekt gry, ustawiając obiekt gry, do którego przypisany jest komponent Camera, jako dziecko śledzonego obiektu: + +![follow game object](images/camera/follow.png) + +Innym sposobem jest aktualizowanie co klatkę pozycji obiektu gry, do którego przypisany jest komponent Camera, zgodnie z ruchem śledzonego obiektu. + +### Konwersja współrzędnych myszy na współrzędne świata + +Gdy kamera została przesunięta, przybliżona lub korzysta z innej projekcji niż domyślna rozciągnięta projekcja ortograficzna, współrzędne myszy dostarczane do funkcji cyklu życia `on_input()` przestają odpowiadać współrzędnym świata obiektów gry. Trzeba wtedy ręcznie uwzględnić zmianę widoku albo projekcji. Kod konwertujący współrzędne myszy i ekranu na współrzędne świata wygląda tak: ```Lua --- builtins/render/default.render_script --- -local function screen_to_world(x, y, z) - local inv = vmath.inv(self.projection * self.view) - x = (2 * x / render.get_width()) - 1 - y = (2 * y / render.get_height()) - 1 - z = (2 * z) - 1 - local x1 = x * inv.m00 + y * inv.m01 + z * inv.m02 + inv.m03 - local y1 = x * inv.m10 + y * inv.m11 + z * inv.m12 + inv.m13 - local z1 = x * inv.m20 + y * inv.m21 + z * inv.m22 + inv.m23 - return x1, y1, z1 +--- Konwertuje współrzędne ekranu na współrzędne świata, +-- biorąc pod uwagę widok i projekcję konkretnej kamery +-- @param camera URL kamery używanej do konwersji +-- @param screen_x Współrzędna x na ekranie do przeliczenia +-- @param screen_y Współrzędna y na ekranie do przeliczenia +-- @param z opcjonalna współrzędna z przekazywana przez konwersję, domyślnie 0 +-- @return world_x Wynikowa współrzędna x w świecie +-- @return world_y Wynikowa współrzędna y w świecie +-- @return world_z Wynikowa współrzędna z w świecie +function M.screen_to_world(camera, screen_x, screen_y, z) + local projection = go.get(camera, "projection") + local view = go.get(camera, "view") + local w, h = window.get_size() + + -- https://defold.com/manuals/camera/#converting-mouse-to-world-coordinates + local inv = vmath.inv(projection * view) + local x = (2 * screen_x / w) - 1 + local y = (2 * screen_y / h) - 1 + local x1 = x * inv.m00 + y * inv.m01 + z * inv.m02 + inv.m03 + local y1 = x * inv.m10 + y * inv.m11 + z * inv.m12 + inv.m13 + return x1, y1, z or 0 end ``` -## Manipulacja w czasie rzeczywistym +Pamiętaj, że jako argumentów tej funkcji należy używać wartości `action.screen_x` i `action.screen_y` z `on_input()`. Zobacz [stronę Examples](https://defold.com/examples/render/screen_to_world/), aby sprawdzić konwersję współrzędnych ekranu na współrzędne świata w praktyce. Dostępny jest też [projekt przykładowy](https://github.com/defold/sample-screen-to-world-coordinates/) pokazujący, jak wykonać taką konwersję. + +::: sidenote +[Rozwiązania kamer od społeczności wymienione w tym podręczniku](/manuals/camera/#third-party-camera-solutions) zawierają funkcje konwersji do współrzędnych ekranu i z powrotem. +::: + +## Manipulacja w czasie działania -Kamery można manipulować w czasie rzeczywistym za pomocą różnych wiadomości i właściwości ([patrz w dokumentacji API](/ref/camera/)).). +Kamerami można manipulować w czasie działania za pomocą różnych wiadomości i właściwości. Sposób użycia znajdziesz w [dokumentacji API](/ref/camera/). -Kamera ma wiele różnych właściwości (properties), które można manipulować za pomocą `go.get()` i `go.set()`: +Kamera ma kilka właściwości, którymi można sterować przy użyciu `go.get()` i `go.set()`: `fov` -: Pole widzenia kamery (typ `number`). +: Pole widzenia kamery (`number`). `near_z` -: Bliska wartość Z kamery (typ `number`). +: Bliska wartość Z kamery (`number`). `far_z` -: Daleka wartość Z kamery (typ `number`). +: Daleka wartość Z kamery (`number`). `orthographic_zoom` -: Zoom kamery ortograficznej (typ `number`). +: Zoom kamery ortograficznej (`number`). `aspect_ratio` -: Dodane w Defold 1.4.8. Stosunek szerokości bryły widokowej do jej wysokości. Używane do obliczania projekcji kamery perspektywicznej (typ `number`). +: Stosunek szerokości bryły widoku do jej wysokości. Używany przy obliczaniu projekcji kamery perspektywicznej (`number`). `view` -: Dodane w Defold 1.4.8. Obliczona macierz widoku kamery. TYLKO DO ODCZYTU. (typ `matrix4`). +: Obliczona macierz widoku kamery. Tylko do odczytu (`matrix4`). `projection` -: Dodane w Defold 1.4.8. Obliczona macierz projekcji kamery. TYLKO DO ODCZYTU. (typ `matrix4`). +: Obliczona macierz projekcji kamery. Tylko do odczytu (`matrix4`). -## Rozwiązania dla kamer od społeczności +## Rozwiązania kamer od społeczności -Istnieje biblioteka wspomagająca kamery, która implementuje wspólne funkcje, takie jak śledzenie obiektu gry, trzęsienie ekranu, konwersja współrzędnych ekranu na współrzędne świata i inne. Jest dostępna na portalu zasobów społeczności Defold (Assets portal): +Społeczność stworzyła rozwiązania kamerowe implementujące typowe funkcje, takie jak trzęsienie ekranu, śledzenie obiektów gry, konwersję współrzędnych ekranu na współrzędne świata i wiele innych. Można je pobrać z portalu zasobów Defold: -- [Orthographic camera](https://defold.com/assets/orthographic/) (2D only) by Björn Ritzl. -- [Defold Rendy](https://defold.com/assets/defold-rendy/) (2D and 3D) by Klayton Kowalski. +- [Orthographic camera](https://defold.com/assets/orthographic/) (tylko 2D) autorstwa Björna Ritzla. +- [Defold Rendy](https://defold.com/assets/defold-rendy/) (2D i 3D) autorstwa Klaytona Kowalskiego. diff --git a/docs/pl/manuals/collection-factory.md b/docs/pl/manuals/collection-factory.md index 259443cd..c3935794 100644 --- a/docs/pl/manuals/collection-factory.md +++ b/docs/pl/manuals/collection-factory.md @@ -1,57 +1,57 @@ --- -title: Instrukcja do Fabryk kolekcji -brief: Instrukcja ta wyjaśnia jak używać Fabryk kolekcji, żeby tworzyć hierarchię obiektów gry. +title: Fabryki kolekcji +brief: Ta instrukcja wyjaśnia, jak używać komponentów fabryki kolekcji do tworzenia hierarchii obiektów gry. --- -# Fabryka kolekcji (Collection factory) +# Fabryki kolekcji -Fabryki kolekcji to komponenty używane do tworzenia grup i hierarchi obiektów gry przechowywanych w pliku danej kolekcji w trakcie działania programu. +Komponent fabryki kolekcji służy do tworzenia grup i hierarchii obiektów gry zapisanych w plikach kolekcji w działającej grze. -Kolekcje są potężnym narzędziem do tworzenia szablonów, które można utylizować wielokrotnie (podobnie jak prefaby). Więcej szczegółów na temat kolekcji znajdziesz w [dokumentacji podstawowych elementów Defold](/manuals/building-blocks#collections). Kolekcje mogą być umieszczane bezpośrednio w Edytorze lub tworzone dynamicznie. +Kolekcje są w Defold wygodnym mechanizmem tworzenia szablonów wielokrotnego użytku, czyli odpowiednika prefabów. Przegląd kolekcji znajdziesz w [dokumentacji o blokach składowych](/manuals/building-blocks#collections). Kolekcje można umieszczać w edytorze albo dynamicznie wstawiać do gry. -Używając fabryki kolekcji możesz tworzyć w świecie gry zawartość pliku kolekcji. Jest to uproszczonie analogicznego procesu tworzenia wszystkich obiektów gry opisanych w danym pliku kolekcji i przypisywanie im relacji rodzic-dziecko również opisanych w takim pliku. Typowym przykładem jest tworzenie postaci wrogów składających się z wielu różnych obiektów (np. jedno z wariantów ciał + jedna z broni). +Za pomocą komponentu fabryki kolekcji możesz tworzyć w świecie gry zawartość pliku kolekcji. To odpowiednik utworzenia przez fabrykę wszystkich obiektów gry zapisanych w kolekcji, a następnie odtworzenia relacji rodzic-dziecko pomiędzy nimi. Typowym zastosowaniem jest tworzenie przeciwników złożonych z wielu obiektów gry, na przykład wroga i jego broni. ## Tworzenie kolekcji -Załóżmy, że chcesz, żeby obiekt reprezentujący Twojego bohatera miał również obiekt-dziecko reprezentujący tarczę. Zbudujemy taką hierarchię w pliku kolekcji i zapiszemy jako "bean.collection". +Załóżmy, że chcemy mieć obiekt gry postaci oraz osobny obiekt gry tarczy będący dzieckiem tej postaci. Budujemy taką hierarchię w pliku kolekcji i zapisujemy ją jako "bean.collection". ::: sidenote -Komponent typu pełnomocnik kolekcji (*collection proxy*) różni się od fabryki i jest używany do stworzenia nowego świata gry, a co za tym idzie również osobnego świata fizyki z obiektami bazującymi na hierarchi w pliku danej kolekcji. Nowy świat ma swoje nowe gniazdo (socket), więc i nową przestrzeń adresową. Wszystkie zasoby z danej kolekcji są wczytywane przez pełnomocnika, kiedy wyślesz do niego wiadomość o rozpoczęciu wczytywania. Jest więc to przydatne przykładowo przy tworzeniu nowych poziomów w grze. Nowy świat gry wiąże się jednak z zajęciem sporej ilości nowych zasobów w pamięci, więc lepiej nie używać ich do dynamicznego wczytywania. Więcej szczegółów znajdziesz w [dokumentacji pełnomocników kolekcji](/manuals/collection-proxy). +Komponent *Collection proxy* (pełnomocnik kolekcji) służy do tworzenia nowego świata gry, w tym osobnego świata fizyki, na podstawie kolekcji. Nowy świat jest dostępny przez nowe gniazdo. Wszystkie zasoby zawarte w kolekcji są ładowane przez pełnomocnika po wysłaniu do niego wiadomości rozpoczynającej ładowanie. To bardzo przydatne na przykład przy zmianie poziomów w grze. Nowe światy gry mają jednak spory narzut, więc nie należy ich używać do dynamicznego ładowania niewielkich rzeczy. Więcej informacji znajdziesz w [dokumentacji Collection proxy](/manuals/collection-proxy). ::: ![Collection to spawn](images/collection_factory/collection.png) -Dodajemy następnie komponent typu *Collection factory* (Fabryka kolekcji) do obiektu gry, który będzie odpowiedzialny za stworzenie obiektów i hierarchi z pliku kolekcji "bean.collection" podanego jako właściwość *Prototype*: +Następnie dodajemy komponent *Collection factory* do obiektu gry, który ma odpowiadać za tworzenie instancji, i ustawiamy "bean.collection" jako właściwość *Prototype* komponentu: ![Collection factory](images/collection_factory/factory.png) -Tworzenie bohatera i tarczy jest teraz tylko kwestią wywołania funckji `collectionfactory.create()`: +Utworzenie postaci i tarczy sprowadza się teraz do wywołania `collectionfactory.create()`: ```lua local bean_ids = collectionfactory.create("#bean_factory") ``` -Funkcja przyjmuje 5 parameterów: +Funkcja przyjmuje 5 parametrów: `url` -: Identyfikator fabryki kolekcji, która ma być użyta do tworzenia nowego zestawu obiektów. +: Id komponentu fabryki kolekcji, który ma utworzyć nowy zestaw obiektów gry. `[position]` -: (opcjonalnie) Pozycja w świecie (bezwzględna) nowych obiektów. Typu `vector3`. Jeśli nie określisz pozycji, obiekty będą tworzone w miejscu komponentu fabryki kolekcji. +: Opcjonalna pozycja tworzonych obiektów gry w przestrzeni świata. Powinna mieć typ `vector3`. Jeśli jej nie podasz, obiekty zostaną utworzone w pozycji komponentu fabryki kolekcji. `[rotation]` -: (opcjonalnie) Orientacja w świecie (bezwzględna) nowych obiektów. Typu `quat`. Jeśli nie określisz orientacji, obiekty będą tworzone z orientacją komponentu fabryki kolekcji. +: Opcjonalny obrót tworzonych obiektów gry w przestrzeni świata. Powinien mieć typ `quat`. `[properties]` -: (opcjonalnie) Właściwości - tabela Lua o strukturze par `id`-`table` używana przy tworzeniu obiektów gry. Poniżej opisano jak skonstruować taką tabelę. +: Opcjonalna tabela Lua zawierająca pary `id`-`table`, używana do inicjalizowania tworzonych obiektów gry. Poniżej opisano, jak ją zbudować. `[scale]` -: (opcjonalnie) Skala tworzonych obiektów, określona jako liczba (`number`) (większa od 0), która określa jednolitą skalę wzdłuż wszystkich osi. Możesz też podać wektor (`vector3`), gdzie każdy komponent będzie odpowiadał skali wzdłuż danej osi. +: Opcjonalna skala tworzonych obiektów gry. Może być podana jako `number` większy od 0, co oznacza jednolite skalowanie we wszystkich osiach. Możesz też przekazać `vector3`, gdzie każdy komponent określa skalę na odpowiedniej osi. -Funkcja `collectionfactory.create()` zwraca tabelę z identyfikatorami utworzonych obiektów gry. Klucze tabeli mapują hashe kolekcji do lokalnych identyfikatorów każdego z obiektów: +`collectionfactory.create()` zwraca tabelę z identyfikatorami utworzonych obiektów gry. Klucze tabeli mapują hash lokalnego id obiektu w kolekcji na id w czasie działania danego obiektu: ::: sidenote -Relacja rodzic-dziecko między "bean" a "shield" *NIE* jest odzwierciedlona w zwracanej tabeli. Ta relacja istnieje jedynie w grafie sceny w trakcie działania programu, co określa jak obiekty są ustawione w stosunku do siebie. Przypisywanie rodzica nigdy nie zmienia identyfikatora obiektu. +Relacja rodzic-dziecko między "bean" i "shield" *nie* jest odzwierciedlona w zwracanej tabeli. Ta relacja istnieje tylko w runtime scene-graph, czyli w sposobie, w jaki obiekty są razem transformowane. Zmiana rodzica nigdy nie zmienia id obiektu. ::: ```lua @@ -64,12 +64,11 @@ pprint(bean_ids) -- hash: [/bean] = hash: [/collection0/bean], -- } ``` - -1. Prefix `/collection[N]/`, gdzie `[N]` jest licznikiem dodanym do ID, żeby zidentyfikować obiekt w sposób unikalny dla każdej instancji: +1. Do id dodawany jest prefiks `/collection[N]/`, gdzie `[N]` to licznik, aby każdą instancję jednoznacznie rozróżnić. ## Właściwości -Podczas tworzenia kolekcji, możesz przekazać właściwości do każdego obiektu gry konstruując tabelę, gdzie klucze odpowiadają identyfikatorom obiektów, a wartości są tabelami z właściwościami (scrip properties) dla danych obiektów. +Podczas tworzenia kolekcji możesz przekazać właściwości do poszczególnych obiektów gry, budując tabelę, w której kluczami są id obiektów, a wartościami tabele z właściwościami skryptu do ustawienia. ```lua local props = {} @@ -77,76 +76,95 @@ props[hash("/bean")] = { shield = false } local ids = collectionfactory.create("#bean_factory", nil, nil, props) ``` -Załóżmy, że obiekt "bean" w kolekcji "bean.collection" ma właściwość "shield". [Instrukcja do właściwości skryptów](/manuals/script-properties) zawiera więcej szczegółów na ten temat. +Załóżmy, że obiekt gry "bean" w "bean.collection" definiuje właściwość "shield". [Instrukcja o właściwościach skryptu](/manuals/script-properties) zawiera więcej informacji o takich właściwościach. ```lua --- bean/controller.script +-- plik bean/controller.script go.property("shield", true) function init(self) if not self.shield then go.delete("shield") - end + end end ``` -## Wczytywanie dynamiczne zasobów +## Dynamiczne ładowanie zasobów fabryki -Zaznaczając właściwość *Load Dynamically* fabryki kolekcji, silnik odłoży wczytywanie zasobów danej kolekcji aż do momentu rozpoczęcia tworzenia. +Po zaznaczeniu pola *Load Dynamically* we właściwościach komponentu fabryki kolekcji silnik opóźni ładowanie zasobów powiązanych z fabryką. ![Load dynamically](images/collection_factory/load_dynamically.png) -Z odznaczoną opcją, silnik wczyta prototypy zasobów kolekcji w momencie wczytywania komponentu fabryki kolekcji, więc będzie można je utworzyć w świecie gry natychmiastowo. +Gdy pole nie jest zaznaczone, silnik ładuje zasoby prototypu podczas ładowania komponentu fabryki kolekcji, dzięki czemu są one od razu gotowe do tworzenia instancji. -Z zaznaczoną opcją, możesz użyć fabryki na dwa sposoby: +Gdy pole jest zaznaczone, masz dwa sposoby użycia: -Wczytywanie synchroniczne: -: Wywołaj [`collectionfactory.create()`](/ref/collectionfactory/#collectionfactory.create:url-[position]-[rotation]-[properties]-[scale]) kiedy chcesz utworzyć obiekty kolekcji. Funkcja wczyta wszystkie zasoby potrzebe do utworzenia obiektów synchronicznie (co może spowodować zwieszenie programu w zależności od wielkości zasobów), a następnie utworzy obiekty z danymi zasobami. +Wczytywanie synchroniczne +: Wywołaj [`collectionfactory.create()`](/ref/collectionfactory/#collectionfactory.create:url-[position]-[rotation]-[properties]-[scale]) wtedy, gdy chcesz tworzyć obiekty. Spowoduje to synchroniczne załadowanie zasobów, co może wywołać chwilowe przycięcie, a następnie utworzenie nowych instancji. ```lua function init(self) - -- Żadne zasoby fabryki nie są załadowane kiedy kolekcja rodzic - -- zawierająca daną fabrykę kolekcji jest utworzona. - -- Wywołanie create spowoduje wczytanie zasobów synchronicznie. - self.go_ids = collecionfactory.create("#collectionfactory") + -- Zasoby fabryki nie są ładowane, gdy ładowana jest kolekcja + -- nadrzędna komponentu fabryki kolekcji. Wywołanie create + -- bez wcześniejszego load wczyta zasoby synchronicznie. + self.go_ids = collectionfactory.create("#collectionfactory") end - function final(self) - -- Usuwanie obiektów gry. Zwolni to zasoby. - -- W tym przypadku obiekty są usuwane, ponieważ - -- fabryka kolekcji nie ma żadnych referencji. + function final(self) + -- Usuń obiekty gry. To zmniejszy licznik referencji zasobów. + -- W tym przypadku zasoby zostaną usunięte, ponieważ komponent + -- fabryki kolekcji nie trzyma już do nich referencji. go.delete(self.go_ids) - -- Wywołanie unload nie zrobi nic, ponieważ - -- fabryka kolekcji nie ma żadnych referencji. + -- Wywołanie unload nic nie zrobi, ponieważ fabryka + -- nie ma żadnych referencji. collectionfactory.unload("#factory") end ``` -Wczytywanie asynchroniczne: -: Wywołaj [`collectionfactory.load()`](/ref/collectionfactory/#collectionfactory.load:[url]-[complete_function]), żeby jawnie załadować zasoby asynchronicznie. Kiedy zasoby będą gotowe, skrypt, w którym wywołano load() otrzyma callback. +Wczytywanie asynchroniczne +: Wywołaj [`collectionfactory.load()`](/ref/collectionfactory/#collectionfactory.load:[url]-[complete_function]), aby jawnie załadować zasoby asynchronicznie. Gdy zasoby będą gotowe do tworzenia obiektów, otrzymasz funkcję zwrotną. ```lua - --callback, który zostanie wywołany po wczytaniu zasobów: function load_complete(self, url, result) - -- Wczytywanie zakończone, zasoby są gotowe do utworzenia + -- Ładowanie zakończone, zasoby są gotowe do tworzenia instancji. self.go_ids = collectionfactory.create(url) end function init(self) - -- Żadne zasoby nie są wczytywane przy utworzeniu kolekcji - -- która jest rodzicem komponentu fabryki kolekcji. - -- Zasoby są wczytywane po wywołaniu load(): + -- Zasoby fabryki nie są ładowane, gdy ładowana jest kolekcja + -- nadrzędna komponentu fabryki kolekcji. Wywołanie load + -- spowoduje ich załadowanie. collectionfactory.load("#factory", load_complete) end function final(self) - -- Usuwanie obiektu gry. Zasoby są zwalniane. - -- W tym przypadku zasoby nie są usuwane, ponieważ - -- fabryka kolekcji nadal posiada do nich referencję. + -- Usuń obiekty gry. To zmniejszy licznik referencji zasobów. + -- W tym przypadku zasoby nie zostaną usunięte, ponieważ komponent + -- fabryki kolekcji nadal trzyma do nich referencję. go.delete(self.go_ids) - -- Wywołanie unload zwolni zasoby utrzymywane przez farbykę i usunie je + -- Wywołanie unload zmniejszy licznik referencji zasobów + -- trzymanych przez komponent fabryki, co doprowadzi do ich usunięcia. collectionfactory.unload("#factory") end ``` + + +## Dynamiczny prototyp + +Możesz zmienić to, jaki *Prototype* potrafi tworzyć komponent fabryki kolekcji, zaznaczając pole *Dynamic Prototype* we właściwościach komponentu. + +![Dynamic prototype](images/collection_factory/dynamic_prototype.png) + +Gdy opcja *Dynamic Prototype* jest włączona, komponent fabryki kolekcji może zmieniać prototyp za pomocą `collectionfactory.set_prototype()`. Przykład: + +```lua +collectionfactory.unload("#factory") -- zwolnij poprzednie zasoby +collectionfactory.set_prototype("#factory", "/main/levels/level1.collectionc") +local ids = collectionfactory.create("#factory") +``` + +::: important +Gdy opcja *Dynamic Prototype* jest włączona, liczba komponentów w kolekcji nie może zostać zoptymalizowana i kolekcja właściciela będzie używać domyślnych limitów komponentów z pliku *game.project*. +::: diff --git a/docs/pl/manuals/collection-proxy.md b/docs/pl/manuals/collection-proxy.md index ee09d513..2ed373db 100644 --- a/docs/pl/manuals/collection-proxy.md +++ b/docs/pl/manuals/collection-proxy.md @@ -1,54 +1,54 @@ --- -title: Instrukcja do Pełnomocników kolekcji -brief: Instrukcja ta wyjaśnia jak dynamicznie tworzyć nowe światy gry i przełączać się między nimi przy użyciu Pełnomocników kolekcji. +title: Instrukcja pełnomocnika kolekcji +brief: Ta instrukcja wyjaśnia, jak dynamicznie tworzyć nowe światy gry i przełączać się między nimi. --- -# Pełnomocnik kolekcji (Collection proxy) +# Pełnomocnik kolekcji -Pełnomocnik kolekcji to komponent używany do wczytywania i zwalniania nowy "Światów" gry dynamicznie bazując na zawartości pliku kolekcji. Mogą być użyte do przełączania się między światami, poziomami w grze, ekranami menu, wczytywaniem i zwalnianiem fabularnych "scen", mini-gier i wiele więcej. +Komponent Collection proxy służy do dynamicznego wczytywania i zwalniania nowych "światów" gry na podstawie zawartości pliku kolekcji. Można go użyć do przełączania między poziomami, ekranami GUI, wczytywania i zwalniania fabularnych "scen" w trakcie poziomu, wczytywania i zwalniania mini-gier i nie tylko. -Defold organizuje wszystkie obiekty gry w kolekcje. Kolekcja może zawierać obiekty gry i inne kolekcje (podkolekcje). Pełnomocnik kolekcji pozwala na rozdzielenie zawartości Twojej gry w oddzielne kolekcje i wczytywanie dynamiczne zasobów w skryptach. +Defold organizuje wszystkie obiekty gry w kolekcje. Kolekcja może zawierać obiekty gry i inne kolekcje, czyli podkolekcje. Pełnomocnik kolekcji pozwala rozdzielić zawartość gry na osobne kolekcje, a następnie dynamicznie zarządzać ich wczytywaniem i zwalnianiem ze skryptów. -Pełnomocnicy kolekcji różnią się od [fabryk kolekcji](/manuals/collection-factory/). Fabryki kolekcji tworzy instancje obiektów zawartych w kolekcji do obecnego świata gry. Pełnomocnicy kolekcji tworzą natomiast nowe, osobne światy gry w trakcie działania programu, więc są używane w innych przypadkach. +Pełnomocniki kolekcji różnią się od [fabryk kolekcji](/manuals/collection-factory/). Fabryka kolekcji tworzy instancje zawartości kolekcji w bieżącym świecie gry. Pełnomocniki kolekcji tworzą natomiast nowy świat gry w trakcie działania programu, więc mają inne zastosowania. -## Towrzenie komponentów typu Pełnomocnik kolekcji +## Tworzenie komponentu pełnomocnika kolekcji -1. Dodaj komponent typu Pełnomocnik kolekcji (Collection proxy) do obiektu gry klikając prawy przycisk myszki na obiekcie gry i wybierając Add Component ▸ Collection Proxy z menu kontekstowego. +1. Dodaj komponent Collection proxy do obiektu gry, klikając prawym przyciskiem myszy obiekt gry i wybierając Add Component ▸ Collection Proxy z menu kontekstowego. -2. Ustaw właściwość *Collection* do pliku kolekcji, którą chcesz przez danego pełnomocnika dynamicznie wczytywać w trakcie działania programu. Referencja do tego pliku jest statyczna, więc upewnij się, że wszystkie potrzebne w kolekcji zasoby będą znajdować się w ostatcznej wersji Twojej gry. +2. Ustaw właściwość *Collection* tak, aby wskazywała kolekcję, którą chcesz później dynamicznie wczytać w trakcie działania programu. Referencja jest statyczna i zapewnia, że cała zawartość wskazanej kolekcji trafi do końcowej wersji gry. ![add proxy component](images/collection-proxy/create_proxy.png) -(Możesz wyłączyć część zawartości Twojej gry ze zbudowanej aplikacji, a potem ściągnąć ją dynamicznie zaznaczając opcję *Exclude* i używając funkcjonalności [Live update](/manuals/live-update/).) +(Możesz wyłączyć tę zawartość z kompilacji i pobrać ją później kodem, zaznaczając *Exclude* i używając funkcji [Live update](/manuals/live-update/).) -## Bootstrap (kolekcja startowa) +## Bootstrap -Podczas startu aplikacji silnik Defold wczytuje i tworzy instancje wszystkich obiektów gry z głównej kolekcji (*bootstrap collection*). Następnie inicjalizuje i aktywuje te obiekty i ich komponenty. Można określić, która z kolekcji jest kolekcją startową w [ustawieniach projektu](/manuals/project-settings/#main-collection). Domyślnie i zgodnie z konwencją kolekcja ta nazwana jest "main.collection" (z ang. główna.kolekcja). +Gdy silnik Defold startuje, wczytuje i instancjonuje wszystkie obiekty gry z kolekcji startowej (*bootstrap collection*). Następnie inicjalizuje i aktywuje obiekty oraz ich komponenty. To, której kolekcji startowej ma użyć silnik, ustawia się w [ustawieniach projektu](/manuals/project-settings/#main-collection). Zgodnie z konwencją plik tej kolekcji zwykle nosi nazwę "main.collection". ![bootstrap](images/collection-proxy/bootstrap.png) -Dla obiektów gry i ich komponentów silnik Defold alokuje pamięć potrzebną do stworzenia całego "świata gry", w którym instancje obiektów z głównej kolekcji są tworzone. Tworzony jest również osobny świat fizyki do obsługi kolizji i symulacji fizyki. +Aby pomieścić obiekty gry i ich komponenty, silnik alokuje pamięć potrzebną dla całego "świata gry", do którego instancjonowana jest zawartość kolekcji startowej. Tworzony jest też oddzielny świat fizyki dla obiektów kolizji i symulacji fizyki. -Ponieważ komponenty typu skrypt muszą być w stanie adresować każdy obiekt w grze, nawet z innej kolekcji, każdy otrzymuje unikalne imię - takie jakie określisz we właściwości *Name* w pliku kolekcji: +Ponieważ komponenty skryptowe muszą mieć możliwość adresowania wszystkich obiektów w grze, także spoza świata startowego, każdej kolekcji nadaje się unikalną nazwę przez właściwość *Name* ustawianą w pliku kolekcji: ![bootstrap](images/collection-proxy/collection_id.png) -Jeśli kolekcja, która jest załadowana posiada komponenty typu Pełnomocnik kolekcji, kolekcje do których te komponenty się odnoszą *NIE* są wtedy wczytywane automatycznie. Musisz jawnie kontrolować wczytywanie zasobów tych kolekcji w kodzie. +Jeśli wczytana kolekcja zawiera komponenty pełnomocnika kolekcji, kolekcje, do których one się odnoszą, *nie* są wczytywane automatycznie. Musisz sterować wczytywaniem tych zasobów w skryptach. ## Wczytywanie kolekcji -Dynamiczne wczytywanie kolekcji przez Pełnomocnika kolekcji jest osiągane przez wysłanie wiadomości `"load"` do komponentu pełnomocnika ze skryptu: +Dynamiczne wczytywanie kolekcji przez pełnomocnika odbywa się przez wysłanie ze skryptu wiadomości `"load"` do komponentu pełnomocnika: ```lua --- Tell the proxy "myproxy" to start loading. +-- Poleć pełnomocnikowi "myproxy" rozpocząć wczytywanie. msg.post("#myproxy", "load") ``` ![load](images/collection-proxy/proxy_load.png) -Pełnomocnik kolekcji nakaże silnikowi zaalokować pamięć na nowy świat gry, jak i również świat fizyki. Następnie światy mogą być utworzone, a w nich instancje wszystkich obiektów danej kolekcji "mylevel.collection". +Pełnomocnik kolekcji nakaże silnikowi zaalokować miejsce na nowy świat i utworzyć osobny świat fizyki. Następnie instancjonowane są wszystkie obiekty gry z kolekcji `mylevel.collection`. -Nowy świat gry dostaje swoje imię określone we właściwości *Name* pliku wczytanej kolekcji, w tym przykładzie to "mylevel". Nazwa ta musi być unikalna. Domyślna nazwa nowo utworzonej kolekcji to "default" - warto więc ją zmienić od razu. Jeśli właściwość *Name* podana w pliku kolekcji jest już aktualnie używana w dowolnym innym załadowanym świecie, silnik Defold zasygnalizuje kolizę nazw: +Nowy świat otrzymuje nazwę z właściwości *Name* w pliku kolekcji. W tym przykładzie ustawiono ją na `mylevel`. Nazwa musi być unikalna. Jeśli wartość *Name* w pliku kolekcji jest już używana przez inny załadowany świat, silnik zgłosi błąd kolizji nazw: ```txt ERROR:GAMEOBJECT: The collection 'default' could not be created since there is already a socket with the same name. @@ -56,12 +56,12 @@ WARNING:RESOURCE: Unable to create resource: build/default/mylevel.collectionc ERROR:GAMESYS: The collection /mylevel.collectionc could not be loaded. ``` -Kiedy silnik kończy wczytywanie kolekcji, pełnomocnik kolekcji wysyła wiadomość o treści `"proxy_loaded"` z powrotem do tego skryptu, który wysłał do niego polecenie wczytania kolekcji `"load"`. Skrypt może teraż zainicjalizować i aktywować kolekcję w odpowiedzi na tę wiadomość: +Gdy silnik zakończy wczytywanie kolekcji, pełnomocnik wyśle wiadomość `"proxy_loaded"` z powrotem do skryptu, który wysłał wiadomość `"load"`. Skrypt może wtedy zainicjalizować i aktywować kolekcję w reakcji na tę wiadomość: ```lua function on_message(self, message_id, message, sender) if message_id == hash("proxy_loaded") then - -- New world is loaded. Init and enable it. + -- Nowy świat został wczytany. Zainicjalizuj go i aktywuj. msg.post(sender, "init") msg.post(sender, "enable") ... @@ -70,74 +70,99 @@ end ``` `"load"` -: Ta wiadomość zleca pełnomocnikowi kolekcji rozpoczęcie wczytywania zasobów kolekcji do nowego świata gry. Pełnomocnik po wczytaniu odeśle wiadomość `"proxy_loaded"`. +: Ta wiadomość każe pełnomocnikowi kolekcji rozpocząć wczytywanie kolekcji do nowego świata. Gdy zakończy, odeśle wiadomość `"proxy_loaded"`. `"async_load"` -: Ta wiadomość zleca pełnomocnikowi kolekcji rozpoczęcie wczytywania zasobów kolekcji do nowego świata gry w tle, asynchronicznie. Pełnomocnik po wczytaniu odeśle wiadomość`"proxy_loaded"`. +: Ta wiadomość każe pełnomocnikowi kolekcji rozpocząć wczytywanie kolekcji do nowego świata w tle, asynchronicznie. Gdy zakończy, odeśle wiadomość `"proxy_loaded"`. `"init"` -: Ta wiadomość zleca pełnomocnikowi kolekcji inicjalizację wszystkich stworzonych instancji obiektów. Funkcje `init()` każdego skryptu zostają wywołane w tym momencie. +: Ta wiadomość każe pełnomocnikowi kolekcji zainicjalizować wszystkie utworzone instancje obiektów. Na tym etapie wywoływane są funkcje `init()` wszystkich skryptów. `"enable"` -: Ta wiadomość zleca pełnomocnikowi kolekcji aktywację wszystkich stworzonych instancji obiektów. Przykładowo, każdy komponent typu sprite jest rysowany na ekranie. +: Ta wiadomość każe pełnomocnikowi kolekcji aktywować wszystkie utworzone instancje obiektów. Na przykład komponenty sprite zaczynają wtedy być rysowane. -## Adresowanie nowego świata gry +## Adresowanie w nowym świecie -Właściwość *Name* ustawiona w pliku kolekcji jest używana do adresowania każdego z obiektów gry i komponentów wczytanego świata gry. Jeśli przykładowo utworzysz obiekt zajmujący się wczytywaniem poziomów (ang. loader), będziesz mieć możliwość komunikowania się z nim z poziomu każdej wczytanej kolekcji: +Właściwość *Name* ustawiona w pliku kolekcji służy do adresowania obiektów gry i komponentów wczytanego świata. Jeśli na przykład utworzysz obiekt odpowiedzialny za wczytywanie poziomów, będziesz mógł komunikować się z nim z dowolnej wczytanej kolekcji: ```lua --- tell the loader to load the next level: +-- poleć loaderowi wczytać następny poziom: msg.post("main:/loader#script", "load_level", { level_id = 2 }) ``` ![load](images/collection-proxy/message_passing.png) -## Zwalnianie pamięci po świecie gry +A jeśli chcesz komunikować się z obiektem gry w wczytanej kolekcji z poziomu loadera, możesz wysłać wiadomość, używając [pełnego URL-a obiektu](/manuals/addressing/#urls): -Aby zwolnić pamięć po wczytanej kolekcji możesz wysłać pełnomocnikowi tej kolekcji wiadomości odpowiadające kolejnym krokom: +```lua +msg.post("mylevel:/myobject", "hello") +``` + +::: important +Nie można bezpośrednio odwoływać się do obiektów gry w wczytanej kolekcji spoza tej kolekcji: + +```lua +local position = go.get_position("mylevel:/myobject") +-- loader.script:42: wywołana funkcja może uzyskiwać dostęp tylko do instancji w tej samej kolekcji. +``` +::: + + +## Zwalnianie świata + +Aby zwolnić wczytaną kolekcję, wysyła się do jej pełnomocnika wiadomości odpowiadające odwrotnej kolejności kroków wczytywania: ```lua --- unload the level +-- zwolnij poziom msg.post("#myproxy", "disable") msg.post("#myproxy", "final") msg.post("#myproxy", "unload") ``` `"disable"` -: Ta wiadomość zleca pełnomocnikowi kolekcji dezaktywację wszystkich stworzonych instancji obiektów. Przykładowo komponenty typu sprite przestają już być renderowane. +: Ta wiadomość każe pełnomocnikowi kolekcji wyłączyć wszystkie obiekty gry i komponenty w tym świecie. Na tym etapie sprite'y przestają być renderowane. `"final"` -: Ta wiadomość zleca pełnomocnikowi kolekcji finalizację wszystkich stworzonych instancji obiektów i komponentów. Funkcje `final()` każdego skryptu zostają wywołane w tym momencie. +: Ta wiadomość każe pełnomocnikowi kolekcji sfinalizować wszystkie obiekty gry i komponenty w tym świecie. Na tym etapie wywoływane są funkcje `final()` wszystkich skryptów. `"unload"` -: Ta wiadomość zleca pełnomocnikowi kolekcji rozpoczęcie zwalniania pamięci przeznaczonej na zasoby kolekcji. Pełnomocnik po zwolnieniu pamięci odeśle wiadomość `"proxy_unloaded"`. Świat gry zostaje całkowicie usunięty z pamięci. +: Ta wiadomość każe pełnomocnikowi kolekcji całkowicie usunąć świat z pamięci. -Jeśli nie zależy Ci na szczegółowej kontroli, możesz po prostu wysłać wiadomość `"unload"` bezpośrednio, bez uprzedniego dezaktywowania i finalizowania obiektów. Pełnomocnik kolekcji zajmie się wtedy automatycznie dezaktywacją i finalizowaniem zanim ostatecznie zwolni pamięć i usunie świat gry. +Jeśli nie potrzebujesz bardziej szczegółowej kontroli, możesz wysłać wiadomość `"unload"` bezpośrednio, bez wcześniejszego wyłączania i finalizowania kolekcji. Pełnomocnik automatycznie wyłączy i sfinalizuje kolekcję przed jej zwolnieniem. -Pełnomocnik kolekcji po zwolnieniu zwróci wiadomość `"proxy_unloaded"` z powrotem do tego skryptu, który wysłał do niego polecenie zwolnienia kolekcji `"unload"`: +Gdy pełnomocnik kolekcji zakończy zwalnianie, odeśle wiadomość `"proxy_unloaded"` do skryptu, który wysłał wiadomość `"unload"`: ```lua function on_message(self, message_id, message, sender) if message_id == hash("proxy_unloaded") then - -- Ok, the world is unloaded... + -- Ok, świat został zwolniony... ... end end ``` -## Krok czasowy +## Krok czasowy -Częstotliwość aktualizacji kolekcji (updates) może być kontrolowana przez pełnomocnika poprzez zmianę kroku czasowego (_time step_). Oznacza to, że nawet jeśli gra działa w stałych 60 klatkach na sekundę, pełnomocnik może aktualizować swoją kolekcję z większym lub mniejszym tempie, co wpływa na działanie symulacji fizyki i zmienną `dt` przekazywaną do funkcji `update()`. Możesz również ustawić tryb aktualizacji (update mode), który pozwala na kontrolowanie czy skalowanie powinno być przeprowadzone dyskretnie (co ma sens tylko przy współczynniku mniejszym od 1.0) lub ciągle. +Aktualizacje kolekcji obsługiwane przez pełnomocnika można skalować przez zmianę kroku czasowego. Oznacza to, że nawet jeśli gra działa ze stałą częstotliwością 60 FPS, pełnomocnik może aktualizować swoją kolekcję szybciej albo wolniej, co wpływa między innymi na: -Możesz kontrolować współczynnik skalowania kroku czasowego (factor) i tryb skalowania (mode) poprzez wiadomość `set_time_step`: +* prędkość symulacji fizyki +* wartość `dt` przekazywaną do `update()` +* [animacje właściwości obiektu gry i GUI](https://defold.com/manuals/animation/#property-animation-1) +* [animacje flipbook](https://defold.com/manuals/animation/#flip-book-animation) +* [symulacje Particle FX](https://defold.com/manuals/particlefx/) +* prędkość timerów + +Możesz też ustawić tryb aktualizacji, który pozwala kontrolować, czy skalowanie ma być wykonywane dyskretnie, co ma sens tylko przy współczynniku poniżej 1.0, czy w sposób ciągły. + +Współczynnik skalowania kroku czasowego i tryb skalowania kontroluje się przez wysłanie do pełnomocnika wiadomości `set_time_step`: ```lua --- update loaded world at one-fifth-speed. +-- aktualizuj wczytany świat z jedną piątą prędkości. msg.post("#myproxy", "set_time_step", {factor = 0.2, mode = 1} ``` -Aby zobaczyć, czy krok czasowy faktycznie uległ zmianie, możemy stworzyć obiekt z poniższym skryptem, w którym będziemy wypisywać wartość zmiennej `dt`: +Aby zobaczyć, co się dzieje przy zmianie kroku czasowego, możemy utworzyć obiekt z poniższym kodem w komponencie skryptowym i umieścić go w kolekcji, której krok czasowy zmieniamy: ```lua function update(self, dt) @@ -145,7 +170,7 @@ function update(self, dt) end ``` -Z krokiem czasowym 0.2, otrzymujemy we get the following result in the console: +Przy kroku czasowym 0.2 otrzymujemy następujący wynik w konsoli: ```txt INFO:DLIB: SSDP started (ssdp://192.168.0.102:54967, http://0.0.0.0:62162) @@ -163,17 +188,21 @@ DEBUG:SCRIPT: update() with timestep (dt) 0 DEBUG:SCRIPT: update() with timestep (dt) 0.016666667535901 ``` -Jak widać funkcja `update()` jest nadal wywoływana 60 razy na sekundę, ale wartość `dt` zmienia się. Widzimy, że jedynie co piąte wywołanie, czyli 1/5 (0.2) wszystkich wywołań funkcji `update()` ma wartość `dt` odpowiadającą 1/60 (dla 60 FPS)--- w pozostałych przypadkach - 0. Symulacja fizyki również będzie odświeżana w zależności od danego `dt`, więc postępy będą widoczne tylko w co 5 klatce. +`update()` jest nadal wywoływane 60 razy na sekundę, ale wartość `dt` się zmienia. Widzimy, że tylko 1/5 wywołań `update()` będzie miało `dt` równy 1/60, czyli odpowiadający 60 FPS, a reszta będzie równa zero. Wszystkie symulacje fizyki również będą aktualizowane zgodnie z tym `dt` i będą postępować tylko w co piątej klatce. + +::: sidenote +Możesz użyć funkcji kroku czasowego kolekcji, aby wstrzymać grę, na przykład podczas wyświetlania popupu albo gdy okno straci fokus. Użyj `msg.post("#myproxy", "set_time_step", {factor = 0, mode = 0})`, aby wstrzymać, oraz `msg.post("#myproxy", "set_time_step", {factor = 1, mode = 1})`, aby wznowić. +::: -Więcej szczegółów znajdziesz tutaj: [`set_time_step`](/ref/collectionproxy#set_time_step). +Więcej szczegółów znajdziesz w [`set_time_step`](/ref/collectionproxy#set_time_step). -## Uwagi i częste błędy +## Uwagi i częste problemy Fizyka -: Dzięki pełnomocnikom kolekcji możliwe jest załadowanie więcej niż jednego *świata gry*. Czyniąc to trzeba mieć na uwadze, że każdy taki świat wiąże się z osobnym światem fizyki. Interakcje fizyki (kolizje, przełączniki, promienie wykrywające) będą miały miejsce jedynie pomiędzy obiektami tej samej kolekcji (tego samego świata fizyki), a nie między obiektami z innych kolekcji. Więc nawet wizualne nakładanie się obiektów z kolizjami, ale z dwóch różnych światów, nie będzie miało skutku w symulacji fizyki. +: Za pomocą pełnomocników kolekcji można wczytać więcej niż jedną kolekcję najwyższego poziomu, czyli więcej niż jeden *świat gry*, do silnika. Trzeba pamiętać, że każda taka kolekcja najwyższego poziomu jest osobnym światem fizyki. Interakcje fizyczne, takie jak kolizje, wyzwalacze i ray-casty, zachodzą wyłącznie między obiektami należącymi do tego samego świata. Nawet jeśli obiekty kolizji z dwóch światów wizualnie leżą dokładnie jeden na drugim, nie będzie między nimi żadnej interakcji fizycznej. Pamięć -: Każda załadowana kolekcja tworzy nowy świat gry, który od razu zajmuje relatywnie sporo pamięci. Jeśli załadujesz naraz zbyt dużo kolekcji możesz wyczerpać dostępne zasoby - warto więc przemyśleć design. Do tworzenia wielu instancji hierarchii obiektów gry (np. wrogów, pocisków, obiektów dekoracyjnych, itd.) warto używać [fabryk kolekcji](/manuals/collection-factory), które tworzą obiekty i przypisują im relacje, ale nie tworzą nowych światów. +: Każda wczytana kolekcja tworzy nowy świat gry, który wiąże się ze stosunkowo dużym zużyciem pamięci. Jeśli jednocześnie wczytasz przez pełnomocników wiele kolekcji, warto przemyśleć projekt. Do tworzenia wielu instancji hierarchii obiektów gry lepiej nadają się [fabryki kolekcji](/manuals/collection-factory), które tworzą obiekty, ale nie tworzą nowych światów. -Wejścia -: Jeśli obiekty w załadowanej kolekcji wymagają wejść z kontrolerów, musisz się upewnić, że obiekt, który posiada pełnomocnika danej kolekcji również przechwytuje wejścia. Kiedy obiekt gry otrzymuje wiadomości z wejściami kontrolerów przekazuje je do swoich komponentów - czyli może je przekazać do swojego komponentu typu pełnomocnik kolekcji. Pełnomocnik z kolei przekazuje przechwycone wejście do załadowanej kolekcji i jej obiektów. \ No newline at end of file +Wejście +: Jeśli obiekty w wczytanej kolekcji wymagają akcji wejściowych, musisz upewnić się, że obiekt zawierający pełnomocnika kolekcji przechwytuje wejście. Gdy obiekt gry otrzymuje wiadomości wejściowe, są one propagowane do komponentów tego obiektu, czyli także do pełnomocników kolekcji. Akcje wejściowe są następnie przekazywane przez pełnomocnika do wczytanej kolekcji i jej obiektów. diff --git a/docs/pl/manuals/components.md b/docs/pl/manuals/components.md index 7961a2ad..07ebd45c 100644 --- a/docs/pl/manuals/components.md +++ b/docs/pl/manuals/components.md @@ -1,6 +1,6 @@ --- title: Komponenty obiektów gry -brief: Ta instrukcja prezentuje przegląd komponentów i jak ich używać. +brief: Ta instrukcja daje przegląd komponentów i sposobów ich używania. --- # Komponenty @@ -11,78 +11,83 @@ brief: Ta instrukcja prezentuje przegląd komponentów i jak ich używać. Defold wspiera następujące typy komponentów: -* [Collection factory](/manuals/collection-factory) - Fabryki kolecji do ich tworzenia -* [Collection proxy](/manuals/collection-proxy) - Pełnomocnicy kolekcji do ich ładowania i zwalniania -* [Collision object](/manuals/physics) - Obiekty kolizji fizyki 2D i 3D -* [Camera](/manuals/camera) - Kamera, umożliwiająca zmianę projekcji i rzutni świata gry +* [Collection factory](/manuals/collection-factory) - Fabryka kolekcji do tworzenia kolekcji +* [Collection proxy](/manuals/collection-proxy) - Pełnomocnik kolekcji do ładowania i zwalniania kolekcji +* [Collision object](/manuals/physics) - Obiekt kolizji do fizyki 2D i 3D +* [Camera](/manuals/camera) - Kamera zmieniająca rzutnię i projekcję świata gry * [Factory](/manuals/factory) - Fabryka do tworzenia obiektów gry * [GUI](/manuals/gui) - Graficzny interfejs użytkownika -* [Label](/manuals/label) - Etykieta z tekstem -* [Mesh](/manuals/mesh) - Siatka trójwymiarowa (z tworzeniem i manipulacją w trakcie działania aplikacji) -* [Model](/manuals/model) - Model trójwymiarowy (z opcjonalnymi animacjami) -* [Particle FX](/manuals/particlefx) - Efekty cząsteczkowe -* [Script](/manuals/script) - Skrypt, dodający logikę do gry +* [Label](/manuals/label) - Etykieta tekstu +* [Mesh](/manuals/mesh) - Siatka 3D z możliwością tworzenia i modyfikowania w czasie działania gry +* [Model](/manuals/model) - Model 3D z opcjonalnymi animacjami +* [Particle FX](/manuals/particlefx) - Emitowanie cząsteczek +* [Script](/manuals/script) - Dodawanie logiki gry * [Sound](/manuals/sound) - Odtwarzanie dźwięku lub muzyki -* [Spine model](/manuals/spinemodel) - Model szkieletowy animacji -* [Sprite](/manuals/sprite) - Obraz dwuwymiarowy (z opcjonalną animacją poklatkową) -* [Tilemap](/manuals/tilemap) - Mapa kafelków +* [Sprite](/manuals/sprite) - Obraz 2D z opcjonalną animacją flipbook +* [Tilemap](/manuals/tilemap) - Wyświetlanie siatki kafelków + +Dodatkowe komponenty można dodać przez rozszerzenia: + +* [Rive model](/extension-rive) - Renderowanie animacji Rive +* [Spine model](/extension-spine) - Renderowanie animacji Spine + ## Aktywowanie i dezaktywowanie komponentów -Komponenty obiektów gry są aktywne wraz z utworzeniem ich obiektu gry. Jeśli chcesz je dezaktywować możesz wysłać wiadomość [`disable`](/ref/go/#disable) do danego komponentu: +Komponenty obiektu gry są aktywne od chwili utworzenia tego obiektu. Jeśli chcesz wyłączyć komponent, wyślij do niego wiadomość [`disable`](/ref/go/#disable): ```lua --- disable the component with id 'weapon' on the same game object as this script +-- wyłączenie komponentu o identyfikatorze 'weapon' na tym samym obiekcie gry, co ten skrypt msg.post("#weapon", "disable") --- disable the component with id 'shield' on the 'enemy' game object +-- wyłączenie komponentu o identyfikatorze 'shield' na obiekcie gry 'enemy' msg.post("enemy#shield", "disable") --- disable all components on the current game object +-- wyłączenie wszystkich komponentów na bieżącym obiekcie gry msg.post(".", "disable") --- disable all components on the 'enemy' game object +-- wyłączenie wszystkich komponentów na obiekcie gry 'enemy' msg.post("enemy", "disable") ``` -To enable a component again you can post an [`enable`](/ref/go/#enable) message to the component: +Aby ponownie włączyć komponent, wyślij do niego wiadomość [`enable`](/ref/go/#enable): ```lua --- enable the component with id 'weapon' +-- włączenie komponentu o identyfikatorze 'weapon' msg.post("#weapon", "enable") ``` ## Właściwości komponentów -Komponenty w Defoldzie mają różne właściwości. Panel [Właściwości](/manuals/editor/#the-editor-views) w edytorze pokazuje właściwości aktualnie wybranego w panelu [Outline](/manuals/editor/#the-editor-views) komponentu. Szukaj właściwości różnych komponentów w instrukcjach do nich. +Typy komponentów w Defoldzie mają różne właściwości. [Panel Properties](/manuals/editor/#the-editor-views) w edytorze pokazuje właściwości aktualnie zaznaczonego komponentu w [panelu Outline](/manuals/editor/#the-editor-views). Więcej informacji o dostępnych właściwościach znajdziesz w instrukcjach poszczególnych typów komponentów. -## Pozycja, orientacja i skala komponentów +## Położenie, obrót i skala komponentów -Komponenty wizualne mają pozycję, orientację i niektóre skalę. Właściwości te mogą być zmienione z poziomu Edytora Defold, ale w większości przypadków nie mogą już być zmienione w trakcie działania aplikacji (wyjątkiem jest skala sprite'ów i etykiet (label)). +Komponenty wizualne zwykle mają właściwość położenia i obrotu, a najczęściej także skalę. Właściwości te można zmieniać w edytorze, ale w niemal wszystkich przypadkach nie da się ich zmienić w czasie działania gry. Wyjątkiem jest skala komponentów sprite i label, którą można zmieniać także w trakcie działania. -Jeśli potrzebujesz zmienić pozycję, rotację czy skalę komponentu w czasie działania programu możesz zmienić właściwości obiektu gry, który posiada te komponenty. Skutkuje to jednak zmianą właściwości wszystkich komponentów danego obiektu gry. Jeśli chcesz manipulować pojedynczym komponentem, zalecamy, żeby przenieść dany komponent do innego obiektu gry, który będzie posiadał go osobno, a następnie dodanie takiego obiektu jako dziecko podstawowego obiektu, do którego komponent należał początkowo. +Jeśli musisz zmienić położenie, obrót albo skalę komponentu w czasie działania gry, zmień zamiast tego położenie, obrót albo skalę obiektu gry, do którego ten komponent należy. Ma to jednak taki skutek uboczny, że wpłynie na wszystkie komponenty na tym obiekcie gry. Jeśli chcesz sterować tylko jednym komponentem spośród wielu przypisanych do obiektu gry, zaleca się przenieść ten komponent do osobnego obiektu gry i dodać go jako obiekt potomny do obiektu gry, do którego pierwotnie należał. ## Kolejność rysowania komponentów -Kolejność rysowania komponentów zależy od: +Kolejność rysowania komponentów wizualnych zależy od dwóch rzeczy: -### Predykaty skryptu renderowania -Każdy komponent ma przypisany [materiał](/manuals/material/), a każdy materiał ma jeden lub więcej tagów. Skrypt renderowania z kolei określa liczbę predykatów, z których każdy odpowiada tagowi. [Predykaty są rysowane jeden nad poprzednim](/manuals/render/#render-predicates) w funkcji *update()*, a komponenty, których materiały mają tagi określone dla danego predykatu są wtedy rysowane. Domyślny skrypt renderowania wyrysuje najpierw sprite'y i mapy kafelków, następnie efekty cząsteczkowe osobno w przestrzeni świata gry, a na końcu komponenty GUI w przestrzeni ekranu. +### Predykaty skryptu do renderowania +Każdemu komponentowi przypisany jest [material](/manuals/material/), a każdy material ma jeden lub więcej tagów. Z kolei skrypt do renderowania definiuje zestaw predykatów, a każdy z nich dopasowuje jeden lub więcej tagów materiału. [Predykaty są rysowane jeden po drugim](/manuals/render/#render-predicates) w funkcji *update()* skryptu do renderowania, a następnie rysowane są komponenty pasujące do tagów zdefiniowanych w każdym predykacie. Domyślny skrypt do renderowania najpierw rysuje sprite'y i tilemapy w jednym przebiegu, potem efekty cząsteczkowe w drugim przebiegu, oba w przestrzeni świata. Następnie przechodzi do rysowania komponentów GUI w osobnym przebiegu w przestrzeni ekranu. -### Wartość współrzędnej Z -Wszystkie obiekty gry i komponenty są umieszczone w przestrzeni 3D z pozycją jako wektor trzech współrzędnych. Kiedy oglądasz swoją grę w 2D, wspołrzędne X i Y pozycję elementu na ekranie wzdłuż szerokości i wysokości, a współrzędna Z określa głębokość. Umożliwia to więc określanie pozycji nachodzących się na siebie kształtów: sprite z wartością Z = 1 pojawi się przed sprite'm z pozycją Z = 0. Domyślnie, Defold umożliwia rysowanie obiektów na osi Z o wartościach z przedziału -1 i 1: +### Wartość Z komponentu +Wszystkie obiekty gry i komponenty są umieszczone w przestrzeni 3D, a ich pozycje są wyrażane jako obiekty vector3. Gdy oglądasz grafikę swojej gry w 2D, wartości X i Y określają położenie obiektu na osiach szerokości i wysokości, a pozycja Z określa położenie na osi głębokości. Pozycja Z pozwala kontrolować widoczność nakładających się obiektów: sprite z wartością Z równą 1 pojawi się przed sprite'em na pozycji Z równej 0. Domyślnie Defold używa układu współrzędnych, w którym wartości Z mieszczą się w zakresie od -1 do 1: ![model](images/graphics/z-order.png) -Komponenty, których materiały mają tagi określone dla danego [predykatu](/manuals/render/#render-predicates) są rysowane razem, a kolejność ich rysowania zależy od ostatecznej wartości współrzędnej Z. Ostateczna wartość Z jest sumą wartości Z komponentu, obiektu gry i każdego obiektu, do którego należy dany obiektu (rodzica). +Komponenty pasujące do [predykatu renderowania](/manuals/render/#render-predicates) są rysowane razem, a kolejność ich rysowania zależy od końcowej wartości Z komponentu. Końcowa wartość Z komponentu jest sumą wartości Z samego komponentu, obiektu gry, do którego należy, oraz wartości Z wszystkich nadrzędnych obiektów gry. ::: sidenote -Kolejność, w której rysowane są komponenty GUI components **NIE** jest określona przez współrzędne Z komponentów GUI. Kolejność ta jest kontrolowana przez funkcję [gui.set_render_order()](/ref/gui/#gui.set_render_order:order). +Kolejność rysowania wielu komponentów GUI **nie** jest określana przez wartość Z tych komponentów. Kolejność rysowania komponentów GUI kontroluje funkcja [gui.set_render_order()](/ref/gui/#gui.set_render_order:order). ::: -Przykład: Dwa obiekty gry A i B. Obiekt B jest dzieckiem obiektu A. Obiekt B ma komponent typu sprite. +Przykład: Dwa obiekty gry A i B. B jest obiektem potomnym A. B ma komponent sprite. -| Id | Z | +| Co | Wartość Z | |----------|---------| | A | 2 | | B | 1 | @@ -90,10 +95,13 @@ Przykład: Dwa obiekty gry A i B. Obiekt B jest dzieckiem obiektu A. Obiekt B ma ![](images/graphics/component-hierarchy.png) -Przy powyższej hierarchi ostateczna wartość Z komponentu typu sprite to 2 + 1 + 0.5 = 3.5. +W powyższej hierarchii końcowa wartość Z komponentu sprite na obiekcie B wynosi 2 + 1 + 0.5 = 3.5. ::: important -Jeśli dwa komponenty mają dokładnie taką samą wartość komponentu Z, to kolejność rysowania jest nieokreślona i obiekty mogą migać zmieniając nieustannie tę kolejność w zależności od platformy. +Jeśli dwa komponenty mają dokładnie taką samą wartość Z, kolejność jest nieokreślona i komponenty mogą migać, przełączając się między sobą, albo być renderowane w innej kolejności na różnych platformach. -Domyślny skrypt renderowania określa najbliższą i najdalszą powierzchnię na osi Z (równoległą do płaszczyzny XY), która zostanie wyrysowana. Każdy komponent, który miałby być wyrysowany poza tymi wartościami nie będzie renderowany. Domyślny przedział wartości Z to -1 do 1, ale z łatwością [można go zmienić](/manuals/render/#default-view-projection). Precyzja numeryczna wartości Z pomiędzy wartościa -1 i 1 jest bardzo wysoka. Pracując z zasobami 3D, możesz chciceć zmienić limity najbliższej i najdalszej powierzchni w Twoim skrypie renderowania. Więcej szczegółów znajdziesz w [instrucji do renderowania](/manuals/render/). +Skrypt do renderowania definiuje bliską i daleką płaszczyznę dla wartości Z. Każdy komponent, którego wartość Z znajduje się poza tym zakresem, nie zostanie wyrenderowany. Domyślny zakres to od -1 do 1, ale [można go łatwo zmienić](/manuals/render/#default-view-projection). Precyzja numeryczna wartości Z przy granicach bliskiej i dalekiej płaszczyzny ustawionych na -1 i 1 jest bardzo wysoka. Pracując z zasobami 3D, możesz potrzebować zmienić te granice w niestandardowym skrypcie do renderowania. Więcej informacji znajdziesz w [instrukcji Render](/manuals/render/). ::: + + +:[Optymalizacje maksymalnej liczby komponentów](../shared/component-max-count-optimizations.md) diff --git a/docs/pl/manuals/compute.md b/docs/pl/manuals/compute.md new file mode 100644 index 00000000..5417cbba --- /dev/null +++ b/docs/pl/manuals/compute.md @@ -0,0 +1,234 @@ +--- +title: Instrukcja compute w Defold +brief: Ta instrukcja wyjaśnia, jak pracować z programami compute, stałymi shaderów i samplerami. +--- + +# Programy compute + +::: sidenote +Obsługa shaderów obliczeniowych (ang. compute shaders) w Defold jest obecnie w fazie *technical preview*. +Oznacza to, że pewnych funkcji jeszcze brakuje i że API może w przyszłości ulec zmianie. +::: + +Shadery obliczeniowe są potężnym narzędziem do wykonywania obliczeń ogólnego przeznaczenia na GPU. Pozwalają wykorzystać równoległą moc obliczeniową GPU do zadań takich jak symulacje fizyki, przetwarzanie obrazów i wiele innych. Shader obliczeniowy działa na danych przechowywanych w buforach lub teksturach, wykonując operacje równolegle w wielu wątkach GPU. Właśnie ta równoległość sprawia, że shadery obliczeniowe są tak skuteczne przy wymagających obliczeniach. + +* Więcej informacji o potoku renderowania znajdziesz w [dokumentacji renderowania](/manuals/render). +* Szczegółowe wyjaśnienie programów shaderowych znajdziesz w [dokumentacji shaderów](/manuals/shader). + +## Do czego można używać shaderów obliczeniowych? + +Ponieważ shadery obliczeniowe służą do ogólnych obliczeń, praktycznie nie ma ograniczeń co do tego, do czego możesz ich użyć. Oto kilka przykładów typowych zastosowań shaderów obliczeniowych: + +Przetwarzanie obrazów + - Filtrowanie obrazów: stosowanie rozmycia, wykrywania krawędzi, wyostrzania i podobnych efektów. + - Korekcja barw: dostosowywanie przestrzeni kolorów obrazu. + +Fizyka + - Systemy cząsteczek: symulacja dużej liczby cząsteczek dla efektów takich jak dym, ogień i dynamika płynów. + - Fizyka ciał miękkich: symulacja odkształcalnych obiektów, takich jak tkanina i galaretka. + - Odrzucanie: `occlusion culling`, `frustum culling` + +Generowanie proceduralne + - Generowanie terenu: tworzenie szczegółowego terenu przy użyciu funkcji szumu. + - Roślinność i zarośla: tworzenie proceduralnie generowanych roślin i drzew. + +Efekty renderowania + - Oświetlenie globalne (`global illumination`): symulowanie realistycznego oświetlenia przez przybliżenie sposobu, w jaki światło odbija się w scenie. + - Wokselizacja (`voxelization`): tworzenie trójwymiarowej siatki wokseli z danych siatki. + +## Jak działają shadery obliczeniowe? + +Na wysokim poziomie shadery obliczeniowe działają przez podział zadania na wiele mniejszych zadań, które mogą zostać wykonane jednocześnie. Odbywa się to dzięki pojęciom `work groups` i `invocations`: + +Grupy robocze +: Shader obliczeniowy działa na siatce `work groups`. Każda grupa robocza zawiera stałą liczbę wywołań (wątków). Rozmiar grup roboczych i liczba wywołań są definiowane w kodzie shadera. + +Wywołania +: Każde wywołanie (wątek) wykonuje program shadera obliczeniowego. Wywołania w obrębie jednej grupy roboczej mogą współdzielić dane przez pamięć współdzieloną, co pozwala na wydajną komunikację i synchronizację między nimi. + +GPU wykonuje shader obliczeniowy, uruchamiając równolegle wiele wywołań w wielu grupach roboczych, co zapewnia znaczną moc obliczeniową dla odpowiednich zadań. + +## Tworzenie programu compute + +Aby utworzyć program compute, right click docelowy folder w widoku *Assets* i wybierz New... ▸ Compute. Możesz też wybrać z menu File ▸ New..., a następnie Compute. Nadaj nazwę nowemu plikowi compute i naciśnij Ok. + +![Plik compute](images/compute/compute_file.png) + +Nowy plik compute otworzy się w *Compute Editor*. + +![Edytor compute](images/compute/compute.png) + +Plik compute zawiera następujące informacje: + +Compute Program +: Plik programu shadera compute (*`.cp`*), którego należy użyć. Shader działa na „abstrakcyjnych elementach roboczych”, co oznacza, że nie ma stałej definicji typów danych wejściowych i wyjściowych. To programista definiuje, co shader obliczeniowy ma wygenerować. + +Constants +: Uniformy, które zostaną przekazane do programu shadera compute. Poniżej znajdziesz listę dostępnych stałych. + +Samplers +: W pliku materiału możesz opcjonalnie skonfigurować konkretne samplery. Dodaj sampler, nazwij go zgodnie z nazwą używaną w programie shadera i ustaw parametry wrap oraz filter według potrzeb. + + +## Używanie programu compute w Defold + +W odróżnieniu od materiałów programy compute nie są przypisywane do żadnych komponentów i nie są częścią normalnego przebiegu renderowania. Aby wykonały jakąkolwiek pracę, trzeba je wywołać (`dispatch`) w skrypcie do renderowania. Zanim jednak to zrobisz, musisz upewnić się, że skrypt do renderowania ma odwołanie do programu compute. Obecnie jedynym sposobem, aby skrypt do renderowania wiedział o programie compute, jest dodanie go do pliku .render, który przechowuje odwołanie do twojego skryptu do renderowania: + +![Plik render z compute](images/compute/compute_render_file.png) + +Aby użyć programu compute, trzeba go najpierw powiązać z kontekstem renderowania. Robi się to tak samo jak w przypadku materiałów: + +```lua +render.set_compute("my_compute") +-- Tutaj wykonuj pracę compute; wywołaj render.set_compute(), aby odwiązać program +render.set_compute() +``` + +Choć stałe compute zostaną automatycznie zastosowane podczas dispatchowania programu, z poziomu edytora nie da się powiązać z programem compute żadnych zasobów wejściowych ani wyjściowych (tekstur, buforów itd.). Zamiast tego trzeba to zrobić w skryptach do renderowania: + +```lua +render.enable_texture("blur_render_target", "tex_blur") +render.enable_texture(self.storage_texture, "tex_storage") +``` + +Aby uruchomić program w wybranej przez siebie przestrzeni roboczej, musisz go wywołać: + +```lua +render.dispatch_compute(128, 128, 1) +-- dispatch_compute przyjmuje też tabelę opcji jako ostatni argument +-- tej tabeli możesz użyć do przekazania stałych renderowania do wywołania dispatch +local constants = render.constant_buffer() +constants.tint = vmath.vector4(1, 1, 1, 1) +render.dispatch_compute(32, 32, 32, {constants = constants}) +``` + +### Zapisywanie danych z programów compute + +Obecnie generowanie jakiegokolwiek rodzaju danych wyjściowych z programu compute jest możliwe tylko za pomocą `storage textures`. Tekstura storage jest podobna do „zwykłej tekstury”, ale oferuje więcej funkcji i możliwości konfiguracji. Jak sugeruje nazwa, tekstury storage mogą służyć jako ogólny bufor, z którego program compute może odczytywać i do którego może zapisywać dane. Ten sam bufor możesz potem powiązać z innym programem shadera do odczytu. + +Aby utworzyć teksturę storage w Defold, musisz zrobić to ze zwykłego pliku .script. Skrypty do renderowania nie mają tej funkcjonalności, ponieważ tekstury dynamiczne trzeba tworzyć przez API zasobów, które jest dostępne tylko w zwykłych plikach .script. + +```lua +-- W pliku .script: +function init(self) + -- Utwórz zasób tekstury jak zwykle, ale dodaj flagę "storage", + -- aby można go było użyć jako zaplecza dla programów compute + local t_backing = resource.create_texture("/my_backing_texture.texturec", { + type = resource.TEXTURE_TYPE_IMAGE_2D, + width = 128, + height = 128, + format = resource.TEXTURE_FORMAT_RGBA32F, + flags = resource.TEXTURE_USAGE_FLAG_STORAGE + resource.TEXTURE_USAGE_FLAG_SAMPLE, + }) + + -- pobierz uchwyt tekstury z zasobu + local t_backing_handle = resource.get_texture_info(t_backing).handle + + -- powiadom renderer o teksturze zaplecza, aby można było ją powiązać przez render.enable_texture + msg.post("@render:", "set_backing_texture", { handle = t_backing_handle }) +end +``` + +## Łącząc wszystko w całość + +### Program shadera + +```glsl +// compute.cp +#version 450 + +layout (local_size_x = 1, local_size_y = 1, local_size_z = 1) in; + +// określ zasoby wejściowe +uniform vec4 color; +uniform sampler2D texture_in; + +// określ obraz wyjściowy +layout(rgba32f) uniform image2D texture_out; + +void main() +{ + // To nie jest szczególnie ciekawy shader, ale pokazuje, + // jak czytać z tekstury i bufora stałych oraz zapisywać do tekstury storage + + ivec2 tex_coord = ivec2(gl_GlobalInvocationID.xy); + vec4 output_value = vec4(0.0, 0.0, 0.0, 1.0); + vec2 tex_coord_uv = vec2(float(tex_coord.x)/(gl_NumWorkGroups.x), float(tex_coord.y)/(gl_NumWorkGroups.y)); + vec4 input_value = texture(texture_in, tex_coord_uv); + output_value.rgb = input_value.rgb * color.rgb; + + // Zapisz wartość wyjściową do tekstury storage + imageStore(texture_out, tex_coord, output_value); +} +``` + +### Komponent skryptowy +```lua +-- W pliku .script: + +-- Tutaj określamy teksturę wejściową, którą później powiążemy +-- z programem compute. Możemy przypisać tę teksturę do komponentu modelu +-- albo włączyć ją w kontekście renderowania w skrypcie do renderowania. +go.property("texture_in", resource.texture()) + +function init(self) + -- Utwórz zasób tekstury jak zwykle, ale dodaj flagę "storage", + -- aby można go było użyć jako zaplecza dla programów compute + local t_backing = resource.create_texture("/my_backing_texture.texturec", { + type = resource.TEXTURE_TYPE_IMAGE_2D, + width = 128, + height = 128, + format = resource.TEXTURE_FORMAT_RGBA32F, + flags = resource.TEXTURE_USAGE_FLAG_STORAGE + resource.TEXTURE_USAGE_FLAG_SAMPLE, + }) + + local textures = { + texture_in = resource.get_texture_info(self.texture_in).handle, + texture_out = resource.get_texture_info(t_backing).handle + } + + -- powiadom renderer o teksturach wejściowej i wyjściowej + msg.post("@render:", "set_backing_texture", textures) +end +``` + +### Skrypt do renderowania +```lua +-- reaguj na wiadomość "set_backing_texture", +-- aby ustawić teksturę zaplecza dla programu compute +function on_message(self, message_id, message) + if message_id == hash("set_backing_texture") then + self.texture_in = message.texture_in + self.texture_out = message.texture_out + end +end + +function update(self) + render.set_compute("compute") + -- Możemy powiązać tekstury z konkretnymi nazwanymi stałymi + render.enable_texture(self.texture_in, "texture_in") + render.enable_texture(self.texture_out, "texture_out") + render.set_constant("color", vmath.vector4(0.5, 0.5, 0.5, 1.0)) + -- Uruchom program compute tyle razy, ile mamy pikseli. + -- To stanowi naszą "grupę roboczą". Shader zostanie wywołany + -- 128 x 128 x 1 razy, czyli raz na piksel. + render.dispatch_compute(128, 128, 1) + -- Gdy skończymy pracę z programem compute, musimy go odwiązać + render.set_compute() +end +``` + +## Zgodność + +Defold obsługuje obecnie shadery obliczeniowe na następujących adapterach graficznych: + +- Vulkan +- Metal (przez MoltenVK) +- OpenGL 4.3+ +- OpenGL ES 3.1+ + +::: sidenote +Obecnie nie ma sposobu, aby sprawdzić, czy uruchomiony klient obsługuje shadery obliczeniowe. +Oznacza to, że jeśli adapter graficzny jest oparty na OpenGL lub OpenGL ES, nie ma gwarancji, że klient obsłuży uruchamianie shaderów obliczeniowych. +Vulkan i Metal obsługują shadery obliczeniowe od wersji 1.0. Aby użyć Vulkan, musisz utworzyć własny manifest i wybrać ten backend. +::: diff --git a/docs/pl/manuals/debugging-game-and-system-logs.md b/docs/pl/manuals/debugging-game-and-system-logs.md new file mode 100644 index 00000000..3b38e326 --- /dev/null +++ b/docs/pl/manuals/debugging-game-and-system-logs.md @@ -0,0 +1,112 @@ +--- +title: Debugowanie - logi gry i systemu +brief: Ta instrukcja wyjaśnia, jak czytać logi gry i systemu. +--- + +# Logi gry i systemu + +Log gry pokazuje całe wyjście z silnika, rozszerzeń natywnych i logiki gry. Polecenia [print()](/ref/stable/base/#print:...) oraz [pprint()](/ref/stable/builtins/?q=pprint#pprint:v) można wywoływać ze skryptów i modułów Lua, aby wyświetlać informacje w logu gry. Z poziomu rozszerzeń natywnych możesz używać funkcji w przestrzeni nazw [`dmLog` namespace](/ref/stable/dmLog/), aby zapisywać do logu gry. Log gry można odczytać w edytorze, w oknie terminala, przy użyciu narzędzi specyficznych dla platformy albo z pliku logu. + +Logi systemowe są generowane przez system operacyjny i mogą dostarczyć dodatkowych informacji, które pomagają namierzyć problem. Mogą też zawierać ślady stosu po awariach oraz ostrzeżenia o niskim poziomie pamięci. + +::: important +Logowanie do konsoli/na ekranie pokazuje informacje tylko w buildach Debug. W buildach Release log konsoli jest pusty, ale możesz włączyć logowanie do pliku w Release, ustawiając opcję projektu "Write Log File" na "Always". Szczegóły poniżej. +::: + +## Odczytywanie logu gry w edytorze + +Gdy uruchamiasz grę lokalnie z edytora albo na urządzeniu połączonym z [mobilną aplikacją deweloperską](/manuals/dev-app), całe wyjście będzie widoczne w panelu konsoli edytora: + +![Edytor 2](images/editor/editor2_overview.png) + +## Odczytywanie logu gry z terminala + +Gdy uruchamiasz grę Defold z terminala, log będzie wyświetlany bezpośrednio w samym oknie terminala. W systemach Windows i Linux wpisujesz w terminalu nazwę pliku wykonywalnego, aby uruchomić grę. W macOS musisz uruchomić silnik z wnętrza pliku .app: + +``` +$ > ./mygame.app/Contents/MacOS/mygame +``` + +## Odczytywanie logów gry i systemu przy użyciu narzędzi specyficznych dla platformy + +### HTML5 + +Logi można odczytywać przy użyciu narzędzi deweloperskich dostępnych w większości przeglądarek. + +* [Chrome](https://developers.google.com/web/tools/chrome-devtools/console) - Menu > More Tools > Developer Tools +* [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Browser_Console) - Tools > Web Developer > Web Console +* [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/console) +* [Safari](https://support.apple.com/guide/safari-developer/log-messages-with-the-console-dev4e7dedc90/mac) - Develop > Show JavaScript Console + +### Android + +Do podglądu logów gry i systemu możesz użyć narzędzia Android Debug Bridge (ADB). + +:[Android ADB](../shared/android-adb.md) + +Po zainstalowaniu i skonfigurowaniu podłącz urządzenie przez USB, otwórz terminal i uruchom: + +```txt +$ cd /platform-tools/ +$ adb logcat +``` + +Urządzenie wypisze wtedy całe wyjście do bieżącego terminala, wraz z komunikatami z gry. + +Jeśli chcesz widzieć wyłącznie wyjście aplikacji Defold, użyj tego polecenia: + +```txt +$ cd /platform-tools/ +$ adb logcat -s defold +--------- beginning of /dev/log/system +--------- beginning of /dev/log/main +I/defold ( 6210): INFO:DLIB: SSDP started (ssdp://192.168.0.97:58089, http://0.0.0.0:38637) +I/defold ( 6210): INFO:ENGINE: Defold Engine 1.2.50 (8d1b912) +I/defold ( 6210): INFO:ENGINE: Loading data from: +I/defold ( 6210): INFO:ENGINE: Initialized sound device 'default' +I/defold ( 6210): +D/defold ( 6210): DEBUG:SCRIPT: Hello there, log! +... +``` + +### iOS + +Masz kilka sposobów odczytywania logów gry i systemu na iOS: + +1. Możesz użyć narzędzia [Console](https://support.apple.com/guide/console/welcome/mac), aby czytać logi gry i systemu. +2. Możesz użyć debuggera LLDB, aby dołączyć do gry uruchomionej na urządzeniu. Aby debugować grę, musi ona być podpisana profilem „Apple Developer Provisioning Profile”, który obejmuje urządzenie, na którym chcesz debugować. Spakuj grę z edytora i podaj provisioning profile w oknie dialogowym bundlowania (bundlowanie dla iOS jest dostępne tylko na macOS). + +Aby uruchomić grę i dołączyć debugger, potrzebujesz narzędzia [ios-deploy](https://github.com/phonegap/ios-deploy). Zainstaluj je i uruchom debugowanie gry, wpisując w terminalu: + +```txt +$ ios-deploy --debug --bundle # UWAGA: to nie jest plik .ipa +``` + +To polecenie zainstaluje aplikację na urządzeniu, uruchomi ją i automatycznie dołączy do niej debugger LLDB. Jeśli dopiero zaczynasz z LLDB, przeczytaj [Getting Started with LLDB](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/gdb_to_lldb_transition_guide/document/lldb-basics.html). + + +## Odczytywanie logu gry z pliku logu + +Użyj ustawienia projektu "Write Log File" w pliku *game.project*, aby sterować logowaniem do pliku: + +- "Never": Nie zapisuj pliku logu. +- "Debug": Zapisuj plik logu tylko dla buildów Debug. +- "Always": Zapisuj plik logu zarówno dla buildów Debug, jak i Release. + +Po włączeniu całe wyjście gry będzie zapisywane na dysku do pliku o nazwie "`log.txt`". Oto jak pobrać ten plik, jeśli uruchamiasz grę na urządzeniu: + +iOS +: Podłącz urządzenie do komputera z zainstalowanymi macOS i Xcode. + + Otwórz Xcode i przejdź do Window ▸ Devices and Simulators. + + Wybierz urządzenie z listy, a następnie wybierz odpowiednią aplikację na liście *Installed Apps*. + + Kliknij ikonę koła zębatego pod listą i wybierz Download Container.... + + ![pobierz kontener](images/debugging/download_container.png) + + Po wyodrębnieniu kontenera zostanie on pokazany w *Finder*. Kliknij kontener prawym przyciskiem myszy i wybierz Show Package Content. Znajdź plik "`log.txt`", który powinien znajdować się w "`AppData/Documents/`". + +Android( +: Możliwość wyodrębnienia pliku "`log.txt`" zależy od wersji systemu operacyjnego i producenta urządzenia. Oto krótki i prosty [poradnik krok po kroku](https://stackoverflow.com/a/48077004/]129360). diff --git a/docs/pl/manuals/debugging-game-logic.md b/docs/pl/manuals/debugging-game-logic.md index e1984155..76409c1e 100644 --- a/docs/pl/manuals/debugging-game-logic.md +++ b/docs/pl/manuals/debugging-game-logic.md @@ -1,139 +1,164 @@ --- -title: Debugowanie w Defoldzie -brief: Ta instrukcja wyjaśnia narzędzia do debugowania dostępne w Defoldzie. +title: Debugowanie w Defold +brief: Ta instrukcja wyjaśnia funkcje debugowania dostępne w Defold. --- # Debugowanie logiki gry -Defold zawiera zintegrowany debugger Lua z narzędziem do inspekcji. Razem z wbudowanymi [narzędziami profilowania](/manuals/profiling) stanowi potężne narzędzie, które może pomóc w znalezieniu przyczyny błędów w logice gry lub analizie problemów wydajnościowych. +Defold zawiera zintegrowany debugger Lua z możliwością inspekcji. W połączeniu z wbudowanymi [narzędziami profilowania](/manuals/profiling) jest to potężne narzędzie, które może pomóc znaleźć przyczynę błędów w logice gry albo przeanalizować problemy z wydajnością. -## Debugowanie za pomocą wydruków i wizualne +## Debugowanie za pomocą print i wizualne -Najprostszym sposobem debugowania w Defold jest korzystanie z [debugowania za pomocą wydruków](http://en.wikipedia.org/wiki/Debugging#Techniques). Używaj funkcji `print()` lub [`pprint()`](/ref/builtins#pprint) do monitorowania zmiennych lub wskazywania przepływu wykonania. Jeśli obiekt gry bez skryptu działa dziwnie, możesz dołączyć do niego skrypt wyłącznie w celu debugowania. Korzystanie z dowolnej z funkcji drukowania spowoduje wydruk na panelu *Console* (konsola) w Edytorze oraz w [logach gry](/manuals/debugging-game-and-system-logs). - -Oprócz drukowania/wyświetlania, silnik może również rysować teksty debugowania i proste linie na ekranie. To jest realizowane poprzez przesyłanie wiadomości do gniazda (socket) `@render`: +Najprostszym sposobem debugowania gry w Defold jest [debugowanie za pomocą print](http://en.wikipedia.org/wiki/Debugging#Techniques). Używaj instrukcji `print()` lub [`pprint()`](/ref/builtins#pprint), aby obserwować zmienne lub wskazywać przepływ wykonania. Jeśli obiekt gry bez skryptu zachowuje się dziwnie, możesz po prostu dołączyć do niego skrypt wyłącznie do debugowania. Korzystanie z dowolnej z funkcji wypisywania spowoduje wyświetlenie wyniku w widoku *Console* w edytorze oraz w [logach gry](/manuals/debugging-game-and-system-logs). +Oprócz wypisywania, silnik może też rysować na ekranie tekst debugowania i proste linie. Robi się to przez wysyłanie wiadomości do socketu `@render`: ```lua --- Draw value of "my_val" with debug text on the screen +-- Narysuj na ekranie wartość "my_val" jako tekst debugowania msg.post("@render:", "draw_text", { text = "My value: " .. my_val, position = vmath.vector3(200, 200, 0) }) --- Draw colored text on the screen +-- Narysuj na ekranie kolorowy tekst local color_green = vmath.vector4(0, 1, 0, 1) msg.post("@render:", "draw_debug_text", { text = "Custom color", position = vmath.vector3(200, 180, 0), color = color_green }) --- Draw debug line between player and enemy on the screen +-- Narysuj na ekranie linię debugowania między playerem a enemy local start_p = go.get_position("player") local end_p = go.get_position("enemy") local color_red = vmath.vector4(1, 0, 0, 1) msg.post("@render:", "draw_line", { start_point = start_p, end_point = end_p, color = color_red }) ``` -Wizualne komunikaty debugowania dodają dane do potoku (pipeline) renderowania i są rysowane jako część standardowego potoku renderowania, czyli wyświetlane. -* `"draw_line"` dodaje dane, które są renderowane za pomocą funkcji `render.draw_debug3d()` w skrypcie renderowania (render script). -* `"draw_text"` jest renderowany z użyciem `"/builtins/fonts/system_font.font"`, który wykorzystuje materiał `"/builtins/fonts/system_font.material"`. -* `"draw_debug_text"` jest to to samo co `"draw_text"`, ale jest renderowany w kolorze niestandardowym. -Zauważ, że prawdopodobnie chcesz aktualizować te dane co klatkę, więc przesyłanie wiadomości do skryptu renderowania w funkcji `update()` jest dobrym pomysłem. +Wizualne wiadomości debugowania dodają dane do potoku renderowania i są rysowane jako część zwykłego potoku renderowania. + +* `"draw_line"` dodaje dane renderowane przez funkcję `render.draw_debug3d()` w skrypcie do renderowania. +* `"draw_text"` jest renderowany przy użyciu `/builtins/fonts/debug/always_on_top.font`, który korzysta z materiału `/builtins/fonts/debug/always_on_top_font.material`. +* `"draw_debug_text"` jest tym samym co `"draw_text"`, ale jest renderowany w niestandardowym kolorze. -## Uruchamianie debuggera +Pamiętaj, że prawdopodobnie chcesz aktualizować te dane co klatkę, więc wysyłanie tych wiadomości w funkcji `update()` jest dobrym pomysłem. -Aby uruchomić wbudowany debugger wraz z grą klkinij menu Debug ▸ Run with Debugger lub wybierz Debug ▸ Attach Debugger, aby dołączyć debugger do aktualnie uruchomionej gry. +## Uruchamianie debugera + +Aby uruchomić debuger, wybierz Debug ▸ Start/Attach. To polecenie uruchomi grę z dołączonym debugerem albo dołączy debuger do już uruchomionej gry. ![overview](images/debugging/overview.png) -Gdy debugger jest podłączony, masz kontrolę nad wykonaniem gry za pomocą przycisków sterowania debugerem w konsoli lub za pomocą menu Debug: +Gdy tylko debuger zostanie dołączony, możesz sterować wykonaniem gry za pomocą przycisków sterowania debugerem w konsoli albo przez menu Debug: Break : ![pause](images/debugging/pause.svg){width=60px .left} - Natychmiastowa przerwa wykonania gry. Gra zostanie zatrzymana w bieżącym punkcie. Teraz można sprawdzić stan gry, przejść do przodu krok po kroku lub kontynuować jej działanie do kolejnego punktu przerwania (breakpoint). Aktualny punkt wykonania jest oznaczony w edytorze kodu: + Natychmiast wstrzymuje wykonanie gry. Gra zatrzyma się w bieżącym punkcie. Możesz teraz sprawdzić stan gry, wykonywać ją krok po kroku albo kontynuować działanie do następnego punktu przerwania. Bieżący punkt wykonania jest oznaczony w edytorze kodu: ![script](images/debugging/script.png) Continue : ![play](images/debugging/play.svg){width=60px .left} - Kontynuuj działanie gry. Kod gry będzie kontynuował działanie, aż naciśniesz pauzę lub wykonanie dojdzie do ustawionego punktu przerwania (breakpoint). Jeśli wykonanie zostanie przerwane na ustawionym punkcie przerwania, punkt wykonania jest oznaczony w edytorze kodu na szczycie znacznika punktu przerwania: + Kontynuuje wykonywanie gry. Kod gry będzie działał dalej, dopóki nie naciśniesz pauzy albo wykonanie nie trafi w ustawiony punkt przerwania. Jeśli wykonanie zostanie zatrzymane na punkcie przerwania, punkt wykonania jest oznaczony w edytorze kodu nad znacznikiem breakpointa: ![break](images/debugging/break.png) Stop : ![stop](images/debugging/stop.svg){width=60px .left} - Stop the debugger. Pressing this button will immediately stop the debugger, detach it from the game and terminate the running game. + Zatrzymuje debuger. Naciśnięcie tego przycisku natychmiast zatrzyma debuger, odłączy go od gry i zakończy uruchomioną grę. Step Over : ![step over](images/debugging/step_over.svg){width=60px .left} - Przesuń wykonanie programu o jeden krok. Jeśli wykonanie obejmuje uruchomienie innego skryptu Lua, wykonanie *nie* wejdzie do funkcji , ale będzie kontynuować działanie i zatrzyma się na kolejnej linii poniżej wywołania funkcji. W tym przykładzie, jeśli użytkownik naciśnie "Step Over", debugger wykonuje kod i zatrzymuje się na instrukcji `end` poniżej linii z wywołaniem funkcji `nextspawn()`: + Przechodzi o jeden krok dalej. Jeśli wykonanie obejmuje uruchomienie innej funkcji Lua, debuger nie wejdzie do tej funkcji, tylko będzie kontynuował działanie i zatrzyma się na następnej linii poniżej wywołania funkcji. W tym przykładzie, jeśli użytkownik naciśnie "step over", debuger wykona kod i zatrzyma się na instrukcji `end` poniżej linii z wywołaniem funkcji `nextspawn()`: ![step](images/debugging/step.png) ::: sidenote -Jedna linia kodu Lua nie odpowiada jednemu wyrażeniu. Krok w debuggerze przesuwa się o jedno wyrażenie naraz, co oznacza, że obecnie możesz musieć nacisnąć przycisk kroku więcej niż raz, aby przejść do następnej linii. +Jedna linia kodu Lua nie odpowiada jednemu wyrażeniu. Przechodzenie w debuggerze odbywa się po jednym wyrażeniu naraz, więc obecnie może być konieczne naciśnięcie przycisku kroku więcej niż raz, aby przejść do następnej linii. ::: Step Into : ![step in](images/debugging/step_in.svg){width=60px .left} - Przesuń wykonanie programu o jeden krok. Jeśli wykonanie obejmuje uruchomienie innej funkcji Lua, wykonanie wejdzie do funkcji. Wywołanie funkcji dodaje wpis na stosie wywołań. Możesz kliknąć każdy wpis na liście stosu wywołań, aby wyświetlić punkt wejścia i zawartość wszystkich zmiennych w tej zamknięciu. Tutaj użytkownik wszedł do funkcji `nextspawn()`: + Przechodzi o jeden krok dalej. Jeśli wykonanie obejmuje uruchomienie innej funkcji Lua, debuger wejdzie do tej funkcji. Wywołanie funkcji dodaje wpis na stosie wywołań. Możesz kliknąć każdy wpis na liście stosu wywołań, aby zobaczyć punkt wejścia i zawartość wszystkich zmiennych w tym domknięciu. W tym przykładzie użytkownik wszedł do funkcji `nextspawn()`: ![step into](images/debugging/step_into.png) Step Out : ![step out](images/debugging/step_out.svg){width=60px .left} - Kontynuuj działanie do momentu zakończenia bieżącej funkcji. Jeśli wykonanie jest w funkcji, naciśnięcie przycisku "Step Out" spowoduje kontynuowanie działania do momentu zakończenia funkcji. - + Kontynuuje wykonywanie do momentu powrotu z bieżącej funkcji. Jeśli wszedłeś do funkcji podczas debugowania, naciśnięcie przycisku "step out" będzie kontynuować wykonanie aż do momentu zwrócenia przez funkcję. -Ustawianie i usuwanie punktów przerwania (breakpoints) -: Możesz ustawić dowolną liczbę punktów przerwania w kodzie Lua. Gdy gra działa z podłączonym debugerem, zatrzyma się na następnym punkcie przerwania i poczeka na dalsze interakcje z tobą. +Ustawianie i usuwanie breakpointów +: Możesz ustawić dowolną liczbę breakpointów w kodzie Lua. Gdy gra działa z dołączonym debugerem, zatrzyma się na następnym napotkanym breakpointcie i poczeka na dalszą interakcję z twojej strony. ![add breakpoint](images/debugging/add_breakpoint.png) - Aby ustawić lub usunąć punkt przerwania, kliknij w kolumnie tuż po prawej stronie numerów wierszy w edytorze kodu. Możesz także wybrać opcję Edit ▸ Toggle Breakpoint z menu. + Aby ustawić lub usunąć breakpoint, kliknij w kolumnie bezpośrednio po prawej stronie numerów linii w edytorze kodu. Możesz też wybrać Edit ▸ Toggle Breakpoint z menu. -Ustawianie punktów przerwania warunkowych -: Możesz skonfigurować punkt przerwania tak, aby zawierał warunek, który musi być spełniony, aby punkt przerwania został uruchomiony. Warunek może uzyskiwać dostęp do zmiennych lokalnych dostępnych w danym momencie wykonania kodu. +Wyłączanie i włączanie breakpointów +: Breakpointy można tymczasowo wyłączyć bez ich usuwania. Gdy są wyłączone, są ignorowane podczas wykonywania, ale można je włączyć ponownie w dowolnym momencie. Kliknij je prawym przyciskiem myszy w marginesie edytora kodu, a następnie przełącz pole wyboru Enabled. Wyłączone breakpointy są pokazane jako puste, aby zaznaczyć, że są nieaktywne. + + ![disable breakpoint](images/debugging/disable_breakpoint.png) + +Ustawianie breakpointów warunkowych +: Możesz skonfigurować breakpoint tak, aby zawierał warunek, który musi zostać spełniony, żeby breakpoint został wyzwolony. Warunek może korzystać z lokalnych zmiennych dostępnych w danym wierszu podczas wykonywania kodu. ![edit breakpoint](images/debugging/edit_breakpoint.png) - Aby edytować warunek punktu przerwania, kliknij prawym przyciskiem myszy w kolumnie tuż po prawej stronie numerów wierszy w edytorze kodu lub wybierz opcję Edit ▸ Edit Breakpoint z menu. + Aby edytować warunek breakpointa, kliknij prawym przyciskiem myszy w kolumnie bezpośrednio po prawej stronie numerów linii w edytorze kodu albo wybierz Edit ▸ Edit Breakpoint z menu. -Wykonywanie wyrażeń Lua -: Z podłączonym debuggerem i zatrzymaną grą na punkcie przerwania dostępna jest przestrzeń wykonawcza Lua z bieżącym kontekstem. Wpisz wyrażenia Lua na dole konsoli i naciśnij Enter, aby je wykonać: +Obliczanie wyrażeń Lua +: Gdy debuger jest dołączony, a gra zatrzymana na breakpointcie, dostępne jest środowisko wykonawcze Lua z bieżącym kontekstem. Wpisz wyrażenia Lua na dole konsoli i naciśnij Enter, aby je ocenić: ![console](images/debugging/console.png) Obecnie nie można modyfikować zmiennych za pomocą ewaluatora. -Odłączanie debuggera -: Wybierz Debug ▸ Detach Debugger, aby odłączyć debuggera od gry. Gra zostanie natychmiast wznowiona. +Odłączanie debugera +: Wybierz Debug ▸ Detach Debugger, aby odłączyć debuger od gry. Gra będzie natychmiast kontynuowana. + +## Karta Breakpoints + + ![breakpoints tab](images/debugging/breakpoints_tab.png) + + Podczas pracy z wieloma breakpointami w różnych skryptach karta Breakpoints zapewnia scentralizowany widok do zarządzania wszystkimi breakpointami w jednym miejscu. + +##### Sterowanie pojedynczym breakpointem + + Do pracy z pojedynczymi breakpointami: + - Kliknij czerwoną ikonę kosza, aby usunąć breakpoint + - Kliknij dwukrotnie wiersz poza obszarem warunku, aby przejść do tej linii w widoku kodu + - Kliknij dwukrotnie komórkę warunku albo kliknij ikonę pióra, aby edytować breakpointy warunkowe + - Kliknij przycisk czyszczenia `X`, gdy najedziesz na komórkę warunku, aby wyczyścić warunek + +##### Operacje zbiorcze + + Zaznacz wiele breakpointów za pomocą Ctrl/Cmd+klik lub Shift+klik, a następnie kliknij prawym przyciskiem myszy, aby wykonać operacje zbiorcze. Możesz jednocześnie edytować warunki kilku breakpointów, przełączać ich stan aktywności albo usuwać je całkowicie. + + Przyciski na pasku narzędzi pozwalają włączyć, wyłączyć lub przełączyć wszystkie breakpointy naraz, co jest przydatne, gdy chcesz uruchomić grę bez zatrzymywania, ale nie chcesz stracić ich położeń. Możesz też usunąć wszystkie, gdy skończysz sesję debugowania. ## Biblioteka debugowania Lua -Lua zawiera bibliotekę debugowania przydatną w niektórych sytuacjach, szczególnie jeśli potrzebujesz zbadać wewnętrzne aspekty swojego środowiska Lua. Więcej informacji na ten temat znajdziesz [tutaj](http://www.lua.org/pil/contents.html#23). +Lua zawiera bibliotekę debugowania, która bywa przydatna w niektórych sytuacjach, szczególnie gdy trzeba zajrzeć do wnętrza środowiska Lua. Więcej informacji znajdziesz w [rozdziale o bibliotece debugowania (Debug Library) w podręczniku Lua](http://www.lua.org/pil/contents.html#23). ## Lista kontrolna debugowania -Jeśli napotkasz błąd lub gra nie działa zgodnie z oczekiwaniami, oto lista kontrolna debugowania: +Jeśli napotkasz błąd albo gra nie zachowuje się zgodnie z oczekiwaniami, skorzystaj z poniższej listy kontrolnej debugowania: -1. Sprawdź wyświetlenia w konsoli (Console) i zweryfikuj, czy nie ma błędów czasu wykonania. +1. Sprawdź zawartość konsoli i upewnij się, że nie ma błędów wykonania. -2. Dodaj instrukcje `print` do swojego kodu, aby sprawdzić, czy kod faktycznie się wykonuje. +2. Dodaj do kodu instrukcje print, aby potwierdzić, że kod rzeczywiście się wykonuje. -3. Jeśli kod nie jest wykonywany, sprawdź, czy w edytorze została dokonana właściwa konfiguracja niezbędna do uruchomienia kodu. Czy skrypt został dodany do odpowiedniego obiektu gry? Czy skrypt uzyskał focus wejścia (acquired input focus), jeśli chcesz obsługiwać wejścia sterowania? Czy wejścia są zdefiniowane poprawnie? Czy kod shadera został dodany do materiału? I tak dalej. +3. Jeśli kod się nie wykonuje, sprawdź, czy w edytorze wykonano wszystkie wymagane czynności konfiguracyjne. Czy skrypt został dodany do właściwego obiektu gry? Czy skrypt przechwycił fokus wejścia? Czy wyzwalacze wejścia są poprawne? Czy kod shadera został dodany do materiału? I tak dalej. -4. Jeśli twój kod zależy od wartości zmiennych (na przykład w instrukcji warunkowej), użyj instrukcji `print` w miejscach, gdzie są używane lub sprawdzane, lub zbadaj je za pomocą debuggera. +4. Jeśli kod zależy od wartości zmiennych, na przykład w instrukcji `if`, wypisz te wartości tam, gdzie są używane lub sprawdzane, albo zbadaj je za pomocą debugera. -Czasem znalezienie błędu może być trudnym i czasochłonnym procesem, który wymaga przeglądania kodu kawałek po kawałku, sprawdzania wszystkiego i zawężania błędnego kodu oraz eliminowania źródeł błędów. Najlepiej jest to robić za pomocą metody "dziel i rządź": +Czasami znalezienie błędu jest trudnym i czasochłonnym procesem, który wymaga przechodzenia przez kod krok po kroku, sprawdzania wszystkiego, zawężania obszaru błędu i eliminowania źródeł problemu. Najlepiej zrobić to metodą „dziel i rządź”: -1. Znajdź połowę (lub mniej) kodu, który podejrzewasz, że może zawierać błąd. -2. Ponownie znajdź połowę, z tej połowy, która musi zawierać błąd. -3. Kontynuuj zawężanie kodu, który musi spowodować błąd, aż go znajdziesz. +1. Ustal, która połowa kodu, albo mniejsza część, musi zawierać błąd. +2. Ponownie ustal, która połowa z tej połowy musi zawierać błąd. +3. Kontynuuj zawężanie kodu, który musi powodować błąd, aż go znajdziesz. -Udanego polowania! +Powodzenia w poszukiwaniach! -## Rozwiązywanie problemów z fizyką +## Debugowanie problemów z fizyką -Jeśli masz problemy z fizyką i kolizje nie działają zgodnie z oczekiwaniami, zaleca się włączenie debugowania fizyki. Zaznacz pole wyboru *"Debug"* w sekcji *"Physics"* pliku `"game.project"`: +Jeśli masz problemy z fizyką i kolizje nie działają zgodnie z oczekiwaniami, zaleca się włączenie debugowania fizyki. Zaznacz pole wyboru *Debug* w sekcji *Physics* pliku *game.project*: ![physics debug setting](images/debugging/physics_debug_setting.png) -Gdy to pole jest zaznaczone, Defold będzie rysował wszystkie kształty kolizji i punkty kontaktu kolizji: +Gdy to pole wyboru jest zaznaczone, Defold będzie rysować wszystkie kształty kolizji i punkty kontaktu kolizji: -![physics debug visualisation](images/debugging/physics_debug_visualisation.png) +![physics debug visualization](images/debugging/physics_debug_visualisation.png) diff --git a/docs/pl/manuals/debugging-native-code-android.md b/docs/pl/manuals/debugging-native-code-android.md new file mode 100644 index 00000000..657c7baf --- /dev/null +++ b/docs/pl/manuals/debugging-native-code-android.md @@ -0,0 +1,85 @@ +--- +title: Debugowanie na Androidzie +brief: Ta instrukcja opisuje, jak debugować zbudowaną aplikację za pomocą Android Studio. +--- + +# Debugowanie na Androidzie + +Tutaj opisujemy, jak debugować zbudowaną aplikację za pomocą [Android Studio](https://developer.android.com/studio/), oficjalnego IDE dla systemu operacyjnego Android firmy Google. + + +## Android Studio + +* Przygotuj pakiet, ustawiając opcję `android.debuggable` w pliku *game.project* + + ![android.debuggable](images/extensions/debugging/android/game_project_debuggable.png) + +* Zbuduj pakiet aplikacji w trybie debug i zapisz go w wybranym folderze. + + ![bundle_android](images/extensions/debugging/android/bundle_android.png) + +* Uruchom [Android Studio](https://developer.android.com/studio/) + +* Wybierz Profile or debug APK + + ![debug_apk](images/extensions/debugging/android/android_profile_or_debug.png) + +* Wybierz utworzony przed chwilą pakiet APK + + ![select_apk](images/extensions/debugging/android/android_select_apk.png) + +* Wybierz główny plik `.so` i upewnij się, że zawiera symbole debugowania + + ![select_so](images/extensions/debugging/android/android_missing_symbols.png) + +* Jeśli ich nie ma, wczytaj nieokrojony plik `.so` (`unstripped`). (rozmiar to około 20 MB) + +* Mapowania ścieżek (ang. path mappings) pozwalają powiązać poszczególne ścieżki zapisane podczas budowania pliku wykonywalnego (w chmurze) z rzeczywistymi folderami na dysku lokalnym. + +* Wybierz plik `.so`, a następnie dodaj mapowanie do folderu na swoim dysku lokalnym + + ![path_mapping1](images/extensions/debugging/android/path_mappings_android.png) + + ![path_mapping2](images/extensions/debugging/android/path_mappings_android2.png) + +* Jeśli masz dostęp do kodu źródłowego silnika, dodaj mapowanie ścieżki również do niego. + +* Upewnij się, że lokalne źródła są przełączone na dokładnie tę wersję, którą obecnie debugujesz + + defold$ git checkout 1.2.148 + +* Naciśnij Apply changes + +* Powinieneś teraz widzieć zmapowany kod źródłowy w projekcie + + ![source](images/extensions/debugging/android/source_mappings_android.png) + +* Dodaj punkt przerwania + + ![breakpoint](images/extensions/debugging/android/breakpoint_android.png) + +* Naciśnij Run -> Debug "Appname" i wywołaj kod, w którym chcesz przerwać wykonywanie + + ![breakpoint](images/extensions/debugging/android/callstack_variables_android.png) + +* Możesz teraz przechodzić po stosie wywołań i sprawdzać wartości zmiennych + + +## Uwagi + +### Folder zadania rozszerzenia natywnego (Native Extension) + +Obecnie ta procedura jest nieco uciążliwa podczas prac rozwojowych. Wynika to z tego, że nazwa folderu zadania +jest losowa przy każdym budowaniu, przez co mapowanie ścieżek staje się za każdym razem nieprawidłowe. + +Mimo to działa poprawnie w ramach pojedynczej sesji debugowania. + +Mapowania ścieżek są przechowywane w pliku projektu `.iml` w projekcie Android Studio. + +Nazwę folderu zadania można odczytać z pliku wykonywalnego + +```sh +$ arm-linux-androideabi-readelf --string-dump=.debug_str build/armv7-android/libdmengine.so | grep /job +``` + +Folder zadania ma nazwę w rodzaju `job1298751322870374150`, za każdym razem z losowym numerem. diff --git a/docs/pl/manuals/debugging-native-code-ios.md b/docs/pl/manuals/debugging-native-code-ios.md new file mode 100644 index 00000000..09d6da05 --- /dev/null +++ b/docs/pl/manuals/debugging-native-code-ios.md @@ -0,0 +1,154 @@ +--- +title: Debugowanie na iOS/macOS +brief: Ta instrukcja opisuje, jak debugować build za pomocą Xcode. +--- + +# Debugowanie na iOS/macOS + +Tutaj opisujemy, jak debugować kompilację za pomocą [Xcode](https://developer.apple.com/xcode/), preferowanego przez Apple środowiska IDE do tworzenia aplikacji na macOS i iOS. + +## Xcode + +* Zbuduj pakiet aplikacji za pomocą bob, używając opcji `--with-symbols` ([więcej informacji](/manuals/debugging-native-code/#symbolicate-a-callstack)): + +```sh +$ cd myproject +$ wget http://d.defold.com/archive//bob/bob.jar +$ java -jar bob.jar --platform armv7-darwin build --with-symbols --variant debug --archive bundle -bo build/ios -mp .mobileprovision --identity "iPhone Developer: Your Name (ID)" +``` + +* Zainstaluj aplikację za pomocą `Xcode`, `iTunes` albo [ios-deploy](https://github.com/ios-control/ios-deploy) + +```sh +$ ios-deploy -b .ipa +``` + +* Pobierz folder `.dSYM` (czyli symbole debugowania) + + * Jeśli projekt nie używa rozszerzeń natywnych (Native Extensions), możesz pobrać plik `.dSYM` z [d.defold.com](http://d.defold.com) + + * Jeśli używasz rozszerzenia natywnego, folder `.dSYM` jest generowany podczas budowania za pomocą [bob.jar](https://www.defold.com/manuals/bob/). Wystarczy samo zbudowanie projektu, bez archiwizacji ani bundlowania: + +```sh +$ cd myproject +$ unzip .internal/cache/arm64-ios/build.zip +$ mv dmengine.dSYM .dSYM +$ mv .dSYM/Contents/Resources/DWARF/dmengine .dSYM/Contents/Resources/DWARF/ +``` + +### Tworzenie projektu + +Aby poprawnie debugować, potrzebujemy projektu oraz zmapowanego kodu źródłowego. +Nie używamy tego projektu do budowania, a jedynie do debugowania. + +* Utwórz nowy projekt Xcode i wybierz szablon Game + + ![project_template](images/extensions/debugging/ios/project_template.png) + +* Wybierz nazwę (np. `debug`) i ustawienia domyślne + +* Wybierz folder, w którym chcesz zapisać projekt + +* Dodaj swój kod do aplikacji + + ![add_files](images/extensions/debugging/ios/add_files.png) + +* Upewnij się, że opcja Copy items if needed jest odznaczona. + + ![add_source](images/extensions/debugging/ios/add_source.png) + +* Oto efekt końcowy + + ![added_source](images/extensions/debugging/ios/added_source.png) + + +* Wyłącz krok Build + + ![edit_scheme](images/extensions/debugging/ios/edit_scheme.png) + + ![disable_build](images/extensions/debugging/ios/disable_build.png) + +* Ustaw wersję Deployment target tak, aby była większa niż wersja iOS na Twoim urządzeniu + + ![deployment_version](images/extensions/debugging/ios/deployment_version.png) + +* Wybierz urządzenie docelowe + + ![select_device](images/extensions/debugging/ios/select_device.png) + + +### Uruchamianie debuggera + +Masz kilka opcji debugowania aplikacji: + +1. Wybierz Debug -> Attach to process... i wybierz z listy aplikację + +2. Albo wybierz Attach to process by PID or Process name + + ![select_device](images/extensions/debugging/ios/attach_to_process_name.png) + +3. Uruchom aplikację na urządzeniu + +4. W Edit Scheme dodaj folder .app jako plik wykonywalny + +### Symbole debugowania + +**Aby użyć lldb, wykonanie musi być wstrzymane** + +* Dodaj ścieżkę `.dSYM` do lldb + +``` +(lldb) add-dsym +``` + + ![add_dsym](images/extensions/debugging/ios/add_dsym.png) + +* Sprawdź, czy `lldb` poprawnie wczytał symbole + +``` +(lldb) image list +``` + +### Mapowania ścieżek + +* Dodaj kod źródłowy silnika (zmień odpowiednio do własnych potrzeb) + +``` +(lldb) settings set target.source-map /Users/builder/ci/builds/engine-ios-64-master/build /Users/mathiaswesterdahl/work/defold +(lldb) settings append target.source-map /private/var/folders/m5/bcw7ykhd6vq9lwjzq1mkp8j00000gn/T/job4836347589046353012/upload/videoplayer/src /Users/mathiaswesterdahl/work/projects/extension-videoplayer-native/videoplayer/src +``` + +* Folder zadania można ustalić na podstawie pliku wykonywalnego. Ten folder ma nazwę `job1298751322870374150` i za każdym razem zawiera losowy numer. + +```sh +$ dsymutil -dump-debug-map 2>&1 >/dev/null | grep /job + +``` + +* Sprawdź mapowania źródeł + +``` +(lldb) settings show target.source-map +``` + +Możesz sprawdzić, z którego pliku źródłowego pochodzi symbol, używając: + +``` +(lldb) image lookup -va +``` + +### Punkty przerwania + +* Otwórz plik w widoku projektu i ustaw punkt przerwania + + ![breakpoint](images/extensions/debugging/ios/breakpoint.png) + +## Uwagi + +### Sprawdzenie UUID pliku binarnego + +Aby debugger zaakceptował folder `.dSYM`, UUID musi odpowiadać UUID debugowanego pliku wykonywalnego. Możesz sprawdzić UUID w ten sposób: + +```sh +$ dwarfdump -u +``` diff --git a/docs/pl/manuals/debugging-native-code.md b/docs/pl/manuals/debugging-native-code.md new file mode 100644 index 00000000..f6ae50fd --- /dev/null +++ b/docs/pl/manuals/debugging-native-code.md @@ -0,0 +1,161 @@ +--- +title: Debugowanie kodu natywnego w Defold +brief: Ta instrukcja wyjaśnia, jak debugować kod natywny w Defold. +--- + +# Debugowanie kodu natywnego + +Defold jest dobrze przetestowany i w normalnych warunkach bardzo rzadko powinien się zawieszać. Nie da się jednak zagwarantować, że nigdy nie dojdzie do awarii, zwłaszcza jeśli Twoja gra korzysta z native extensions. Jeśli napotkasz problemy z awariami albo kod natywny nie zachowuje się tak, jak powinien, możesz pójść kilkoma różnymi drogami: + +* użyć debuggera i prześledzić kod krok po kroku +* użyć debugowania przez wypisywanie +* przeanalizować log awarii +* zsymbolikować stos wywołań + + +## Użyj debuggera + +Najczęściej uruchamia się kod w `debuggerze`. Pozwala on przechodzić przez kod krok po kroku, ustawiać punkty przerwania (`breakpoints`) i zatrzymać wykonanie, jeśli dojdzie do awarii. + +Istnieje kilka debuggerów dla każdej platformy. + +* Visual Studio - Windows +* VSCode - Windows, macOS, Linux +* Android Studio - Windows, macOS, Linux +* Xcode - macOS +* WinDBG - Windows +* lldb / gdb - macOS, Linux, (Windows) +* ios-deploy - macOS + +Każde z tych narzędzi może debugować określone platformy: + +* Visual Studio - Windows + platformy obsługujące gdbserver (np. Linux/Android) +* VSCode - Windows, macOS (lldb), Linux (lldb/gdb) + platformy obsługujące gdbserver +* Xcode - macOS, iOS ([więcej informacji](/manuals/debugging-native-code-ios)) +* Android Studio - Android ([więcej informacji](/manuals/debugging-native-code-android)) +* WinDBG - Windows +* lldb/gdb - macOS, Linux, (iOS) +* ios-deploy - iOS (przez lldb) + + +## Użyj debugowania przez wypisywanie + +Najprostszym sposobem debugowania kodu natywnego jest [debugowanie przez wypisywanie](http://en.wikipedia.org/wiki/Debugging#Techniques). Użyj funkcji z przestrzeni nazw [`dmLog`](/ref/stable/dmLog/), aby obserwować zmienne albo zaznaczać przebieg wykonania. Każda z funkcji logujących wypisze dane do widoku *Console* w edytorze oraz do [logu gry](/manuals/debugging-game-and-system-logs). + + +## Przeanalizuj log awarii + +Silnik Defold zapisuje plik `_crash`, jeśli dojdzie do poważnej awarii. Plik awarii zawiera informacje o systemie oraz o samej awarii. [Wyjście logu gry](/manuals/debugging-game-and-system-logs) zapisze, gdzie znajduje się plik awarii (lokalizacja zależy od systemu operacyjnego, urządzenia i aplikacji). + +Możesz użyć [modułu crash](https://www.defold.com/ref/crash/), aby odczytać ten plik w następnej sesji. Zaleca się odczytać plik, zebrać informacje, wypisać je do konsoli i wysłać do [usługi analitycznej](/tags/stars/analytics/), która obsługuje zbieranie logów awarii. + +::: important +W systemie Windows generowany jest również plik `_crash.dmp`. Ten plik jest przydatny podczas debugowania awarii. +::: + +### Pobieranie logu awarii z urządzenia + +Jeśli awaria wystąpi na urządzeniu mobilnym, możesz pobrać plik awarii na własny komputer i przeanalizować go lokalnie. + +#### Android + +Jeśli aplikacja jest [debuggable](/manuals/project-settings/#android), możesz pobrać log awarii za pomocą narzędzia [Android Debug Bridge (ADB)](https://developer.android.com/studio/command-line/adb.html) i polecenia `adb shell`: + +``` +$ adb shell "run-as com.defold.example sh -c 'cat /data/data/com.defold.example/files/_crash'" > ./_crash +``` + +#### iOS + +W iTunes możesz wyświetlić lub pobrać kontener aplikacji. + +W oknie Xcode ▸ Devices możesz też wybrać logi awarii z menu `Xcode -> Devices`. + + +## Zsymbolikuj stos wywołań + +Jeśli uzyskasz stos wywołań z pliku `_crash` albo z [pliku logu](/manuals/debugging-game-and-system-logs), możesz go zsymbolikować. Oznacza to przetłumaczenie każdego adresu w stosie wywołań na nazwę pliku i numer linii, co z kolei pomaga ustalić główną przyczynę problemu. + +Bardzo ważne jest, aby dopasować właściwy silnik do stosu wywołań, w przeciwnym razie możesz zacząć debugować zupełnie niewłaściwe rzeczy. Użyj flagi [`--with-symbols`](https://www.defold.com/manuals/bob/) podczas bundlowania za pomocą [bob](https://www.defold.com/manuals/bob/) albo zaznacz Generate debug symbols w oknie bundlowania w edytorze: + +* iOS - folder `dmengine.dSYM.zip` w `build/arm64-ios` zawiera symbole debugowe dla buildów iOS. +* macOS - folder `dmengine.dSYM.zip` w `build/x86_64-macos` zawiera symbole debugowe dla buildów macOS. +* Android - katalog wyjściowy bundla `projecttitle.apk.symbols/lib/` zawiera symbole debugowe dla docelowych architektur. +* Linux - plik wykonywalny zawiera symbole debugowe. +* Windows - plik `dmengine.pdb` w `build/x86_64-win32` zawiera symbole debugowe dla buildów Windows. +* HTML5 - plik `dmengine.js.symbols` w `build/js-web` lub `build/wasm-web` zawiera symbole debugowe dla buildów HTML5. + +::: important +Bardzo ważne jest, aby zachować symbole debugowe dla każdego publicznego wydania gry i wiedzieć, do którego wydania należą. Bez symboli debugowych nie da się debugować natywnych awarii. Warto też zachować wersję silnika bez stripowania. Umożliwia to najlepszą możliwą symbolikację stosu wywołań. +::: + + +### Przesyłanie symboli do Google Play +Możesz [przesłać symbole debugowe do Google Play](https://developer.android.com/studio/build/shrink-code#android_gradle_plugin_version_40_or_earlier_and_other_build_systems), aby wszystkie awarie zarejestrowane w Google Play pokazywały zsymbolikowane stosy wywołań. Spakuj do ZIP-a zawartość katalogu wyjściowego bundla `projecttitle.apk.symbols/lib/`. Katalog zawiera jeden lub więcej podkatalogów o nazwach architektur, takich jak `arm64-v8a` i `armeabi-v7a`. + + +### Zsymbolikuj stos wywołań z Androida + +1. Pobierz silnik z katalogu buildu + +```sh + $ ls /build//[lib]dmengine[.exe|.so] +``` + +2. Rozpakuj go do katalogu: + +```sh + $ unzip dmengine.apk -d dmengine_1_2_105 +``` + +3. Znajdź adres ze stosu wywołań + + Na przykład w niezsymbolikowanym stosie wywołań może to wyglądać tak: + + `#00 pc 00257224 libmy_game_name.so` + + Gdzie *`00257224`* jest adresem + +4. Rozwiąż adres + +```sh + $ arm-linux-androideabi-addr2line -C -f -e dmengine_1_2_105/lib/armeabi-v7a/libdmengine.so _address_ +``` + +Uwaga: jeśli zdobędziesz ślad stosu z [logów Androida](/manuals/debugging-game-and-system-logs), być może uda się go zsymbolikować za pomocą [ndk-stack](https://developer.android.com/ndk/guides/ndk-stack.html) + +### Zsymbolikuj stos wywołań z iOS + +1. Jeśli używasz Native Extensions, serwer może dostarczyć symbole (.dSYM) (przekaż `--with-symbols` do `bob.jar`) + +```sh + $ unzip /build/arm64-darwin/build.zip + # spowoduje to utworzenie Contents/Resources/DWARF/dmengine +``` + +2. Jeśli nie używasz Native Extensions, pobierz standardowe symbole: + +```sh + $ wget http://d.defold.com/archive//engine/arm64-darwin/dmengine.dSYM +``` + +3. Zsymbolikuj, używając adresu załadowania + + Z jakiegoś powodu samo podanie adresu ze stosu wywołań nie działa (tj. adres załadowania 0x0) + +```sh + $ atos -arch arm64 -o Contents/Resources/DWARF/dmengine 0x1492c4 +``` + + # Nie działa też podanie adresu załadowania bezpośrednio + +```sh + $ atos -arch arm64 -o MyApp.dSYM/Contents/Resources/DWARF/MyApp -l0x100000000 0x1492c4 +``` + + Dodanie adresu załadowania do adresu działa: + +```sh + $ atos -arch arm64 -o MyApp.dSYM/Contents/Resources/DWARF/MyApp 0x1001492c4 + dmCrash::OnCrash(int) (in MyApp) (backtrace_execinfo.cpp:27) +``` diff --git a/docs/pl/manuals/debugging.md b/docs/pl/manuals/debugging.md new file mode 100644 index 00000000..f5f1152a --- /dev/null +++ b/docs/pl/manuals/debugging.md @@ -0,0 +1,11 @@ +--- +title: Debugowanie w silniku Defold +brief: Ta instrukcja wyjaśnia dostępne w silniku Defold możliwości debugowania. +--- + +# Debugowanie + +Defold zawiera zintegrowany debugger Lua z możliwością inspekcji. Razem z wbudowanymi [narzędziami profilowania](/manuals/profiling) stanowi potężne narzędzie, które może pomóc w znalezieniu przyczyny błędów w logice gry lub w analizie problemów z wydajnością. Defold udostępnia również logi awarii na te rzadkie sytuacje, gdy sam silnik ulegnie awarii. + +* Dowiedz się więcej o [debugowaniu logiki gry](/manuals/debugging-game-logic). +* Dowiedz się więcej o [debugowaniu kodu natywnego](/manuals/debugging-native-code). diff --git a/docs/pl/manuals/design.md b/docs/pl/manuals/design.md new file mode 100644 index 00000000..52b4bf34 --- /dev/null +++ b/docs/pl/manuals/design.md @@ -0,0 +1,24 @@ +--- +title: Założenia projektowe Defold +brief: Filozofia stojąca za założeniami projektowymi Defold. +--- + +# Założenia projektowe Defold + +Defold powstał z myślą o następujących celach: + +- Ma być kompletną, profesjonalną platformą produkcyjną, czyli gotowym rozwiązaniem dla zespołów tworzących gry. +- Ma być prosty i przejrzysty oraz dostarczać jednoznacznych rozwiązań typowych problemów architektonicznych i organizacyjnych występujących podczas tworzenia gier. +- Ma być bardzo szybką platformą deweloperską, idealną do iteracyjnego tworzenia gier. +- Ma zapewniać wysoką wydajność w czasie działania. +- Ma być naprawdę wieloplatformowy. + +Projekt edytora i silnika został starannie dopracowany tak, aby osiągnąć te cele. Niektóre z naszych decyzji projektowych różnią się od tego, do czego możesz być przyzwyczajony, jeśli masz doświadczenie z innymi platformami. Na przykład: + +- Wymagamy statycznego deklarowania drzewa zasobów oraz całego nazewnictwa. Wymaga to od Ciebie pewnego początkowego wysiłku, ale w dłuższej perspektywie bardzo usprawnia proces tworzenia. +- Zachęcamy do przekazywania wiadomości między prostymi, zamkniętymi w sobie jednostkami. +- Nie ma dziedziczenia zorientowanego obiektowo. +- Nasze API są asynchroniczne. +- Potok renderowania (ang. rendering pipeline) jest sterowany kodem i w pełni konfigurowalny. +- Wszystkie pliki zasobów mają proste, tekstowe formaty, optymalnie przygotowane zarówno do scalania w Git, jak i do importu oraz przetwarzania za pomocą zewnętrznych narzędzi. +- Zasoby można zmieniać i szybko przeładowywać (ang. hot reload) w działającej grze, co pozwala na niezwykle szybkie iterowanie i eksperymentowanie. diff --git a/docs/pl/manuals/dev-app.md b/docs/pl/manuals/dev-app.md new file mode 100644 index 00000000..d783b799 --- /dev/null +++ b/docs/pl/manuals/dev-app.md @@ -0,0 +1,67 @@ +--- +title: Uruchamianie development app na urządzeniu +brief: Ta instrukcja wyjaśnia, jak zainstalować development app na urządzeniu, aby wygodnie rozwijać projekt iteracyjnie bezpośrednio na nim. +--- + +# Mobilna development app + +Development app (aplikacja do tworzenia i testowania gry na urządzeniu) pozwala przesyłać do niej zawartość przez Wi-Fi. Dzięki temu znacznie skraca się czas iteracji, bo nie trzeba za każdym razem budować i instalować aplikacji, gdy chcesz sprawdzić zmiany. Instalujesz development app na urządzeniu lub urządzeniach, uruchamiasz ją, a potem wybierasz urządzenie jako cel budowania w edytorze. + +## Instalowanie development app + +Każda aplikacja na iOS lub Androidzie zbudowana w wariancie Debug może działać jako development app. To zalecane rozwiązanie, ponieważ taka development app ma poprawne ustawienia projektu i korzysta z tych samych [rozszerzeń natywnych](/manuals/extensions/) co projekt, nad którym pracujesz. + +Od wersji Defold 1.4.0 można zbudować wariant Debug projektu bez żadnej zawartości. Użyj tej opcji, aby utworzyć wersję aplikacji z rozszerzeniami natywnymi, odpowiednią do iteracyjnego tworzenia i testowania opisanego w tej instrukcji. + +![paczka bez zawartości](images/dev-app/contentless-bundle.png) + +### Instalowanie na iOS + +Postępuj zgodnie z [instrukcjami w podręczniku iOS](/manuals/ios/#creating-an-ios-application-bundle), aby utworzyć paczkę dla iOS. Upewnij się, że wybierasz wariant Debug! + +### Instalowanie na Androidzie + +Postępuj zgodnie z [instrukcjami w podręczniku Android](https://defold.com/manuals/android/#creating-an-android-application-bundle), aby utworzyć paczkę dla Androida. + +## Uruchamianie gry + +Aby uruchomić grę na urządzeniu, development app i edytor muszą móc połączyć się ze sobą przez tę samą sieć Wi-Fi albo przez USB (zobacz niżej). + +1. Upewnij się, że edytor jest uruchomiony. +2. Uruchom development app na urządzeniu. +3. Wybierz urządzenie w menu Project ▸ Targets w edytorze. +4. Wybierz Project ▸ Build, aby uruchomić grę. Start może chwilę potrwać, ponieważ zawartość gry jest przesyłana strumieniowo na urządzenie przez sieć. +5. Gdy gra działa, możesz jak zwykle korzystać z [szybkiego przeładowania](/manuals/hot-reload/). + +### Łączenie z urządzeniem iOS przez USB w systemie Windows + +Jeśli łączysz się przez USB w systemie Windows z development app działającą na urządzeniu iOS, najpierw musisz [zainstalować iTunes](https://www.apple.com/lae/itunes/download/). Po zainstalowaniu iTunes musisz też [włączyć Personal Hotspot](https://support.apple.com/en-us/HT204023) na urządzeniu iOS w ustawieniach urządzenia. Jeśli zobaczysz alert z pytaniem Trust This Computer?, stuknij Trust. Gdy development app działa, urządzenie powinno teraz pojawić się w menu Project ▸ Targets. + +### Łączenie z urządzeniem iOS przez USB w systemie Linux + +W systemie Linux musisz włączyć Personal Hotspot na urządzeniu w ustawieniach urządzenia, gdy jest ono podłączone przez USB. Jeśli zobaczysz alert z pytaniem Trust This Computer?, stuknij Trust. Gdy development app działa, urządzenie powinno teraz pojawić się w menu Project ▸ Targets. + +### Łączenie z urządzeniem iOS przez USB w systemie macOS + +W nowszych wersjach iOS urządzenie po podłączeniu przez USB do macOS automatycznie otworzy nowy interfejs Ethernet między urządzeniem a komputerem. Gdy development app działa, urządzenie powinno pojawić się w menu Project ▸ Targets. + +W starszych wersjach iOS musisz włączyć Personal Hotspot na urządzeniu w ustawieniach urządzenia, gdy jest ono podłączone przez USB do macOS. Jeśli zobaczysz alert z pytaniem Trust This Computer?, stuknij Trust. Gdy development app działa, urządzenie powinno teraz pojawić się w menu Project ▸ Targets. + +### Łączenie z urządzeniem Android przez USB w systemie macOS + +W macOS można połączyć się przez USB z działającą development app na urządzeniu Android, gdy na urządzeniu jest włączony tryb USB Tethering. W macOS trzeba zainstalować sterownik zewnętrzny, taki jak [HoRNDIS](https://joshuawise.com/horndis#available_versions). Po zainstalowaniu HoRNDIS trzeba też zezwolić mu na działanie w ustawieniach Security & Privacy. Gdy USB Tethering jest włączone, urządzenie pojawi się w menu Project ▸ Targets, jeśli development app działa. + +### Łączenie z urządzeniem Android przez USB w systemie Windows lub Linux + +W systemach Windows i Linux można połączyć się przez USB z działającą development app na urządzeniu Android, gdy na urządzeniu jest włączony tryb USB Tethering. Gdy USB Tethering jest włączone, urządzenie pojawi się w menu Project ▸ Targets, jeśli development app działa. + +## Rozwiązywanie problemów + +Nie można pobrać aplikacji (Unable to download application) +: Upewnij się, że UDID urządzenia znajduje się w profilu provisioning użytym do podpisania aplikacji. + +Urządzenie nie pojawia się w menu Project ▸ Targets +: Upewnij się, że urządzenie jest połączone z tą samą siecią Wi-Fi co komputer. Upewnij się też, że development app została zbudowana w wariancie Debug. + +Gra nie uruchamia się i pojawia się komunikat o niezgodnych wersjach +: Dzieje się tak, gdy zaktualizujesz edytor do najnowszej wersji. Musisz zbudować i zainstalować nową wersję. diff --git a/docs/pl/manuals/editor-keyboard-shortcuts.md b/docs/pl/manuals/editor-keyboard-shortcuts.md deleted file mode 100644 index 6305d8b2..00000000 --- a/docs/pl/manuals/editor-keyboard-shortcuts.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Skróty klawiszowe Edytora -brief: Ta instrukcja pokazuje obecne skróty klawiszowe Edytora Defold i jak je zmodyfikować. ---- - -# Skróty klawiszowe Edytora - -## Domyślne skróty klawiszowe Edytora - -Nazwy komend nie są przetłumaczone ze względu na użycie ich oryginalnych nazw z Edytora. Pamiętaj, że różne komendy działają w różnych kontekstach. - -| Komenda | Windows | macOS | Linux | -|---------|---------|-------|-------| -| Add | A | A | A | -| Add secondary | Shift+A | Shift+A | Shift+A | -| Backwards tab trigger | Shift+Tab | Shift+Tab | Shift+Tab | -| Beginning of file | Ctrl+Home | Cmd+Up | Ctrl+Home | -| Beginning of line | | Ctrl+A | | -| Beginning of line text | Home | Home | Home | -| Build | Ctrl+B | Cmd+B | Ctrl+B | -| Close | Ctrl+W | Cmd+W | Ctrl+W | -| Close all | Shift+Ctrl+W | Shift+Cmd+W | Shift+Ctrl+W | -| Continue | F5 | F5 | F5 | -| Copy | Ctrl+C | Cmd+C | Ctrl+C | -| Cut | Ctrl+X | Cmd+X | Ctrl+X | -| Delete | Delete | Delete | Delete | -| Delete backward | Backspace | Backspace | Backspace | -| Delete line | | Ctrl+D | | -| Delete next word | Ctrl+Delete | Alt+Delete | Ctrl+Delete | -| Delete prev word | Ctrl+Backspace | Alt+Backspace | Ctrl+Backspace | -| Delete to end of line | Shift+Ctrl+Delete | Cmd+Delete | Shift+Ctrl+Delete | -| Documentation | F1 | F1 | F1 | -| Down | Down | Down | Down | -| Edit breakpoint | Alt+F9 | Alt+F9 | Alt+F9 | -| End of file | Ctrl+End | Cmd+Down | Ctrl+End | -| End of line | End | Ctrl+E | End | -| Enter | Enter | Enter | Enter | -| Erase tool | Shift+E | Shift+E | Shift+E | -| Escape | Esc | Esc | Esc | -| Find next | Ctrl+G, Enter | Cmd+G, Enter | Ctrl+G, Enter | -| Find prev | Shift+Ctrl+G, Shift+Enter | Shift+Cmd+G, Shift+Enter | Shift+Ctrl+G, Shift+Enter | -| Find references | Shift+F12 | Shift+F12 | Shift+F12 | -| Find text | Ctrl+F | Cmd+F | Ctrl+F | -| Frame selection | F | F | F | -| Goto definition | F12 | F12 | F12 | -| Goto line | Ctrl+L | Cmd+L | Ctrl+L | -| Hide selected | Ctrl+E | Cmd+E | Ctrl+E | -| Hot reload | Ctrl+R | Cmd+R | Ctrl+R | -| Left | Left | Left | Left | -| Move down | Alt+Down | Alt+Down | Alt+Down | -| Move tool | W | W | W | -| Move up | Alt+Up | Alt+Up | Alt+Up | -| New file | Ctrl+N | Cmd+N | Ctrl+N | -| Next word | Ctrl+Right | Alt+Right | Ctrl+Right | -| Open | Ctrl+O | Cmd+O | Ctrl+O | -| Open asset | Shift+Ctrl+R | Cmd+P | Shift+Ctrl+R | -| Page down | Page Down | Page Down | Page Down | -| Page up | Page Up | Page Up | Page Up | -| Paste | Ctrl+V | Cmd+V | Ctrl+V | -| Preferences | Ctrl+Comma | Cmd+Comma | Ctrl+Comma | -| Prev word | Ctrl+Left | Alt+Left | Ctrl+Left | -| Proposals | Ctrl+Space | Ctrl+Space | Ctrl+Space | -| Quit | Ctrl+Q | Cmd+Q | Ctrl+Q | -| Realign camera | Period | Period | Period | -| Rebuild | Shift+Ctrl+B | Shift+Cmd+B | Shift+Ctrl+B | -| Rebundle | Ctrl+U | Cmd+U | Ctrl+U | -| Recent files | Alt+R | Ctrl+R | Alt+R | -| Redo | Shift+Ctrl+Z | Shift+Cmd+Z | Shift+Ctrl+Z | -| Reindent | Ctrl+I | Ctrl+I | Ctrl+I | -| Rename | F2 | F2 | F2 | -| Reopen closed file | Shift+Ctrl+T | Shift+Cmd+T | Shift+Ctrl+T | -| Replace next | Shift+Ctrl+H | Alt+Cmd+G | Shift+Ctrl+H | -| Replace text | | Alt+Cmd+F | | -| Right | Right | Right | Right | -| Rotate tool | E | E | E | -| Save all | Ctrl+S | Cmd+S | Ctrl+S | -| Scale tool | R | R | R | -| Scene stop | Ctrl+T | Cmd+T | Ctrl+T | -| Search in files | Shift+Ctrl+F | Shift+Cmd+F | Shift+Ctrl+F | -| Select all | Ctrl+A | Cmd+A | Ctrl+A | -| Select beginning of file | Shift+Ctrl+Home | Shift+Cmd+Up | Shift+Ctrl+Home | -| Select beginning of line | | Shift+Ctrl+A | | -| Select beginning of line text | Shift+Home | Shift+Home | Shift+Home | -| Select down | Shift+Down | Shift+Down | Shift+Down | -| Select end of file | Shift+Ctrl+End | Shift+Cmd+Down | Shift+Ctrl+End | -| Select end of line | Shift+End | Shift+Alt+Down | Shift+End | -| Select left | Shift+Left | Shift+Left | Shift+Left | -| Select next occurrence | Ctrl+D | Cmd+D | Ctrl+D | -| Select next word | Shift+Ctrl+Right | Shift+Alt+Right | Shift+Ctrl+Right | -| Select page down | Shift+Page Down | Shift+Page Down | Shift+Page Down | -| Select page up | Shift+Page Up | Shift+Page Up | Shift+Page Up | -| Select prev word | Shift+Ctrl+Left | Shift+Ctrl+Left | Shift+Ctrl+Left | -| Select right | Shift+Right | Shift+Right | Shift+Right | -| Show last hidden | Shift+Ctrl+E | Shift+Cmd+E | Shift+Ctrl+E | -| Show palette | Space | Space | Space | -| Split selection into lines | Shift+Ctrl+L | Shift+Cmd+L | Shift+Ctrl+L | -| Step into | F11 | F11 | F11 | -| Step out | Shift+F11 | Shift+F11 | Shift+F11 | -| Step over | F10 | F10 | F10 | -| Stop debugger | Shift+F5 | | Shift+F5 | -| Switch to next tab | Ctrl+Tab | Ctrl+Tab | Ctrl+Tab | -| Switch to previous tab | Shift+Ctrl+Tab | Shift+Ctrl+Tab | Shift+Ctrl+Tab | -| Tab | Tab | Tab | Tab | -| Toggle breakpoint | F9 | F9 | F9 | -| Toggle comment | Ctrl+Slash | Cmd+Slash | Ctrl+Slash | -| Toggle component guides | Ctrl+H | Ctrl+Cmd+H | Ctrl+H | -| Toggle pane bottom | F7 | F7 | F7 | -| Toggle pane left | F6 | F6 | F6 | -| Toggle pane right | F8 | F8 | F8 | -| Toggle visibility filters | Shift+Ctrl+I | Shift+Cmd+I | Shift+Ctrl+I | -| Undo | Ctrl+Z | Cmd+Z | Ctrl+Z | -| Up | Up | Up | Up | -| Up major | Shift+Up | Shift+Up | Shift+Up | -| Zoom in | Ctrl+'+' | Cmd+'+' | Ctrl+'+' | -| Zoom out | Ctrl+'-' | Cmd+'-' | Ctrl+'-' | - - -## Modyfikowanie skrótów klawiszowych - -Możesz dowolnie zmodyfikować skróty klawiszowe tworząc plik konfiguracyjny (np. `keymap.edn` w katalogu domowym). Następnie wybierz File ▸ Preferences i ustaw Path to Custom Keymap wpisując ścieżkę do stworzonego pliku. Musisz uruchomić ponownie Edytor po tym ustawieniu i za każdym razem kiedy zmieniasz zawartość pliku konfiguracyjnego, aby nowe zmiany działały. - -![custom keymap](images/editor/preferences_general.png) - -Domyślne pliki konfiguracyjne są do pobrania dla danych systemów: [Windows](examples/keymap_win.edn), [MacOS](examples/keymap_macos.edn) i [Linux](examples/keymap_linux.edn) diff --git a/docs/pl/manuals/editor-preferences.md b/docs/pl/manuals/editor-preferences.md index ff3bf4d9..fe2027b3 100644 --- a/docs/pl/manuals/editor-preferences.md +++ b/docs/pl/manuals/editor-preferences.md @@ -1,83 +1,111 @@ --- -title: Preferencje Edytora -brief: Ta instrukcja przedstawia co oznaczają i jak zmodyfikować Preferencje Edytora. +title: Preferencje edytora +brief: Możesz zmieniać ustawienia edytora w oknie Preferences. --- -# Preferencje Edytora +# Preferencje edytora -Możesz dostosować ustawienia Edytora z poziomu okna Preferencji. Okno Preferencji otwiera się z menu File -> Preferences. +Możesz zmieniać ustawienia edytora w oknie Preferences. Okno otwierasz z menu File -> Preferences. -## General (Ogólne) +## General ![](images/editor/preferences_general.png) -Load External Changes on App Focus (Wczytaj zewnętrzne zmiany po aktywowaniu aplikacji) -: Umożliwia skanowanie zewnętrznych zmian, gdy Edytor zostaje aktywnie wybrany w systemie. +Load External Changes on App Focus +: Włącza wyszukiwanie zmian zewnętrznych, gdy edytor odzyskuje fokus. -Open Bundle Target Folder (Otwórz folder docelowy pakietu) -: Umożliwia otwarcie folderu docelowego pakietu po zakończeniu procesu pakowania. +Open Bundle Target Folder +: Włącza otwieranie folderu docelowego bundla po zakończeniu procesu bundlowania. -Enable Texture Compression (Włącz kompresję tekstur) -: Umożliwia kompresję tekstur dla wszystkich kompilacji utworzonych z Edytora. +Enable Texture Compression +: Włącza [kompresję tekstur](/manuals/texture-profiles) dla wszystkich buildów tworzonych z edytora. -Escape Quits Game (Klawisz Escape zamyka grę) -: Zatrzymuje działającą kompilację twojej gry za pomocą klawisza Esc. +Escape Quits Game +: Zamyka uruchomiony build gry po naciśnięciu Esc. -Track Active Tab in Asset Browser (Śledź aktywną kartę w przeglądarce zasobów) -: Plik edytowany na wybranej karcie w panelu Edytor zostanie zaznaczony w Przeglądarce Zasobów (znanej również jako panel *Assets*). +Track Active Tab in Asset Browser +: Plik edytowany na wybranej karcie w panelu *Editor* zostanie zaznaczony w Asset Browser, znanym też jako panel *Asset*. -Path to custom keymap (Ścieżka do niestandardowej mapy klawiszy) -: Absolutna ścieżka do pliku zawierającego niestandardowe skróty klawiaturowe. +Lint Code on Build +: Włącza [lintowanie kodu](/manuals/writing-code/#linting-configuration) podczas budowania projektu. Ta opcja jest włączona domyślnie, ale można ją wyłączyć, jeśli lintowanie w dużym projekcie trwa zbyt długo. -## Code (Kod) +Engine Arguments +: Argumenty przekazywane do pliku wykonywalnego dmengine, gdy edytor buduje i uruchamia projekt. + Używaj jednego argumentu na linię. Na przykład: + ``` +--config=bootstrap.main_collection=/my dir/1.collectionc +--verbose +--graphics-adapter=vulkan +``` + +## Code ![](images/editor/preferences_code.png) -Custom Editor (Niestandardowy Edytor) -: Absolutna ścieżka do zewnętrznego Edytora. Na macOS powinna to być ścieżka do pliku wykonywalnego wewnątrz .app (np. `/Applications/Atom.app/Contents/MacOS/Atom`). +Custom Editor +: Bezwzględna ścieżka do zewnętrznego edytora. Na macOS powinna to być ścieżka do pliku wykonywalnego wewnątrz .app, na przykład `/Applications/Atom.app/Contents/MacOS/Atom`. + +Open File +: Wzorzec używany przez zewnętrzny edytor do wskazania pliku, który ma zostać otwarty. Wzorzec `{file}` zostanie zastąpiony nazwą pliku do otwarcia. -Open File (Otwórz plik) -: Wzorzec używany przez niestandardowy Edytor do określenia, który plik ma być otwarty. Wzorzec `{file}` zostanie zastąpiony nazwą pliku do otwarcia. +Open File at Line +: Wzorzec używany przez zewnętrzny edytor do wskazania pliku i numeru linii. Wzorzec `{file}` zostanie zastąpiony nazwą pliku do otwarcia, a `{line}` numerem linii. -Open File at Line (Otwórz plik w linii) -: Wzorzec używany przez niestandardowy edytor do określenia, który plik ma być otwarty i na której linii. Wzorzec `{file}` zostanie zastąpiony nazwą pliku do otwarcia, a `{line}` numerem linii. +Code editor font +: Nazwa czcionki zainstalowanej w systemie, której używa edytor kodu. -Code editor font (Czcionka edytora kodu) -: Nazwa zainstalowanej systemowej czcionki do użycia w edytorze kodu. +Zoom on Scroll +: Określa, czy podczas przewijania w edytorze kodu z wciśniętym przyciskiem Cmd/Ctrl ma się zmieniać rozmiar czcionki. -### Otwieranie plików skryptów w programie Visual Studio Code +### Otwieranie plików skryptów w Visual Studio Code ![](images/editor/preferences_vscode.png) -Aby otworzyć pliki skryptów bezpośrednio z Edytora Defold w programie Microsoft Visual Studio Code, musisz ustawić następujące ustawienia, określając ścieżkę do pliku wykonywalnego: +Aby otwierać pliki skryptów z Defold Editor bezpośrednio w Visual Studio Code, ustaw poniższe wartości, podając ścieżkę do pliku wykonywalnego: -- macOS: /Applications/Visual Studio Code.app/Contents/MacOS/Electron -- Linux: /usr/bin/code -- Windows: C:\Program Files\Microsoft VS Code\Code.exe +- MacOS: `/Applications/Visual Studio Code.app/Contents/MacOS/Electron` +- Linux: `/usr/bin/code` +- Windows: `C:\Program Files\Microsoft VS Code\Code.exe` Ustaw te parametry, aby otwierać konkretne pliki i linie: - Open File: `. {file}` - Open File at Line: `. -g {file}:{line}` -Znak . jest wymagany, aby otworzyć cały workspace, a nie pojedynczy plik. +Znak `.` jest tutaj wymagany, aby otworzyć cały obszar roboczy, a nie pojedynczy plik. -## Rozszerzenia +## Extensions ![](images/editor/preferences_extensions.png) -Serwer budowania (Build Server) -: URL serwera budowania używanego podczas kompilacji projektu zawierającego rozszerzenia natywne (native extensions). Możliwe jest dodanie nazwy użytkownika i tokena dostępowego do URL w celu autoryzowanego dostępu do serwera budowania. Aby określić nazwę użytkownika (username) i token dostępowy, użyj następującej notacji: `username:token@build.defold.com`. Autoryzowany dostęp jest wymagany dla kompilacji na platformę Nintendo Switch oraz w przypadku uruchamiania własnej instancji serwera kompilacji z włączoną autoryzacją (dokładne informacje znajdziesz w [dokumentacji serwera budowania](https://github.com/defold/extender/blob/dev/README_SECURITY.md). Nazwę użytkownika i hasło można także ustawić jako zmienne środowiskowe systemu `DM_EXTENDER_USERNAME` i `DM_EXTENDER_PASSWORD`. +Build Server +: Adres URL serwera buildów używanego podczas budowania projektu zawierającego [native extensions](/manuals/extensions). Możesz dodać do adresu URL nazwę użytkownika i token dostępu, aby korzystać z uwierzytelnionego dostępu do serwera buildów. Użyj zapisu `username:token@build.defold.com`. Uwierzytelniony dostęp jest wymagany przy buildach dla Nintendo Switch oraz podczas korzystania z własnej instancji build servera z włączonym uwierzytelnianiem ([zobacz dokumentację build servera](https://github.com/defold/extender/blob/dev/README_SECURITY.md), aby uzyskać więcej informacji). Nazwę użytkownika i hasło można też ustawić jako zmienne środowiskowe `DM_EXTENDER_USERNAME` i `DM_EXTENDER_PASSWORD`. + +Build Server Username +: Nazwa użytkownika do uwierzytelniania. + +Build Server Password +: Hasło do uwierzytelniania. Zostanie zapisane w pliku preferencji w postaci zaszyfrowanej. -Nagłówki serwera budowania -: dodatkowe nagłówki serwera budowania przy budowaniu rozszerzeń natywnych. Jest to ważne, jeśli korzystasz z usługi CloudFlare lub podobnych usług z extenderem. +Build Server Headers +: Dodatkowe nagłówki wysyłane do build servera podczas budowania native extensions. Jest to ważne przy korzystaniu z CloudFlare lub podobnych usług razem z extenderem. -## Narzędzia +## Tools ![](images/editor/preferences_tools.png) -Ścieżka ADB -: Ścieżka do narzędzia linii komend [ADB](https://developer.android.com/tools/adb) zainstalowanego na tym systemie. Jeśli masz zainstalowane ADB na swoim systemie, edytor Defold użyje go do instalacji i uruchamiania spakowanych plików APK na połączonym urządzeniu z systemem Android. Domyślnie edytor sprawdza, czy ADB jest zainstalowane w znanych lokalizacjach, więc musisz podać ścieżkę tylko wtedy, gdy masz zainstalowane ADB w niestandardowym miejscu. +ADB path +: Ścieżka do narzędzia wiersza poleceń [ADB](https://developer.android.com/tools/adb) zainstalowanego w tym systemie. Jeśli ADB jest zainstalowane, edytor Defold użyje go do instalowania i uruchamiania zbudowanych APK na podłączonym urządzeniu z Androidem. Domyślnie edytor sprawdza znane lokalizacje, więc ścieżkę trzeba podać tylko wtedy, gdy ADB jest zainstalowane w niestandardowym miejscu. + +ios-deploy path +: Ścieżka do narzędzi wiersza poleceń [ios-deploy](https://github.com/ios-control/ios-deploy) zainstalowanych w tym systemie. Dotyczy to tylko macOS. Podobnie jak w przypadku ścieżki ADB, edytor Defold użyje tego narzędzia do instalowania i uruchamiania zbundlowanych aplikacji iOS na podłączonym iPhonie. Domyślnie edytor sprawdza znane lokalizacje, więc ścieżkę trzeba podać tylko wtedy, gdy korzystasz z niestandardowej instalacji ios-deploy. + +## Keymap + +![](images/editor/preferences_keymap.png) + +Możesz konfigurować skróty edytora, zarówno dodając własne, jak i usuwając wbudowane. Aby edytować skrót, użyj menu kontekstowego przy wybranym poleceniu w tabeli skrótów albo kliknij je dwukrotnie lub naciśnij Enter, aby otworzyć okno dodawania nowego skrótu. -Ścieżka ios-deploy -: Ścieżka do narzędzi linii komend ios-deploy zainstalowanych na tym systemie (dotyczy tylko macOS). Podobnie jak w przypadku ścieżki ADB, edytor Defold będzie używać tego narzędzia do instalacji i uruchamiania spakowanych aplikacji iOS na połączonym iPhone. Domyślnie edytor sprawdza, czy ios-deploy jest zainstalowane w znanych lokalizacjach, więc musisz podać ścieżkę tylko wtedy, gdy korzystasz z niestandardowej lokalizacji własnej instalacji ios-deploy. +Przy niektórych skrótach mogą pojawić się ostrzeżenia, wyświetlane na pomarańczowo. Najedź kursorem na skrót, aby zobaczyć ostrzeżenie. Typowe ostrzeżenia to: +- typeable shortcuts: wybrany skrót można wpisać w polach tekstowych. Upewnij się, że polecenie jest wyłączone w kontekstach edycji kodu i wprowadzania tekstu. +- conflicts: ten sam skrót jest przypisany do wielu różnych poleceń. Upewnij się, że w chwili wywołania skrótu aktywne jest najwyżej jedno z nich, w przeciwnym razie edytor wykona jedno z przypisanych poleceń w nieokreślony sposób. diff --git a/docs/pl/manuals/editor-scripts-ui.md b/docs/pl/manuals/editor-scripts-ui.md new file mode 100644 index 00000000..26e57f7f --- /dev/null +++ b/docs/pl/manuals/editor-scripts-ui.md @@ -0,0 +1,370 @@ +--- +title: "Skrypty edytora: UI" +brief: Ta instrukcja wyjaśnia, jak tworzyć elementy UI w edytorze przy użyciu Lua +--- + +# Skrypty edytora i UI + +Ta instrukcja wyjaśnia, jak tworzyć interaktywne elementy UI w edytorze przy użyciu skryptów edytora napisanych w Lua. Aby zacząć pracę ze skryptami edytora, zobacz [instrukcję skryptów edytora](/manuals/editor-scripts). Pełne API edytora znajdziesz [tutaj](/ref/stable/editor-lua/). Obecnie można tworzyć tylko interaktywne okna dialogowe, chociaż w przyszłości chcemy rozszerzyć obsługę skryptowego UI na resztę edytora. + +## Witaj świecie + +Cała funkcjonalność związana z UI znajduje się w module `editor.ui`. Oto najprostszy przykład skryptu edytora z własnym UI na start: +```lua +local M = {} + +function M.get_commands() + return { + { + label = "Do with confirmation", + locations = {"View"}, + run = function() + local result = editor.ui.show_dialog(editor.ui.dialog({ + title = "Perform action?", + buttons = { + editor.ui.dialog_button({ + text = "Cancel", + cancel = true, + result = false + }), + editor.ui.dialog_button({ + text = "Perform", + default = true, + result = true + }) + } + })) + print('Perform action:', result) + end + } + } +end + +return M + +``` + +Ten fragment kodu definiuje polecenie **View → Do with confirmation**. Gdy je uruchomisz, zobaczysz następujące okno dialogowe: + +![Okno dialogowe przykładu „Witaj świecie”](images/editor_scripts/perform_action_dialog.png) + +Na końcu, po naciśnięciu Enter (albo kliknięciu przycisku `Perform`), w konsoli edytora zobaczysz następujący wiersz: +``` +Perform action: true +``` + +## Podstawowe pojęcia + +### Komponenty + +Edytor udostępnia różne **komponenty** UI, które można składać, aby uzyskać pożądany interfejs. Zgodnie z konwencją wszystkie komponenty są konfigurowane pojedynczą tabelą o nazwie **props**. Same komponenty nie są tabelami, lecz **niezmiennymi userdata** używanymi przez edytor do tworzenia UI. + +### Props + +**Props** to tabele definiujące wejścia komponentów. Należy traktować je jako niezmienne: modyfikowanie tabeli props in-place nie spowoduje ponownego renderowania komponentu, ale użycie innej tabeli już tak. UI jest aktualizowane wtedy, gdy instancja komponentu otrzyma tabelę props, która w płytkim porównaniu nie jest równa poprzedniej. + +### Wyrównanie + +Gdy komponent otrzyma jakiś obszar w UI, zajmie całą dostępną przestrzeń, ale nie oznacza to, że widoczna część komponentu się rozciągnie. Zamiast tego widoczna część zajmie tyle miejsca, ile potrzebuje, a następnie zostanie wyrównana w obrębie przydzielonego obszaru. Dlatego większość wbudowanych komponentów definiuje pole `alignment`. + +Na przykład rozważ ten komponent etykiety: +```lua +editor.ui.label({ + text = "Hello", + alignment = editor.ui.ALIGNMENT.RIGHT +}) +``` +Widoczna część to tekst `Hello`, a w obrębie przydzielonego obszaru komponentu jest on wyrównany tak: + +![Wyrównanie](images/editor_scripts/alignment.png) + +## Wbudowane komponenty + +Edytor definiuje różne wbudowane komponenty, których można używać razem do budowania UI. Komponenty można z grubsza podzielić na 3 kategorie: układ, prezentacja danych i wejście. + +### Komponenty układu + +Komponenty układu służą do umieszczania innych komponentów obok siebie. Główne komponenty układu to **`horizontal`**, **`vertical`** i **`grid`**. Komponenty te definiują też pola takie jak **padding** i **spacing**, gdzie padding oznacza pustą przestrzeń od krawędzi przydzielonego obszaru do zawartości, a spacing pustą przestrzeń między elementami potomnymi: + +![Padding i Spacing](images/editor_scripts/padding_and_spacing.png) + +Edytor definiuje `small`, `medium` i `large` stałe dla paddingu i spacingu. W przypadku spacingu wartość `small` jest przeznaczona do odstępów między różnymi podelementami pojedynczego elementu UI, `medium` do odstępów między poszczególnymi elementami UI, a `large` do odstępów między grupami elementów. Domyślny spacing to `medium`. Dla paddingu wartość `large` oznacza odstęp od krawędzi okna do zawartości, `medium` odstęp od krawędzi istotnego elementu UI, a `small` odstęp od krawędzi małych elementów UI, takich jak menu kontekstowe i podpowiedzi, które nie są jeszcze zaimplementowane. + +Kontener **`horizontal`** umieszcza swoje elementy potomne jeden po drugim w poziomie, zawsze rozciągając wysokość każdego elementu potomnego tak, aby wypełniała dostępną przestrzeń. Domyślnie szerokość każdego elementu potomnego jest utrzymywana na minimalnym poziomie, ale można sprawić, by zajmował tyle miejsca, ile się da, ustawiając w nim pole `grow` na `true`. + +Kontener **`vertical`** jest podobny do horizontal, ale z zamienionymi osiami. + +Na koniec, **`grid`** to komponent kontenera, który układa elementy potomne w dwuwymiarowej siatce, podobnie jak tabela. Ustawienie `grow` w siatce dotyczy wierszy albo kolumn, dlatego ustawia się je nie na elemencie potomnym, ale w tabeli konfiguracji kolumny. Dodatkowo elementy potomne w siatce można skonfigurować tak, aby zajmowały wiele wierszy lub kolumn za pomocą pól `row_span` i `column_span`. Siatki są przydatne przy tworzeniu formularzy z wieloma polami wejściowymi: +```lua +editor.ui.grid({ + padding = editor.ui.PADDING.LARGE, -- dodaj padding wokół krawędzi dialogu + columns = {{}, {grow = true}}, -- spraw, by druga kolumna się rozciągała + children = { + { + editor.ui.label({ + text = "Level Name", + alignment = editor.ui.ALIGNMENT.RIGHT + }), + editor.ui.string_field({}) + }, + { + editor.ui.label({ + text = "Author", + alignment = editor.ui.ALIGNMENT.RIGHT + }), + editor.ui.string_field({}) + } + } +}) +``` +Powyższy kod utworzy następujący formularz w oknie dialogowym: + +![Formularz nowego poziomu](images/editor_scripts/new_level_dialog.png) + +### Komponenty prezentacji danych + +Edytor definiuje 4 komponenty prezentacji danych: +- **`label`** — etykieta tekstowa przeznaczona do używania z polami formularzy. +- **`icon`** — ikona; obecnie można jej używać tylko do prezentowania niewielkiego zestawu predefiniowanych ikon, ale w przyszłości chcemy dopuścić więcej ikon. +- **`heading`** — element tekstowy przeznaczony do wyświetlania wiersza nagłówka, na przykład w formularzu lub oknie dialogowym. Enum `editor.ui.HEADING_STYLE` definiuje różne style nagłówków, w tym nagłówki `H1`-`H6` z HTML-a, a także specyficzne dla edytora `DIALOG` i `FORM`. +- **`paragraph`** — element tekstowy przeznaczony do wyświetlania akapitu tekstu. Główna różnica względem `label` polega na tym, że paragraph obsługuje zawijanie wierszy: jeśli przydzielony obszar jest zbyt wąski, tekst zostanie zawinięty, a jeśli nadal nie zmieści się w widoku, zostanie ewentualnie skrócony do `"..."`. + +### Komponenty wejściowe + +Komponenty wejściowe służą do interakcji użytkownika z UI. Wszystkie komponenty wejściowe obsługują pole `enabled`, które kontroluje, czy interakcja jest włączona, oraz definiują różne callbacki powiadamiające skrypt edytora o interakcji. + +Jeśli tworzysz statyczne UI, wystarczy zdefiniować callbacki, które po prostu modyfikują zmienne lokalne. W przypadku dynamicznych interfejsów i bardziej zaawansowanych interakcji zobacz sekcję [reaktywność](#reactivity). + +Na przykład można tak utworzyć proste, statyczne okno dialogowe tworzenia nowego pliku: +```lua +-- początkowa nazwa pliku, zostanie zastąpiona przez dialog +local file_name = "" +local create_file = editor.ui.show_dialog(editor.ui.dialog({ + title = "Utwórz nowy plik", + content = editor.ui.horizontal({ + padding = editor.ui.PADDING.LARGE, + spacing = editor.ui.SPACING.MEDIUM, + children = { + editor.ui.label({ + text = "Nazwa nowego pliku", + alignment = editor.ui.ALIGNMENT.CENTER + }), + editor.ui.string_field({ + grow = true, + text = file_name, + -- Callback wywoływany podczas wpisywania: + on_value_changed = function(new_text) + file_name = new_text + end + }) + } + }), + buttons = { + editor.ui.dialog_button({ text = "Anuluj", cancel = true, result = false }), + editor.ui.dialog_button({ text = "Utwórz plik", default = true, result = true }) + } +})) +if create_file then + print("create", file_name) +end +``` +Oto lista wbudowanych komponentów wejściowych: +- **`string_field`**, **`integer_field`** i **`number_field`** to warianty jednoliniowego pola tekstowego, które pozwalają edytować odpowiednio łańcuchy znaków, liczby całkowite i liczby. +- **`select_box`** służy do wybierania opcji z predefiniowanej tablicy za pomocą listy rozwijanej. +- **`check_box`** to logiczne pole wejściowe z callbackiem `on_value_changed`. +- **`button`** z callbackiem `on_press`, który jest wywoływany po naciśnięciu przycisku. +- **`external_file_field`** to komponent przeznaczony do wybierania ścieżki do pliku na komputerze. Składa się z pola tekstowego i przycisku otwierającego okno wyboru pliku. +- **`resource_field`** to komponent przeznaczony do wybierania zasobu w projekcie. + +Wszystkie komponenty poza przyciskami pozwalają ustawić pole `issue`, które wyświetla problem powiązany z komponentem, czyli `editor.ui.ISSUE_SEVERITY.ERROR` albo `editor.ui.ISSUE_SEVERITY.WARNING`, na przykład: +```lua +issue = {severity = editor.ui.ISSUE_SEVERITY.WARNING, message = "Ta wartość jest przestarzała"} +``` +Gdy issue jest określone, zmienia wygląd komponentu wejściowego i dodaje podpowiedź z komunikatem problemu. + +Oto demonstracja wszystkich pól wejściowych wraz z ich wariantami issue: + +![Pola wejściowe](images/editor_scripts/inputs_demo.png) + +### Komponenty związane z dialogami + +Aby wyświetlić okno dialogowe, musisz użyć funkcji `editor.ui.show_dialog`. Oczekuje ona komponentu **`dialog`**, który definiuje główną strukturę dialogów Defold: `title`, `header`, `content` i `buttons`. Komponent dialog jest trochę wyjątkowy: nie można użyć go jako elementu potomnego innego komponentu, ponieważ reprezentuje okno, a nie element UI. `header` i `content` są jednak zwykłymi komponentami. + +Przyciski dialogowe też są szczególne: tworzy się je za pomocą komponentu **`dialog_button`**. W odróżnieniu od zwykłych przycisków przyciski dialogowe nie mają callbacku `on_pressed`. Zamiast tego definiują pole `result` z wartością, którą funkcja `editor.ui.show_dialog` zwróci po zamknięciu dialogu. Przyciski dialogowe definiują też logiczne pola `cancel` i `default`: przycisk z polem `cancel` jest uruchamiany, gdy użytkownik naciśnie Escape albo zamknie dialog przyciskiem zamykania systemu operacyjnego, a przycisk `default` jest uruchamiany, gdy użytkownik naciśnie Enter. Przycisk dialogowy może mieć jednocześnie ustawione `cancel` i `default` na `true`. + +### Komponenty pomocnicze + +Dodatkowo edytor definiuje kilka komponentów pomocniczych: +- **`separator`** to cienka linia używana do oddzielania bloków zawartości +- **`scroll`** to komponent opakowujący, który pokazuje paski przewijania, gdy opakowany komponent nie mieści się w przydzielonej przestrzeni + +## Reaktywność + +Ponieważ komponenty są **niezmiennymi userdata**, po ich utworzeniu nie da się ich zmieniać. Jak więc sprawić, żeby UI zmieniało się w czasie? Odpowiedź: **komponenty reaktywne**. + +::: sidenote +UI skryptów edytora czerpie inspirację z biblioteki [React](https://react.dev/), więc wiedza o reaktywnym UI i hookach Reacta będzie pomocna. +::: + +Najprościej mówiąc, komponent reaktywny to komponent z funkcją Lua, która otrzymuje dane (props) i zwraca widok, czyli inny komponent. Funkcja komponentu reaktywnego może używać **hooków**: specjalnych funkcji w module `editor.ui`, które dodają komponentom cechy reaktywne. Zgodnie z konwencją wszystkie hooki mają nazwy zaczynające się od `use_`. + +Aby utworzyć komponent reaktywny, użyj funkcji `editor.ui.component()`. + +Spójrzmy na przykład: okno dialogowe tworzenia nowego pliku, które pozwala utworzyć plik tylko wtedy, gdy wpisana nazwa pliku nie jest pusta: + +```lua +-- 1. dialog jest komponentem reaktywnym +local dialog = editor.ui.component(function(props) + -- 2. komponent definiuje lokalny stan, czyli nazwę pliku, która domyślnie jest pustym ciągiem + local name, set_name = editor.ui.use_state("") + + return editor.ui.dialog({ + title = props.title, + content = editor.ui.vertical({ + padding = editor.ui.PADDING.LARGE, + children = { + editor.ui.string_field({ + value = name, + -- 3. wpisywanie i Enter aktualizują lokalny stan + on_value_changed = set_name + }) + } + }), + buttons = { + editor.ui.dialog_button({ + text = "Anuluj", + cancel = true + }), + editor.ui.dialog_button({ + text = "Utwórz plik", + -- 4. tworzenie jest włączone, gdy nazwa nie jest pusta + enabled = name ~= "", + default = true, + -- 5. wynikiem jest nazwa + result = name + }) + } + }) +end) + +-- 6. show_dialog zwróci albo niepustą nazwę pliku, albo nil po anulowaniu +local file_name = editor.ui.show_dialog(dialog({ title = "Nazwa nowego pliku" })) +if file_name then + print("create " .. file_name) +else + print("cancelled") +end +``` + +Gdy uruchomisz polecenie menu wykonujące ten kod, edytor pokaże na początku dialog z wyłączonym przyciskiem `Create File`, ale gdy wpiszesz nazwę i naciśniesz Enter, przycisk stanie się aktywny: + +![Okno dialogowe tworzenia nowego pliku](images/editor_scripts/reactive_new_file_dialog.png) + +Jak to działa? Przy pierwszym renderowaniu hook `use_state` tworzy lokalny stan powiązany z komponentem i zwraca go wraz z setterem tego stanu. Gdy funkcja settera zostanie wywołana, planuje ponowne renderowanie komponentu. Podczas kolejnych renderowań funkcja komponentu jest wywoływana ponownie, a `use_state` zwraca zaktualizowany stan. Nowy komponent widoku zwrócony przez funkcję komponentu jest następnie porównywany z poprzednim, a UI jest aktualizowane tam, gdzie wykryto zmiany. + +Takie reaktywne podejście bardzo upraszcza budowanie interaktywnych interfejsów i utrzymywanie ich w synchronizacji: zamiast jawnie aktualizować wszystkie dotknięte komponenty UI po danych wejściowych użytkownika, definiujesz widok jako czystą funkcję danych wejściowych (props i stanu lokalnego), a edytor sam obsługuje wszystkie aktualizacje. + +### Zasady reaktywności + +Edytor oczekuje, że reaktywne komponenty funkcyjne będą zachowywać się poprawnie, żeby to działało: + +1. Funkcje komponentów muszą być czyste. Nie ma gwarancji, kiedy ani jak często funkcja komponentu zostanie wywołana. Wszystkie efekty uboczne powinny znajdować się poza renderowaniem, na przykład w callbackach. +2. Props i stan lokalny muszą być niezmienne. Nie mutuj props. Jeśli stan lokalny jest tabelą, nie modyfikuj jej in-place, tylko utwórz nową i przekaż ją do settera, gdy stan ma się zmienić. +3. Funkcje komponentów muszą wywoływać te same hooki w tej samej kolejności przy każdym wywołaniu. Nie wywołuj hooków wewnątrz pętli, w blokach warunkowych, po wcześniejszych return itd. Dobrą praktyką jest wywoływanie hooków na początku funkcji komponentu, przed jakimkolwiek innym kodem. +4. Wywołuj hooki tylko z funkcji komponentów. Hooki działają w kontekście komponentu reaktywnego, dlatego wolno je wywoływać wyłącznie w funkcji komponentu albo w innej funkcji wywoływanej bezpośrednio przez funkcję komponentu. + +### Hooki + +::: sidenote +Jeśli znasz [React](https://react.dev/), zauważysz, że hooki w edytorze mają nieco inną semantykę, jeśli chodzi o zależności hooków. +::: + +Edytor definiuje 2 hooki: **`use_memo`** i **`use_state`**. + +### **`use_state`** + +Lokalny stan można utworzyć na 2 sposoby: z wartością domyślną albo z funkcją inicjalizującą: +```lua +-- wartość domyślna +local enabled, set_enabled = editor.ui.use_state(true) +-- funkcja inicjalizująca + argumenty +local id, set_id = editor.ui.use_state(string.lower, props.name) +``` +Podobnie setter można wywołać z nową wartością albo funkcją aktualizującą: +```lua +-- funkcja aktualizująca +local function increment_by(n, by) + return n + by +end + +local counter = editor.ui.component(function(props) + local count, set_count = editor.ui.use_state(0) + + return editor.ui.horizontal({ + spacing = editor.ui.SPACING.SMALL, + children = { + editor.ui.label({ + text = tostring(count), + alignment = editor.ui.ALIGNMENT.LEFT, + grow = true + }), + editor.ui.text_button({ + text = "+1", + on_pressed = function() set_count(increment_by, 1) end + }), + editor.ui.text_button({ + text = "+5", + on_pressed = function() set_count(increment_by, 5) end + }) + } + }) +end) +``` + +Na koniec stan może zostać **zresetowany**. Dochodzi do tego, gdy zmieni się którykolwiek z argumentów przekazywanych do `editor.ui.use_state()`, sprawdzanych przez `==`. Z tego powodu nie wolno używać literałów tabel ani literałowych funkcji inicjalizujących jako argumentów haka `use_state`, bo spowoduje to reset stanu przy każdym ponownym renderowaniu. Dla zobrazowania: +```lua +-- ❌ ŹLE: literał tabeli w inicjalizatorze powoduje reset stanu przy każdym ponownym renderowaniu +local user, set_user = editor.ui.use_state({ first_name = props.first_name, last_name = props.last_name}) + +-- ✅ DOBRZE: użyj funkcji inicjalizującej poza funkcją komponentu, aby utworzyć stan tabeli +local function create_user(first_name, last_name) + return { first_name = first_name, last_name = last_name} +end +-- ...później, wewnątrz funkcji komponentu: +local user, set_user = editor.ui.use_state(create_user, props.first_name, props.last_name) + + +-- ❌ ŹLE: literał funkcji inicjalizującej powoduje reset stanu przy każdym ponownym renderowaniu +local id, set_id = editor.ui.use_state(function() return string.lower(props.name) end) + +-- ✅ DOBRZE: użyj referencji do funkcji inicjalizującej, aby utworzyć stan +local id, set_id = editor.ui.use_state(string.lower, props.name) +``` + +### **`use_memo`** + +Możesz użyć haka `use_memo`, aby poprawić wydajność. W funkcjach renderujących często wykonuje się pewne obliczenia, na przykład sprawdzanie poprawności danych wejściowych użytkownika. Haka `use_memo` można użyć wtedy, gdy sprawdzenie, czy argumenty funkcji obliczeniowej się zmieniły, jest tańsze niż samo wywołanie tej funkcji. Hak wywoła funkcję obliczeniową przy pierwszym renderowaniu i ponownie wykorzysta obliczoną wartość podczas kolejnych renderowań, jeśli wszystkie argumenty `use_memo` pozostaną bez zmian: +```lua +-- funkcja walidująca poza funkcją komponentu +local function validate_password(password) + if #password < 8 then + return false, "Hasło musi mieć co najmniej 8 znaków." + elseif not password:match("%l") then + return false, "Hasło musi zawierać co najmniej jedną małą literę." + elseif not password:match("%u") then + return false, "Hasło musi zawierać co najmniej jedną wielką literę." + elseif not password:match("%d") then + return false, "Hasło musi zawierać co najmniej jedną cyfrę." + else + return true, "Hasło jest poprawne." + end +end + +-- ...później, wewnątrz funkcji komponentu +local username, set_username = editor.ui.use_state('') +local password, set_password = editor.ui.use_state('') +local valid, message = editor.ui.use_memo(validate_password, password) +``` +W tym przykładzie walidacja hasła wykona się przy każdej zmianie hasła, na przykład podczas wpisywania w polu hasła, ale nie wtedy, gdy zmieni się nazwa użytkownika. + +Innym zastosowaniem haka `use_memo` jest tworzenie callbacków, które są potem używane w komponentach wejściowych, albo sytuacje, gdy lokalnie utworzona funkcja jest używana jako wartość props innego komponentu. To zapobiega niepotrzebnym ponownym renderowaniom. diff --git a/docs/pl/manuals/editor-scripts.md b/docs/pl/manuals/editor-scripts.md index 162e911b..f136aca4 100644 --- a/docs/pl/manuals/editor-scripts.md +++ b/docs/pl/manuals/editor-scripts.md @@ -1,67 +1,93 @@ --- -title: Skrypty Edytora -brief: Ta instrukcja wyjaśnia, jak rozszerzać Edytor za pomocą Lua. +title: Skrypty edytora +brief: Ta instrukcja wyjaśnia, jak rozszerzać edytor Defold przy użyciu Lua. --- -# Skrypty Edytora +# Skrypty edytora -Możesz tworzyć niestandardowe pozycje menu oraz rozszerzać cyklu życia Edytora, używając plików Lua o specjalnym rozszerzeniu: `.editor_script`. Dzięki temu systemowi możesz dostosować dowolnie Edytor, aby zwiększyć swoją wydajność w procesie tworzenia gier. +Możesz tworzyć własne pozycje menu i hooki cyklu życia edytora przy użyciu plików Lua ze specjalnym rozszerzeniem `.editor_script`. Dzięki temu mechanizmowi da się dostosować edytor tak, aby usprawnić własny proces pracy. -## Uruchamianie skryptów Edytora +## Środowisko uruchomieniowe skryptów edytora -Skrypty Edytora (editor scripts) działają wewnątrz Edytora, w maszynie wirtualnej Lua emulowanej przez maszynę wirtualną Java. Wszystkie skrypty współdzielą to samo środowisko, co oznacza, że mogą ze sobą współdziałać. Możesz wymagać (require) modułów Lua, tak samo jak w przypadku plików `.script`, ale wersja Lua uruchamiana wewnątrz Edytora jest inna, więc upewnij się, że twój współdzielony kod jest zgodny. Edytor używa wersji Lua 5.2.x, a dokładniej [silnika luaj](https://github.com/luaj/luaj), który jest obecnie jedynym dostępnym rozwiązaniem do uruchamiania Lua w JVM. Oprócz tego istnieją pewne ograniczenia: -- brak pakietów `debug` i `coroutine`; -- brak funkcji `os.execute` — zapewniamy bardziej przyjazny i bezpieczny sposób wykonywania skryptów powłoki (shell scripts) w sekcji "akcje" - [actions](#actions); -- brak funkcji `os.tmpname` i `io.tmpfile` — obecnie skrypty Edytora mają dostęp tylko do plików wewnątrz katalogu projektu; -- obecnie brak funkcji `os.rename`, choć zamierzamy ją dodać; -- brak funkcji `os.exit` i `os.setlocale`. +Skrypty edytora działają wewnątrz edytora, w maszynie wirtualnej Lua emulowanej przez JVM. Wszystkie skrypty współdzielą jedno środowisko, więc mogą ze sobą współpracować. Możesz używać modułów Lua przez require, podobnie jak w plikach `.script`, ale wersja Lua uruchamiana w edytorze jest inna, dlatego współdzielony kod musi być z nią zgodny. Edytor używa Lua 5.2.x, a dokładniej środowiska [luaj](https://github.com/luaj/luaj), które obecnie jest jedynym sensownym sposobem uruchamiania Lua na JVM. Poza tym obowiązuje kilka ograniczeń: -Wszystkie rozszerzenia Edytora zdefiniowane w skryptach Edytora są ładowane podczas otwierania projektu. Podczas pobierania bibliotek rozszerzenia są ponownie ładowane, ponieważ w bibliotekach, od których zależysz, mogą znajdować się nowe skrypty Edytora. Podczas tego ponownego ładowania nie są wykrywane żadne zmiany w twoich własnych skryptach Edytora, ponieważ mogłeś być w trakcie ich zmian. Aby również je ponownie załadować, musisz uruchomić komendę Project → Reload Editor Scripts (Przeładuj skrypty Edytora). +- nie ma pakietu `debug`; +- nie ma `os.execute`, ale dostępna jest podobna funkcja `editor.execute()`; +- nie ma `os.tmpname` ani `io.tmpfile` — obecnie skrypty edytora mogą uzyskiwać dostęp tylko do plików wewnątrz katalogu projektu; +- obecnie nie ma `os.rename`, choć planujemy je dodać; +- nie ma `os.exit` ani `os.setlocale`; +- w kontekstach, w których edytor potrzebuje natychmiastowej odpowiedzi od skryptu, nie wolno używać niektórych długo działających funkcji; szczegóły znajdziesz w sekcji [Tryby wykonania](#tryby-wykonania). -## Anatomia skryptu `.editor_script` +Wszystkie rozszerzenia edytora zdefiniowane w skryptach edytora są ładowane podczas otwierania projektu. Gdy pobierasz biblioteki, rozszerzenia są przeładowywane, ponieważ w zależnościach mogą pojawić się nowe skrypty edytora. Podczas takiego przeładowania zmiany w twoich własnych skryptach nie są wykrywane, bo możesz być akurat w trakcie ich edycji. Aby przeładować także je, uruchom polecenie **Project → Reload Editor Scripts**. + +## Anatomia pliku `.editor_script` + +Każdy skrypt edytora powinien zwracać moduł, na przykład: -Każdy skrypt Edytora powinien zwracać moduł, na przykład: ```lua local M = {} function M.get_commands() - -- TODO - define editor commands + -- TODO - zdefiniuj polecenia edytora end function M.get_language_servers() - -- TODO - define language servers + -- TODO - zdefiniuj serwery językowe +end + +function M.get_prefs_schema() + -- TODO - zdefiniuj preferencje end return M ``` -Edytor zbiera wszystkie skrypty Edytora zdefiniowane w projekcie i bibliotekach, ładuje je do pojedynczej maszyny Lua i wywołuje je w odpowiednich momentach (więcej na ten temat w sekcjach "komendy": [commands](#commands) i "haki cyklu życia": [lifecycle hooks](#lifecycle-hooks)). - -## Edytor API - -Możesz komunikować się z Edytorem za pomocą pakietu `editor`, który definiuje to API: - -- `editor.platform` — string oznaczający platformę: `"x86_64-win32"` dla systemu Windows, `"x86_64-macos"` dla macOS lub `"x86_64-linux"` dla systemu Linux. -- `editor.version` — string - nazwa wersji Defold, na przykład `"1.4.8"`. -- `editor.engine_sha1` — string - SHA1 silnika Defold. -- `editor.editor_sha1` — string - SHA1 Edytora Defold. -- `editor.get(node_id, property)` — pobierz wartość węzła (node) w Edytorze. Węzły w kontekście Edytora Defold to różne elementy, takie jak pliki skryptów, pliki kolekcji, obiekty gry w kolekcjach, pliki JSON wczytywane jako zasoby itp. `"node_id"` to userdata przekazywane do Skryptu Edytora przez sam Edytor. Możesz również podać ścieżkę zasobu zamiast identyfikatora węzła, na przykład `"/main/game.script"`. `"property"` to string. Obecnie obsługiwane są tylko te właściwości: - - `"path"` — ścieżka pliku od katalogu projektu dla zasobów — elementów, które istnieją jako pliki. Przykład zwracanej wartości: `"/main/game.script"` - - `"text"` — treść tekstowa zasobu edytowalna jako tekst (na przykład pliki skryptów lub pliki JSON). Przykład zwracanej wartości: `"function init(self)\nend"`. Należy zauważyć, że to nie jest to samo co odczytywanie pliku za pomocą `io.open()`, ponieważ możesz edytować plik bez zapisywania go, a te edycje są dostępne tylko podczas dostępu do właściwości `"text"`. - - niektóre właściwości wyświetlane w widoku Properties (Właściwości), gdy coś jest zaznaczone w panelu Outline. Obsługiwane są następujące typy właściwości: - - string - ciągi znaków - - boolean - zmienne logiczne - - number - liczby - - vec2/vec3/vec4 - wektory - - resource - zasoby - -Należy zauważyć, że niektóre z tych właściwości mogą być tylko do odczytu (read-only), a niektóre mogą być niedostępne w różnych kontekstach, więc przed ich odczytaniem powinieneś użyć `editor.can_get`, a przed ich zmianą - `editor.can_set`, które zwrócą informację, czy daną właściwość można odczytać i czy można zmienić i zapisać. Najedź wskaźnikiem myszki na właściwość w panelu Properties (właściwości), żeby zobaczyć tooltop z informacją o jej nazwie w skryptach Edytora. Możesz ustawić właściwości zasobów jako `nil` używając pustej wartości `""`. -- `editor.can_get(node_id, property)` — sprawdź czy można odczytać daną właściwość w danym kontekście. Jeśli tak (true), to `editor.get()` nie zwróci błędu. -- `editor.can_set(node_id, property)` — sprawdź czy można zmienić i zapisać daną właściwość w danym kontekście. Jeśli tak (true), to akcja `"set"` na tej właściwości nie zwróci błędu. - -## Komendy - -Jeśli Skrypt Edytora definiuje funckję `get_commands`, to będzie one wywołana podczas przeładowania rozszerzenia i zwróci komendy możliwe do użycia w Edytorze w pasku menu lub w kontekstowym menu w panelach Assets i Outline. Przykład: +Edytor zbiera wszystkie skrypty edytora zdefiniowane w projekcie i bibliotekach, ładuje je do jednej maszyny Lua i wywołuje wtedy, gdy są potrzebne. Więcej informacji znajdziesz w sekcjach [Polecenia](#commands) i [Hooki cyklu życia](#lifecycle-hooks). + +## API edytora + +Z edytorem możesz komunikować się przez pakiet `editor`, który udostępnia następujące API: + +- `editor.platform` — łańcuch znaków określający platformę: `"x86_64-win32"` dla Windows, `"x86_64-macos"` dla macOS albo `"x86_64-linux"` dla Linux; +- `editor.version` — łańcuch znaków z nazwą wersji Defold, na przykład `"1.4.8"`; +- `editor.engine_sha1` — łańcuch znaków z SHA1 silnika Defold; +- `editor.editor_sha1` — łańcuch znaków z SHA1 edytora Defold; +- `editor.get(node_id, property)` — odczytuje wartość wybranego węzła wewnątrz edytora. Węzły w edytorze to różne byty, na przykład pliki skryptów lub kolekcji, obiekty gry wewnątrz kolekcji, pliki JSON wczytane jako zasoby itd. `node_id` to wartość userdata przekazywana skryptowi przez edytor. Zamiast `node_id` możesz też podać ścieżkę zasobu, na przykład `"/main/game.script"`. `property` to łańcuch znaków. Obecnie obsługiwane są między innymi: + - `"path"` — ścieżka zasobu względem katalogu projektu dla zasobów istniejących jako pliki lub katalogi. Przykładowa wartość: `"/main/game.script"`; + - `"children"` — lista ścieżek zasobów potomnych dla zasobów będących katalogami; + - `"text"` — tekstowa zawartość zasobu edytowalnego jako tekst, na przykład plików skryptów lub JSON. Przykładowa wartość: `"function init(self)\nend"`. To nie jest to samo co odczyt pliku przez `io.open()`, ponieważ plik może być zmieniony, ale jeszcze niezapisany, a takie zmiany są dostępne tylko przez właściwość `"text"`; + - dla atlasów: `images` (lista węzłów obrazów atlasu) oraz `animations` (lista węzłów animacji); + - dla animacji atlasu: `images`; + - dla tilemap: `layers` (lista węzłów warstw tilemapy); + - dla warstw tilemapy: `tiles` (nieograniczona dwuwymiarowa siatka kafelków), więcej w `tilemap.tiles.*`; + - dla `particlefx`: `emitters` (lista węzłów emiterów) i `modifiers` (lista węzłów modyfikatorów); + - dla emiterów `particlefx`: `modifiers`; + - dla obiektów kolizji: `shapes` (lista węzłów kształtów kolizji); + - dla plików GUI: `layers` (lista węzłów warstw); + - część właściwości widocznych w panelu Properties, gdy w Outline coś jest zaznaczone. Obecnie obsługiwane są typy: + - `strings` + - `booleans` + - `numbers` + - `vec2`/`vec3`/`vec4` + - `resources` + - `curves` + Niektóre z tych właściwości mogą być tylko do odczytu albo niedostępne w danym kontekście, dlatego przed odczytem użyj `editor.can_get`, a przed zapisem `editor.can_set`. Po najechaniu kursorem na nazwę właściwości w panelu Properties zobaczysz podpowiedź z nazwą używaną w skryptach edytora. Właściwości zasobów możesz ustawić na `nil`, przekazując `""`. +- `editor.can_get(node_id, property)` — sprawdza, czy odczyt danej właściwości przez `editor.get()` nie zakończy się błędem; +- `editor.can_set(node_id, property)` — sprawdza, czy krok transakcji `editor.tx.set()` dla tej właściwości nie zakończy się błędem; +- `editor.create_directory(resource_path)` — tworzy katalog, jeśli nie istnieje, wraz z brakującymi katalogami nadrzędnymi; +- `editor.create_resources(resources)` — tworzy co najmniej jeden zasób, z szablonów albo z własną zawartością; +- `editor.delete_directory(resource_path)` — usuwa katalog, jeśli istnieje, wraz z istniejącymi podkatalogami i plikami; +- `editor.execute(cmd, [...args], [options])` — uruchamia polecenie powłoki, opcjonalnie przechwytując jego wynik; +- `editor.save()` — zapisuje wszystkie niezapisane zmiany na dysk; +- `editor.transact(txs)` — modyfikuje stan edytora w pamięci przy użyciu jednego lub wielu kroków transakcji utworzonych przez `editor.tx.*`; +- `editor.ui.*` — funkcje związane z interfejsem; szczegóły w [instrukcji UI](/manuals/editor-scripts-ui); +- `editor.prefs.*` — funkcje do pracy z preferencjami edytora; szczegóły w sekcji [Preferencje](#preferences). + +Pełne API edytora znajdziesz [tutaj](https://defold.com/ref/alpha/editor/). + +## Polecenia + +Jeśli moduł skryptu edytora definiuje funkcję `get_commands`, zostanie ona wywołana podczas przeładowywania rozszerzeń, a zwrócone polecenia będą dostępne w pasku menu edytora albo w menu kontekstowych paneli Assets i Outline. Przykład: ```lua local M = {} @@ -80,14 +106,9 @@ function M.get_commands() end, run = function(opts) local text = editor.get(opts.selection, "text") - return { - { - action = "set", - node_id = opts.selection, - property = "text", - value = strip_comments(text) - } - } + editor.transact({ + editor.tx.set(opts.selection, "text", strip_comments(text)) + }) end }, { @@ -101,12 +122,7 @@ function M.get_commands() end, run = function(opts) local path = editor.get(opts.selection, "path") - return { - { - action = "shell", - command = {"./scripts/minify-json.sh", path:sub(2)} - } - } + editor.execute("./scripts/minify-json.sh", path:sub(2)) end } } @@ -115,116 +131,471 @@ end return M ``` -Edytor oczekuje, że funkcja `get_commands()` zwróci tablicę tablic, z których każda opisuje osobne polecenie. Opis polecenia składa się z: +Edytor oczekuje, że `get_commands()` zwróci tablicę tabel, z których każda opisuje jedno polecenie. Opis polecenia składa się z: -- `label` (wymagane) — tekst, który zostanie wyświetlony użytkownikowi jako pozycja w menu. -- `locations` (wymagane) — tablica zawierająca jedno z poniższych: `"Edit"`, `"View"`, `"Assets"` lub `"Outline"` - określa, w jakim miejscu Edytora menu powinno być dostępne. `"Edit"` i `"View"` oznaczają pasek menu na górze, `"Assets"` oznacza menu kontekstowe w panelu `"Assets"`, a `"Outline"` oznacza menu kontekstowe w panelu `"Outline"`. -- `query` — sposób, w jaki polecenie pyta Edytor o odpowiednie informacje i definiuje, na jakich danych operuje. Dla każdego klucza w tabeli `query` istnieje odpowiadający klucz w tabeli `opts`, który jest przekazywany jako argument do funkcji `active` i `run`. Obsługiwane klucze to: - - `selection` — oznacza, że polecenie jest ważne, gdy coś w Edytorze jest zaznaczone, i działa na tym zaznaczeniu. - - `type` — określa typ zaznaczonych węzłów, na które polecenie jest zainteresowane. Obecnie dozwolone są następujące rodzaje: - - `"resource"` — w panelach `"Assets"` i `"Outline"` oznacza zaznaczony element, który ma odpowiadający plik. W pasku menu (`Edit` lub `View`), `"resource"` to aktualnie otwarty plik; - - `"outline"` — coś, co może być wyświetlane w `"Outline"`. W `"Outline"` to zaznaczony element, w pasku menu to aktualnie otwarty plik; - - `cardinality` — określa, ile zaznaczonych elementów powinno być. Jeśli jest to `"one"`, zaznaczenie przekazywane do funkcji obsługującej polecenie będzie zawierać tylko jeden identyfikator węzła. Jeśli jest to `"many"`, przekazywana tablica będzie zawierać jeden lub więcej identyfikatorów węzła. -- `active` - funkcja wywoływana w celu sprawdzenia, czy polecenie jest aktywne, powinna zwracać wartość logiczną. Jeśli w locations zawarte są `"Assets"` lub `"Outline"`, funkcja `active` zostanie wywołana podczas wyświetlania menu kontekstowego. Jeśli w `locations` zawarte są `"Edit"` lub `"View"`, funkcja `active` zostanie wywołana przy każdej interakcji użytkownika, takiej jak pisanie na klawiaturze lub klikanie myszą, dlatego upewnij się, że funkcja `active` działa stosunkowo szybko. -- `run` - funkcja wywoływana, gdy użytkownik wybierze pozycję z menu, i powinna zwrócić tablicę akcji - [actions](#actions). +- `label` (wymagane) — tekst pozycji menu widoczny dla użytkownika; +- `locations` (wymagane) — tablica zawierająca `"Edit"`, `"View"`, `"Project"`, `"Debug"`, `"Assets"`, `"Bundle"`, `"Scene"` albo `"Outline"`, określająca, gdzie polecenie ma być dostępne. `"Edit"`, `"View"`, `"Project"` i `"Debug"` oznaczają górny pasek menu, `"Assets"` oznacza menu kontekstowe panelu Assets, `"Outline"` oznacza menu kontekstowe panelu Outline, a `"Bundle"` oznacza podmenu **Project → Bundle**; +- `query` — sposób, w jaki polecenie prosi edytor o potrzebne dane i definiuje, na czym operuje. Dla każdego klucza w tabeli `query` pojawi się odpowiadający klucz w tabeli `opts`, przekazywanej do funkcji `active` i `run`. Obsługiwane klucze: + - `selection` oznacza, że polecenie działa na aktualnym zaznaczeniu. + - `type` określa typ zaznaczonych węzłów. Obecnie dozwolone są: + - `"resource"` — w Assets i Outline oznacza zaznaczony element mający odpowiadający mu plik. W pasku menu (Edit lub View) oznacza aktualnie otwarty plik; + - `"outline"` — coś, co może być pokazane w Outline. W Outline to zaznaczony element, w pasku menu — aktualnie otwarty plik; + - `"scene"` — coś, co da się wyrenderować w Scene; + - `cardinality` określa liczbę zaznaczonych elementów. Dla `"one"` callback otrzyma pojedynczy `node_id`, a dla `"many"` — tablicę co najmniej jednego `node_id`; + - `argument` — argument polecenia. Obecnie tylko polecenia z lokalizacją `"Bundle"` otrzymują argument: `true`, gdy użytkownik jawnie wybrał bundlowanie, i `false` przy rebundle; +- `id` — identyfikator polecenia, używany na przykład do zapamiętywania ostatnio użytego polecenia bundlowania w `prefs`; +- `active` — callback sprawdzający, czy polecenie ma być aktywne. Powinien zwracać wartość logiczną. Jeśli `locations` zawiera `"Assets"`, `"Scene"` albo `"Outline"`, `active` zostanie wywołane przy otwieraniu menu kontekstowego. Jeśli `locations` zawiera `"Edit"` albo `"View"`, `active` będzie uruchamiane przy każdej interakcji użytkownika, na przykład podczas pisania na klawiaturze lub kliknięć myszą, więc musi działać stosunkowo szybko; +- `run` — callback wykonywany po wybraniu polecenia przez użytkownika. -## Actions +### Używanie poleceń do zmiany stanu edytora w pamięci -Action (akcja) to tabela opisująca, co Edytor powinien zrobić. Każda akcja zawiera klucz `action`. Akcje dzielą się na dwa rodzaje: możliwe do cofnięcia (undoable) i niemożliwe do cofnięcia (non-undoable). +Wewnątrz `run` możesz odczytywać i zmieniać stan edytora zapisany w pamięci. Odczyt odbywa się przez `editor.get()`, co pozwala pobierać aktualny stan plików i zaznaczenia (jeśli używasz `query = {selection = ...}`). Możesz pobrać właściwość `"text"` plików skryptów oraz wybrane właściwości widoczne w panelu Properties — najedź kursorem na nazwę właściwości, aby zobaczyć, jak nazywa się w skryptach edytora. Zmiany w stanie edytora wykonuje się przez `editor.transact()`, gdzie grupujesz jedną lub więcej modyfikacji w pojedynczy krok z możliwością cofnięcia. Na przykład polecenie resetujące transformację obiektu gry może wyglądać tak: -### Akcje możliwe do cofnięcia +```lua +{ + label = "Reset transform", + locations = {"Outline"}, + query = {selection = {type = "outline", cardinality = "one"}}, + active = function(opts) + local node = opts.selection + return editor.can_set(node, "position") + and editor.can_set(node, "rotation") + and editor.can_set(node, "scale") + end, + run = function(opts) + local node = opts.selection + editor.transact({ + editor.tx.set(node, "position", {0, 0, 0}), + editor.tx.set(node, "rotation", {0, 0, 0}), + editor.tx.set(node, "scale", {1, 1, 1}) + }) + end +} +``` -Undoable action - możliwa do cofnięcia akcja może zostać cofnięta po jej wykonaniu (Undo or Ctrl + Z). Jeśli polecenie zwraca wiele akcji możliwych do cofnięcia, są one wykonywane razem i cofane razem. Należy używać akcji możliwych do cofnięcia, jeśli to możliwe. Ich wadą są większe ograniczenia. +#### Edycja atlasów -Istniejące działania możliwe do cofnięcia to: +Poza odczytem i zapisem właściwości atlasu możesz też odczytywać i modyfikować obrazy oraz animacje atlasu. Atlas definiuje właściwości listowe `images` i `animations`, a animacje mają dodatkowo listową właściwość `images`. Z tymi właściwościami można używać kroków transakcji `editor.tx.add`, `editor.tx.remove` i `editor.tx.clear`. -- `"set"` — ustawienie właściwości węzła w Edytorze na określoną wartość. Przykład: - ```lua - { - action = "set", - node_id = opts.selection, - property = "text", - value = "current time is " .. os.date() - } - ``` -Akcja `"set"` wymaga podania tych parametrów: - - `node_id` — identyfikator węzła jako userdata. Alternatywnie, można użyć ścieżki zasobu zamiast identyfikatora węzła otrzymanego od Edytora, na przykład `"/main/game.script"`; - - `property` — właściwość węzła do ustawienia, obecnie obsługiwane jes tylko `"text"`; - - `value` — nowa wartość właściwości. Dla właściwości `"text"` powinno to być łańcuchem znaków (string). +Na przykład, aby dodać obraz do atlasu, uruchom w `run` takie polecenie: -### Akcje niemożliwe do cofnięcia +```lua +editor.transact({ + editor.tx.add("/main.atlas", "images", {image="/assets/hero.png"}) +}) +``` -Akcje możliwe do cofnięcia czyszczą historię cofnięć (undo), więc z poziomu Edytora nie można ich cofnąć i jeśli użytkownik chce to zrobić, musi użyć innych środków, np. systemów kontroli wersji. +Aby zbudować zbiór wszystkich obrazów w atlasie: -Istniejące działania niemożliwe do cofnięcia to: -- `"shell"` — wykonanie skryptu powłoki. Przykład: - ```lua - { - action = "shell", - command = { - "./scripts/minify-json.sh", - editor.get(opts.selection, "path"):sub(2) -- trim leading "/" - } - } - ``` -Działanie `"shell"` wymaga parametru `command`, który jest tablicą polecenia, oraz jego argumentów. Główna różnica w porównaniu do `os.execute` polega na tym, że jest to potencjalnie niebezpieczna operacja, dlatego Edytor wyświetli okno dialogowe z pytaniem do użytkownika czy na pewno chce wywołać daną komendę. Edytor zapamięta, jeśli użytkownik już wyraził zgodę na wykonanie takiej komendy. +```lua +local all_images = {} ---@type table +-- najpierw zbierz "gołe" obrazy +local image_nodes = editor.get("/main.atlas", "images") +for i = 1, #image_nodes do + all_images[editor.get(image_nodes[i], "image")] = true +end +-- następnie zbierz obrazy używane w animacjach +local animation_nodes = editor.get("/main.atlas", "animations") +for i = 1, #animation_nodes do + local animation_image_nodes = editor.get(animation_nodes[i], "images") + for j = 1, #animation_image_nodes do + all_images[editor.get(animation_image_nodes[j], "image")] = true + end +end +pprint(all_images) +-- { +-- ["/assets/hero.png"] = true, +-- ["/assets/enemy.png"] = true, +-- }} +``` -### Łączenie akcji i efekty uboczne +Aby zastąpić wszystkie animacje w atlasie: -Możesz łączyć akcje możliwe do cofnięcia (undoable) i akcje niemożliwe do cofnięcia (non-undoable). Akcje są wykonywane sekwencyjnie, dlatego w zależności od kolejności działań możesz stracić możliwość cofania części tego polecenia. +```lua +editor.transact({ + editor.tx.clear("/main.atlas", "animations"), + editor.tx.add("/main.atlas", "animations", { + id = "hero_run", + images = { + {image = "/assets/hero_run_1.png"}, + {image = "/assets/hero_run_2.png"}, + {image = "/assets/hero_run_3.png"}, + {image = "/assets/hero_run_4.png"} + } + }) +}) +``` + +#### Edycja tilesource -Zamiast zwracać akcje z funkcji, które ich oczekują, możesz po prostu czytać i zapisywać dane bezpośrednio do plików, korzystając z funkcji `io.open()`. Spowoduje to ponowne załadowanie zasobów, co wyczyści historię cofania (undo history). +Poza zwykłymi właściwościami z Outline, tilesource definiuje jeszcze: -## Haki cyklu życia (Lifecycle Hooks) +- `animations` — listę węzłów animacji tilesource; +- `collision_groups` — listę węzłów grup kolizji tilesource; +- `tile_collision_groups` — tabelę przypisań grup kolizji do kafelków tilesource. -Istnieje jeden, specjalnie traktowany plik Skryptu Edytora: `hooks.editor_script`, znajdujący się w głównym katalogu twojego projektu, w tym samym katalogu co `game.project`. Tylko ten plik Skryptu Edytora otrzyma zdarzenia cyklu życia od Edytora. Oto przykład takiego pliku: +Przykładowa konfiguracja tilesource: ```lua -local M = {} +local tilesource = "/game/world.tilesource" +editor.transact({ + editor.tx.add(tilesource, "animations", {id = "idle", start_tile = 1, end_tile = 1}), + editor.tx.add(tilesource, "animations", {id = "walk", start_tile = 2, end_tile = 6, fps = 10}), + editor.tx.add(tilesource, "collision_groups", {id = "player"}), + editor.tx.add(tilesource, "collision_groups", {id = "obstacle"}), + editor.tx.set(tilesource, "tile_collision_groups", { + [1] = "player", + [7] = "obstacle", + [8] = "obstacle" + }) +}) +``` -function M.on_build_started(opts) - local file = io.open("assets/build.json", "w") - file:write("{\"build_time\": \"".. os.date() .."\"}") - file:close() +#### Edycja tilemap + +Tilemapy definiują właściwość `layers`, która jest listą węzłów warstw. Każda warstwa ma z kolei właściwość `tiles`, przechowującą nieograniczoną dwuwymiarową siatkę kafelków. To zachowuje się inaczej niż w silniku: kafelki nie mają ograniczonych granic i można je dodawać w dowolnym miejscu, także na ujemnych współrzędnych. Do pracy z kafelkami API skryptów edytora udostępnia moduł `tilemap.tiles` z funkcjami: + +- `tilemap.tiles.new()` — tworzy pustą strukturę danych dla nieograniczonej siatki kafelków; +- `tilemap.tiles.get_tile(tiles, x, y)` — zwraca indeks kafelka na podanych współrzędnych; +- `tilemap.tiles.get_info(tiles, x, y)` — zwraca pełne informacje o kafelku w danym punkcie (kształt danych jest zgodny z `tilemap.get_tile_info` w silniku); +- `tilemap.tiles.iterator(tiles)` — tworzy iterator po wszystkich kafelkach tilemapy; +- `tilemap.tiles.clear(tiles)` — usuwa wszystkie kafelki; +- `tilemap.tiles.set(tiles, x, y, tile_or_info)` — ustawia kafelek w podanym miejscu; +- `tilemap.tiles.remove(tiles, x, y)` — usuwa kafelek z podanych współrzędnych. + +Przykład wypisania całej zawartości tilemapy: + +```lua +local layers = editor.get("/level.tilemap", "layers") +for i = 1, #layers do + local layer = layers[i] + local id = editor.get(layer, "id") + local tiles = editor.get(layer, "tiles") + print("layer " .. id .. ": {") + for x, y, tile in tilemap.tiles.iterator(tiles) do + print(" [" .. x .. ", " .. y .. "] = " .. tile) + end + print("}") end +``` -return M +Przykład dodania nowej warstwy z kafelkami: + +```lua +local tiles = tilemap.tiles.new() +tilemap.tiles.set(tiles, 1, 1, 2) +editor.transact({ + editor.tx.add("/level.tilemap", "layers", { + id = "new_layer", + tiles = tiles + }) +}) +``` + +#### Edycja particlefx + +particlefx możesz edytować przez właściwości `modifiers` i `emitters`. Na przykład dodanie emitera kołowego z modyfikatorem przyspieszenia wygląda tak: + +```lua +editor.transact({ + editor.tx.add("/fire.particlefx", "emitters", { + type = "emitter-type-circle", + modifiers = { + {type = "modifier-type-acceleration"} + } + }) +}) ``` -Zdecydowaliśmy się ograniczyć haki cyklu życia do jednego pliku Skryptu Edytora, ponieważ kolejność wykonywania haków budowania (build hooks) jest ważniejsza niż łatwość dodawania kolejnego kroku buildu. Polecenia są niezależne od siebie, więc nie ma znaczenia, w jakiej kolejności są wyświetlane w menu. W końcu to użytkownik wykonuje konkretne polecenie, które wybrał. Gdyby można było określać haki cyklu życia w różnych plikach Skryptu Edytora, stworzyłoby to problem: w jakiej kolejności mają się wykonywać haki? Chcesz prawdopodobnie utworzyć sumy kontrolne zawartości po jej skompresowaniu... Dlatego posiadanie jednego pliku, który ustala kolejność kroków buildu, wywołując każdą funkcję kroku, jest sposobem na rozwiązanie tego problemu. +Wiele właściwości particlefx to krzywe albo krzywe ze spreadem (czyli krzywa plus losowy rozrzut). Krzywe są reprezentowane jako tabela z niepustą listą `points`, gdzie każdy punkt jest tabelą z właściwościami: + +- `x` — współrzędna x punktu; powinna zaczynać się od 0 i kończyć na 1; +- `y` — wartość punktu; +- `tx` (0 do 1) i `ty` (-1 do 1) — tangensy punktu. Dla kąta 80 stopni `tx` powinno być równe `math.cos(math.rad(80))`, a `ty` — `math.sin(math.rad(80))`. -Każdy hak cyklu życia może zwracać akcje lub zapisywać pliki w katalogu projektu. +Krzywe ze spreadem mają dodatkowo właściwość liczbową `spread`. -Istniejące haki cyklu życia, które plik `hooks.editor_script` może określić: -- `on_build_started(opts)` — wykonywane, gdy gra jest budowana w celu uruchomienia jej lokalnie lub na zdalnym, docelowym urządzeniu, używając opcji `"Project Build"` lub `"Debug Start"`. Twoje zmiany, czy to zwracane akcje czy zaktualizowane zawartości pliku, pojawią się w zbudowanej grze. Wyrzucenie błędu z tego haka spowoduje przerwanie budowy. `opts` to tabela zawierająca obecnie następujący klucz: - - `platform` — łańcuch w formacie `%arch%-%os%`, opisujący platformę, dla której budowana jest gra, zawsze taki sam jak `editor.platform`. -- `on_build_finished(opts)` — wykonywane, gdy budowa zostanie zakończona, niezależnie od tego, czy zakończyła się sukcesem czy nie. `opts` w tym przypadku to tabela zawierająca następujące klucze: - - `platform` — to samo, co w `on_build_started`. - - `success` — czy budowa zakończyła się sukcesem, true lub false. -- `on_bundle_started(opts)` — wykonywane, gdy tworzysz paczkę z grą lub budujesz wersję HTML5 gry. Podobnie jak `on_build_started`, zmiany wywołane przez ten hak pojawią się w paczce, a błędy spowodują przerwanie procesu pakowania (bundle). `opts` zawiera tutaj następujące klucze: - - `output_directory — ścieżka do katalogu wyjściowego paczki, na przykład `"/path/to/project/build/default/__htmlLaunchDir"` - - `platform` — platforma, dla której paczka jest tworzona. Zobacz listę możliwych wartości platform w podręczniku Boba (narzędzia do budowania i pakowania). - - `variant` — wariant paczki, `"debug"`, `"release"` lub `"headless"`. -- `on_bundle_finished(opts)` — wykonywane, gdy budowanie paczki (bundle) zostanie ukończone, niezależnie od tego, czy zakończyło się sukcesem. `opts` w tym przypadku to tabela zawierająca te same dane co `opts` w `on_bundle_started`, oraz dodatkowo klucz `success`, który wskazuje, czy budowa zakończyła się sukcesem. - - `on_target_launched(opts)` — wykonywane, gdy użytkownik uruchomił grę i uruchomienie zakończyło się sukcesem. `opts` zawiera klucz `url` wskazujący na uruchomioną usługę silnika, na przykład `"http://127.0.0.1:35405"`. - - `on_target_terminated(opts)` — wykonywane, gdy uruchomiona gra zostaje zamknięta. `opts` ma te same klucze co `on_target_launched`. +Przykład ustawienia krzywej alpha czasu życia cząsteczki dla istniejącego emitera: -Należy zauważyć, że haki cyklu życia są obecnie funkcją dostępną tylko w Edytorze i nie są wykonywane przez Boba podczas pakowania z wiersza poleceń. +```lua +local emitter = editor.get("/fire.particlefx", "emitters")[1] +editor.transact({ + editor.tx.set(emitter, "particle_key_alpha", { points = { + {x = 0, y = 0, tx = 0.1, ty = 1}, -- startuj od 0 i szybko rośnij + {x = 0.2, y = 1, tx = 1, ty = 0}, -- osiągnij 1 po 20% czasu życia + {x = 1, y = 0, tx = 1, ty = 0} -- powoli opadaj do 0 + }}) +}) +``` -## Skrypty Edytora w bibliotekach +Oczywiście można też użyć klucza `particle_key_alpha` bezpośrednio w tabeli podczas tworzenia emitera. Dodatkowo zamiast krzywej możesz podać pojedynczą liczbę reprezentującą krzywą statyczną. -Możesz publikować biblioteki dla użytku przez inne osoby, które zawierają polecenia, i zostaną one automatycznie wykryte przez Edytor. Haki cyklu życia nie mogą być jednak automatycznie wykrywane, ponieważ muszą być zdefiniowane w pliku znajdującym się w głównym katalogu projektu, a biblioteki wystawiają tylko podkatalogi. Ma to na celu umożliwienie większej kontroli nad procesem budowy: nadal możesz tworzyć haki cyklu życia jako proste funkcje w plikach `.lua`, więc użytkownicy twojej biblioteki mogą je zaimportować i używać w swoim pliku `hooks.editor_script`. +#### Edycja obiektów kolizji -Należy również zauważyć, że chociaż zależności są wyświetlane w widoku `"Assets"`, to nie istnieją one jako pliki (są wpisami w archiwum zip), więc obecnie nie ma łatwego sposobu na wykonanie skryptu powłoki dostarczonego jako zależności (biblioteki). Jeśli jest to absolutnie konieczne, będziesz musiał wydobyć dostarczone skrypty, pobierając ich tekst za pomocą `editor.get()` i zapisując go gdzieś za pomocą `file:write()`, na przykład w katalogu `build/editor-scripts/your-extension-name`. +Poza domyślnymi właściwościami z Outline obiekty kolizji definiują listową właściwość `shapes`. Dodawanie nowych kształtów kolizji wygląda tak: -Prostszym sposobem na wydobycie niezbędnych plików jest wykorzystanie systemu wtyczek rozszerzeń natywnych (native extensions). Aby to zrobić, musisz utworzyć plik `ext.manifest` w katalogu twojej biblioteki, a następnie utworzyć katalog `plugins/bin/${platform}` w tym samym katalogu, w którym znajduje się plik `ext.manifest`. Pliki w tym katalogu zostaną automatycznie wydobyte do katalogu `/build/plugins/${extension-path}/plugins/bin/${platform}`, dzięki czemu twoje Skrypty Edytora mogą się do nich odnosić. +```lua +editor.transact({ + editor.tx.add("/hero.collisionobject", "shapes", { + type = "shape-type-box" -- albo "shape-type-sphere", "shape-type-capsule" + }) +}) +``` -## Serwery językowy (language servers) +Właściwość `type` kształtu jest wymagana podczas tworzenia i nie można jej zmienić po dodaniu kształtu. Dostępne są trzy typy: -Edytor obsługuje niewielki podzbiór protokołu [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). Chociaż zamierzamy rozwijać obsługę Edytora dla funkcji LSP w przyszłości, obecnie obsługuje on tylko wykrywanie diagnoz (lints) w edytowanych plikach. +- `shape-type-box` — kształt pudełkowy z właściwością `dimensions`; +- `shape-type-sphere` — kształt sferyczny z właściwością `diameter`; +- `shape-type-capsule` — kapsuła z właściwościami `diameter` i `height`. -Aby zdefiniować serwer językowy, musisz edytować funkcję `get_language_servers` w swoim Skrypcie Edytora, jak w poniższym przykładzie: +#### Edycja plików GUI +Poza właściwościami z Outline pliki GUI definiują: + +- `layers` — listę węzłów warstw GUI z możliwością zmiany kolejności; +- `materials` — listę węzłów materiałów. + +Warstwy GUI można edytować przez właściwość `layers`, na przykład: + +```lua +editor.transact({ + editor.tx.add("/main.gui", "layers", {name = "foreground"}), + editor.tx.add("/main.gui", "layers", {name = "background"}) +}) +``` + +Można też zmieniać kolejność warstw: + +```lua +local fg, bg = table.unpack(editor.get("/main.gui", "layers")) +editor.transact({ + editor.tx.reorder("/main.gui", "layers", {bg, fg}) +}) +``` + +Podobnie fonty, materiały, tekstury i particlefx są edytowane przez właściwości `fonts`, `materials`, `textures` i `particlefxs`: + +```lua +editor.transact({ + editor.tx.add("/main.gui", "fonts", {font = "/main.font"}), + editor.tx.add("/main.gui", "materials", {name = "shine", material = "/shine.material"}), + editor.tx.add("/main.gui", "particlefxs", {particlefx = "/confetti.material"}), + editor.tx.add("/main.gui", "textures", {texture = "/ui.atlas"}) +}) +``` + +Te właściwości nie obsługują zmiany kolejności. + +Na końcu możesz też edytować węzły GUI przez listową właściwość `nodes`, na przykład: + +```lua +editor.transact({ + editor.tx.add("/main.gui", "nodes", { + type = "gui-node-type-box", + position = {20, 20, 20} + }), + editor.tx.add("/main.gui", "nodes", { + type = "gui-node-type-template", + template = "/button.gui" + }), +}) +``` + +Wbudowane typy węzłów: + +- `gui-node-type-box` +- `gui-node-type-particlefx` +- `gui-node-type-pie` +- `gui-node-type-template` +- `gui-node-type-text` + +Jeśli korzystasz z rozszerzenia Spine, możesz też używać typu `gui-node-type-spine`. + +Jeżeli plik GUI definiuje layouty, możesz pobierać i ustawiać wartości z layoutów przez składnię `layout:property`, na przykład: + +```lua +local node = editor.get("/main.gui", "nodes")[1] + +-- ODCZYT: +local position = editor.get(node, "position") +pprint(position) -- {20, 20, 20} +local landscape_position = editor.get(node, "Landscape:position") +pprint(landscape_position) -- {20, 20, 20} + +-- ZAPIS: +editor.transact({ + editor.tx.set(node, "Landscape:position", {30, 30, 30}) +}) +pprint(editor.get(node, "Landscape:position")) -- {30, 30, 30} +``` + +Właściwości layoutów, które zostały ustawione, można przywracać do wartości domyślnych przez `editor.tx.reset`: + +```lua +print(editor.can_reset(node, "Landscape:position")) -- true +editor.transact({ + editor.tx.reset(node, "Landscape:position") +}) +``` + +Drzewa węzłów szablonu można odczytywać, ale nie można ich edytować — da się ustawiać tylko właściwości węzłów w drzewie szablonu: + +```lua +local template = editor.get("/main.gui", "nodes")[2] +print(editor.can_add(template, "nodes")) -- false +local node_in_template = editor.get(template, "nodes")[1] +editor.transact({ + editor.tx.set(node_in_template, "text", "Button text") +}) +print(editor.can_reset(node_in_template, "text")) -- true (nadpisuje wartość z szablonu) +``` + +#### Edycja obiektów gry + +Skrypty edytora potrafią edytować komponenty pliku obiektu gry. Komponenty występują w dwóch wariantach: referencyjne i osadzone. Komponenty referencyjne mają typ `component-reference` i działają jako odwołania do innych zasobów, pozwalając jedynie nadpisywać właściwości go zdefiniowane w skryptach. Komponenty osadzone mają typy takie jak `sprite`, `label` itd. i pozwalają edytować wszystkie właściwości właściwe dla danego typu komponentu, a także dodawać podkomponenty, na przykład kształty obiektów kolizji. Przykładowa konfiguracja obiektu gry: + +```lua +editor.transact({ + editor.tx.add("/npc.go", "components", { + type = "sprite", + id = "view" + }), + editor.tx.add("/npc.go", "components", { + type = "collisionobject", + id = "collision", + shapes = { + { + type = "shape-type-box", + dimensions = {32, 32, 32} + } + } + }), + editor.tx.add("/npc.go", "components", { + type = "component-reference", + path = "/npc.script", + id = "controller", + __hp = 100 -- ustaw właściwość go zdefiniowaną w skrypcie + }) +}) +``` + +#### Edycja kolekcji + +Skrypty edytora potrafią też edytować kolekcje. Możesz dodawać obiekty gry (osadzone albo referencyjne) oraz kolekcje referencyjne. Na przykład: + +```lua +local coll = "/char.collection" +editor.transact({ + editor.tx.add(coll, "children", { + -- osadzony obiekt gry + type = "go", + id = "root", + children = { + { + -- referencyjny obiekt gry + type = "go-reference", + path = "/char-view.go", + id = "view" + }, + { + -- referencyjna kolekcja + type = "collection-reference", + path = "/body-attachments.collection", + id = "attachments" + } + }, + -- osadzone obiekty gry mogą też zawierać komponenty + components = { + { + type = "collisionobject", + id = "collision", + shapes = { + {type = "shape-type-box", dimensions = {2.5, 2.5, 2.5}} + } + }, + { + type = "component-reference", + id = "controller", + path = "/char.script", + __hp = 100 -- ustaw właściwość go zdefiniowaną w skrypcie + } + } + }) +}) +``` + +Podobnie jak w edytorze, referencyjne kolekcje można dodawać tylko do korzenia edytowanej kolekcji, a obiekty gry można dodawać tylko do osadzonych albo referencyjnych obiektów gry, ale nie do referencyjnych kolekcji ani do obiektów gry wewnątrz takich kolekcji. + +### Używanie poleceń powłoki + +Wewnątrz `run` możesz zapisywać pliki przy użyciu modułu `io` i uruchamiać polecenia powłoki przez `editor.execute()`. Przy wykonywaniu poleceń możesz też przechwycić ich tekstowy wynik i użyć go dalej w kodzie. Jeśli na przykład chcesz dodać polecenie formatujące JSON przez globalnie zainstalowane [`jq`](https://jqlang.github.io/jq/), możesz napisać: + +```lua +{ + label = "Format JSON", + locations = {"Assets"}, + query = {selection = {type = "resource", cardinality = "one"}}, + action = function(opts) + local path = editor.get(opts.selection, "path") + return path:match(".json$") ~= nil + end, + run = function(opts) + local text = editor.get(opts.selection, "text") + local new_text = editor.execute("jq", "-n", "--argjson", "data", text, "$data", { + reload_resources = false, -- nie przeładowuj zasobów, bo jq nie zapisuje nic na dysku + out = "capture" -- zwróć tekstowy wynik zamiast braku wyniku + }) + editor.transact({ editor.tx.set(opts.selection, "text", new_text) }) + end +} +``` + +Ponieważ to polecenie uruchamia program powłoki tylko do odczytu i informuje o tym edytor przez `reload_resources = false`, akcję nadal da się cofnąć. + +::: sidenote +Jeśli chcesz dystrybuować skrypt edytora jako bibliotekę, możesz chcieć dołączyć binarny program dla platform edytora w ramach zależności. Więcej informacji znajdziesz w sekcji [Skrypty edytora w bibliotekach](#editor-scripts-in-libraries). +::: + +## Hooki cyklu życia + +Istnieje specjalnie traktowany plik skryptu edytora: `hooks.editor_script`, umieszczony w katalogu głównym projektu, obok pliku *game.project*. Tylko ten jeden skrypt edytora otrzymuje zdarzenia cyklu życia z edytora. Przykład: + +```lua +local M = {} + +function M.on_build_started(opts) + local file = io.open("assets/build.json", "w") + file:write('{"build_time": "' .. os.date() .. '"}') + file:close() +end + +return M +``` + +Zdecydowaliśmy się ograniczyć hooki cyklu życia do jednego pliku skryptu edytora, ponieważ kolejność wykonywania kroków builda jest ważniejsza niż łatwość dodania kolejnego kroku. Polecenia są od siebie niezależne, więc kolejność wyświetlania ich w menu nie ma większego znaczenia — i tak użytkownik uruchamia konkretne wybrane polecenie. Gdyby hooki builda dało się definiować w wielu skryptach edytora, pojawiłby się problem: w jakiej kolejności miałyby działać? Prawdopodobnie chcesz wyliczać sumy kontrolne dopiero po skompresowaniu zawartości. Jeden plik, który jawnie ustala kolejność kroków builda przez wywoływanie odpowiednich funkcji, rozwiązuje ten problem. + +Istniejące haki cyklu życia, które może zdefiniować `/hooks.editor_script`: + +- `on_build_started(opts)` — wywoływany, gdy gra jest budowana do uruchomienia lokalnie albo na zdalnym urządzeniu przez Project Build lub Debug Start. Twoje zmiany pojawią się w zbudowanej grze. Wyrzucenie błędu z tego haka przerwie build. `opts` to tabela z kluczami: + - `platform` — łańcuch w formacie `%arch%-%os%`, opisujący platformę docelową; obecnie zawsze taki sam jak `editor.platform`; +- `on_build_finished(opts)` — wywoływany po zakończeniu builda, niezależnie od wyniku. `opts` zawiera: + - `platform` — to samo co w `on_build_started`; + - `success` — `true` albo `false`, w zależności od tego, czy build zakończył się powodzeniem; +- `on_bundle_started(opts)` — wywoływany podczas tworzenia bundla albo budowania wersji HTML5. Podobnie jak `on_build_started`, zmiany wykonane przez ten hak trafią do bundla, a błędy przerwą proces. `opts` zawiera: + - `output_directory` — ścieżkę do katalogu z wynikowym bundlem, na przykład `"/path/to/project/build/default/__htmlLaunchDir"`; + - `platform` — platformę, dla której tworzony jest bundle. Listę możliwych wartości znajdziesz w [instrukcji Boba](/manuals/bob); + - `variant` — wariant bundla: `"debug"`, `"release"` albo `"headless"`; +- `on_bundle_finished(opts)` — wywoływany po zakończeniu bundlowania, niezależnie od wyniku. `opts` zawiera te same dane co `on_bundle_started`, plus klucz `success`; +- `on_target_launched(opts)` — wywoływany, gdy użytkownik uruchomi grę i start zakończy się sukcesem. `opts` zawiera klucz `url` wskazujący uruchomioną usługę silnika, na przykład `"http://127.0.0.1:35405"`; +- `on_target_terminated(opts)` — wywoływany po zamknięciu uruchomionej gry; otrzymuje taki sam `opts` jak `on_target_launched`. + +Pamiętaj, że hooki cyklu życia są obecnie funkcją dostępną wyłącznie w edytorze i nie są wykonywane przez Boba podczas bundlowania z wiersza poleceń. + +## Serwery językowe + +Edytor obsługuje podzbiór [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). Docelowo chcemy rozszerzyć obsługę funkcji LSP, ale obecnie edytor potrafi tylko pokazywać diagnostykę (czyli linty) w edytowanych plikach oraz podpowiedzi. + +Aby zdefiniować serwer językowy, edytuj funkcję `get_language_servers` w swoim skrypcie edytora na przykład tak: ```lua function M.get_language_servers() @@ -244,10 +615,218 @@ function M.get_language_servers() end ``` -Edytor uruchomi serwer językowy, korzystając z określonej komendy, używając standardowego wejścia i wyjścia procesu serwera do komunikacji. +Edytor uruchomi serwer językowy przy użyciu zdefiniowanego `command`, komunikując się z procesem przez standardowe wejście i wyjście. + +Tabela definicji serwera językowego może zawierać: + +- `languages` (wymagane) — listę języków, którymi serwer jest zainteresowany; identyfikatory są zdefiniowane [tutaj](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers), ale działają też rozszerzenia plików; +- `command` (wymagane) — tablicę z poleceniem i argumentami; +- `watched_files` — tablicę tabel z kluczami `pattern` (glob), które będą wyzwalały powiadomienie serwera o [zmianie obserwowanych plików](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didChangeWatchedFiles). + +## Serwer HTTP + +Każda uruchomiona instancja edytora ma aktywny serwer HTTP. Można go rozszerzać przy użyciu skryptów edytora. Aby dodać własne endpointy, zdefiniuj funkcję `get_http_server_routes`, która zwróci dodatkowe trasy: + +```lua +print("My route: " .. http.server.url .. "/my-extension") + +function M.get_http_server_routes() + return { + http.server.route("/my-extension", "GET", function(request) + return http.server.response(200, "Hello world!") + end) + } +end +``` + +Po przeładowaniu skryptów edytora w konsoli zobaczysz komunikat podobny do `My route: http://0.0.0.0:12345/my-extension`. Po otwarciu tego linku w przeglądarce zobaczysz komunikat `"Hello world!"`. + +Argument `request` jest prostą tabelą Lua z informacjami o żądaniu. Zawiera między innymi klucze `path` (segment ścieżki URL zaczynający się od `/`), `method` (na przykład `"GET"`), `headers` (tabela z nazwami nagłówków zapisanymi małymi literami), a opcjonalnie także `query` oraz `body`, jeśli dana trasa definiuje sposób interpretacji body. Na przykład endpoint przyjmujący body w formacie JSON definiuje się z konwerterem `"json"`: + +```lua +http.server.route("/my-extension/echo-request", "POST", "json", function(request) + return http.server.json_response(request) +end) +``` + +Taki endpoint możesz przetestować w terminalu przez `curl` i `jq`: + +```sh +curl 'http://0.0.0.0:12345/my-extension/echo-request?q=1' -X POST --data '{"input": "json"}' | jq +{ + "path": "/my-extension/echo-request", + "method": "POST", + "query": "q=1", + "headers": { + "host": "0.0.0.0:12345", + "content-type": "application/x-www-form-urlencoded", + "accept": "*/*", + "user-agent": "curl/8.7.1", + "content-length": "17" + }, + "body": { + "input": "json" + } +} +``` + +Ścieżka trasy obsługuje wzorce, które można wyłuskać z request path i przekazać do handlera jako część obiektu request, na przykład: + +```lua +http.server.route("/my-extension/setting/{category}.{key}", function(request) + return http.server.response(200, tostring(editor.get("/game.project", request.category .. "." .. request.key))) +end) +``` + +Jeśli otworzysz adres taki jak `http://0.0.0.0:12345/my-extension/setting/project.title`, zobaczysz tytuł gry odczytany z pliku `/game.project`. + +Poza wzorcami pojedynczego segmentu można też dopasowywać resztę ścieżki URL składnią `{*name}`. Na przykład prosty endpoint serwujący pliki z katalogu projektu może wyglądać tak: + +```lua +http.server.route("/my-extension/files/{*file}", function(request) + local attrs = editor.external_file_attributes(request.file) + if attrs.is_file then + return http.server.external_file_response(request.file) + else + return 404 + end +end) +``` + +Po otwarciu adresu takiego jak `http://0.0.0.0:12345/my-extension/files/main/main.collection` w przeglądarce zobaczysz zawartość pliku `main/main.collection`. + +## Skrypty edytora w bibliotekach + +Możesz publikować biblioteki zawierające polecenia dla innych użytkowników, a edytor wykryje je automatycznie. Haki nie mogą być jednak wykrywane automatycznie, bo muszą być zdefiniowane w pliku znajdującym się w katalogu głównym projektu, podczas gdy biblioteki udostępniają tylko podkatalogi. To celowe: użytkownik powinien mieć większą kontrolę nad procesem builda. Nadal możesz definiować haki cyklu życia jako zwykłe funkcje w plikach `.lua`, a użytkownicy biblioteki mogą je potem załadować i wykorzystać w swoim `/hooks.editor_script`. + +Warto też pamiętać, że choć zależności są widoczne w Assets, nie istnieją jako zwykłe pliki — są wpisami w archiwum zip. Edytor potrafi jednak wypakować wybrane pliki z zależności do katalogu `build/plugins/`. W tym celu utwórz plik `ext.manifest` w katalogu biblioteki, a następnie katalog `plugins/bin/${platform}` w tym samym folderze, w którym znajduje się plik `ext.manifest`. Zawartość tego katalogu zostanie automatycznie wypakowana do `/build/plugins/${extension-path}/plugins/bin/${platform}`, dzięki czemu skrypty edytora będą mogły się do niej odwoływać. + +## Preferencje + +Skrypty edytora mogą definiować i używać preferencji, czyli trwałych, niezatwierdzonych danych przechowywanych na komputerze użytkownika. Preferencje mają trzy główne cechy: + +- są typowane: każda preferencja ma definicję schematu zawierającą typ danych i dodatkowe metadane, takie jak wartość domyślna; +- mają zakres: preferencje są ograniczone albo do projektu, albo do użytkownika; +- są zagnieżdżone: każdy klucz preferencji jest łańcuchem rozdzielanym kropkami, gdzie pierwszy segment identyfikuje skrypt edytora, a kolejne opisują strukturę danej preferencji. + +Wszystkie preferencje trzeba zarejestrować przez zdefiniowanie schematu: + +```lua +function M.get_prefs_schema() + return { + ["my_json_formatter.jq_path"] = editor.prefs.schema.string(), + ["my_json_formatter.indent.size"] = editor.prefs.schema.integer({default = 2, scope = editor.prefs.SCOPE.PROJECT}), + ["my_json_formatter.indent.type"] = editor.prefs.schema.enum({values = {"spaces", "tabs"}, scope = editor.prefs.SCOPE.PROJECT}), + } +end +``` + +Po przeładowaniu takiego skryptu edytor rejestruje schemat. Następnie skrypt może odczytywać i zapisywać preferencje, na przykład: + +```lua +-- Pobierz konkretną preferencję +editor.prefs.get("my_json_formatter.indent.type") +-- Zwróci: "spaces" + +-- Pobierz całą grupę preferencji +editor.prefs.get("my_json_formatter") +-- Zwróci: +-- { +-- jq_path = "", +-- indent = { +-- size = 2, +-- type = "spaces" +-- } +-- } + +-- Ustaw wiele zagnieżdżonych preferencji naraz +editor.prefs.set("my_json_formatter.indent", { + type = "tabs", + size = 1 +}) +``` + +## Tryby wykonania + +Środowisko uruchomieniowe skryptów edytora używa dwóch trybów wykonania, które w większości są przezroczyste dla samego skryptu: **immediate** i **long-running**. + +Tryb **immediate** jest używany wtedy, gdy edytor potrzebuje odpowiedzi od skryptu możliwie natychmiast. Na przykład callbacki `active` poleceń menu są wykonywane w tym trybie, ponieważ sprawdzenia aktywności odbywają się w wątku UI edytora i muszą odświeżyć interfejs w tej samej klatce. + +Tryb **long-running** jest używany wtedy, gdy odpowiedź nie musi być natychmiastowa. Na przykład callbacki `run` poleceń menu działają w trybie **long-running**, więc skrypt może poświęcić więcej czasu na wykonanie zadania. + +Niektóre funkcje dostępne dla skryptów edytora mogą wykonywać się długo. Na przykład `editor.execute("git", "status", {reload_resources=false, out="capture"})` może w dużym projekcie działać nawet sekundę. Aby zachować responsywność i wydajność edytora, takich funkcji nie wolno używać w kontekstach wymagających natychmiastowej odpowiedzi. Próba użycia ich w takim kontekście zakończy się błędem: `Cannot use long-running editor function in immediate context`. Rozwiązaniem jest unikanie tych funkcji w trybie immediate. + +Za długo działające uznawane są: + +- `editor.create_directory()`, `editor.create_resources()`, `editor.delete_directory()`, `editor.save()`, `os.remove()` i `file:write()` — modyfikują pliki na dysku, przez co edytor musi zsynchronizować drzewo zasobów w pamięci ze stanem dysku, co w dużych projektach może trwać sekundy; +- `editor.execute()` — uruchamianie poleceń powłoki może zająć nieprzewidywalnie dużo czasu; +- `editor.transact()` — duże transakcje na szeroko referencjonowanych węzłach mogą trwać setki milisekund, co jest zbyt wolne dla responsywnego UI. + +W trybie immediate działają: + +- callbacki `active` poleceń menu — edytor potrzebuje odpowiedzi w tej samej klatce UI; +- kod wykonywany na najwyższym poziomie skryptów edytora — sam proces przeładowywania skryptów nie powinien powodować skutków ubocznych. + +## Akcje + +::: sidenote +Wcześniej edytor komunikował się z maszyną Lua w sposób blokujący, więc skrypty edytora nie mogły blokować działania edytora, bo część interakcji była wykonywana z wątku UI. Z tego powodu nie było na przykład `editor.execute()` ani `editor.transact()`. Uruchamianie skryptów i zmiany stanu edytora były wtedy inicjowane przez zwracanie tablicy "actions" z hooków i callbacków `run`. + +Obecnie edytor komunikuje się z maszyną Lua w sposób nieblokujący, więc akcje nie są już potrzebne: korzystanie z funkcji takich jak `editor.execute()` jest wygodniejsze, krótsze i daje większe możliwości. Akcje są teraz **DEPRECATED**, choć nie planujemy ich usuwać. +::: + +Skrypty edytora mogą zwracać tablicę akcji z funkcji `run` poleceń albo z hooków w `/hooks.editor_script`. Edytor wykona potem te akcje. + +Action to tabela opisująca, co edytor ma zrobić. Każda akcja ma klucz `action`. Akcje występują w dwóch wariantach: z możliwością cofnięcia i bez możliwości cofnięcia. + +### Akcje z możliwością cofnięcia + +::: sidenote +Preferuj używanie `editor.transact()`. +::: + +Akcję z możliwością cofnięcia można cofnąć po jej wykonaniu. Jeśli polecenie zwraca kilka akcji tego typu, zostaną wykonane i cofnięte razem. W miarę możliwości warto ich używać, choć są bardziej ograniczone. + +Obecnie dostępne akcje z możliwością cofnięcia: + +- `"set"` — ustawia właściwość węzła w edytorze na wybraną wartość. Przykład: + ```lua + { + action = "set", + node_id = opts.selection, + property = "text", + value = "current time is " .. os.date() + } + ``` + Akcja `"set"` wymaga: + - `node_id` — identyfikatora węzła jako userdata. Alternatywnie można podać ścieżkę zasobu, na przykład `"/main/game.script"`; + - `property` — właściwości do ustawienia, na przykład `"text"`; + - `value` — nowej wartości właściwości. Dla `"text"` powinna to być wartość typu string. + +### Akcje bez możliwości cofnięcia + +::: sidenote +Preferuj używanie `editor.execute()`. +::: + +Akcja bez możliwości cofnięcia czyści historię cofania, więc jeśli chcesz ją odwrócić, musisz użyć innych metod, na przykład systemu kontroli wersji. + +Obecnie dostępne akcje bez możliwości cofnięcia: + +- `"shell"` — uruchamia skrypt powłoki. Przykład: + ```lua + { + action = "shell", + command = { + "./scripts/minify-json.sh", + editor.get(opts.selection, "path"):sub(2) -- usuń początkowy "/" + } + } + ``` + Akcja `"shell"` wymaga klucza `command`, czyli tablicy z poleceniem i argumentami. + +### Łączenie akcji i efektów ubocznych -Tabela definicji serwera językowego może określać: +Możesz mieszać akcje z możliwością cofnięcia i bez niej. Akcje są wykonywane sekwencyjnie, więc w zależności od kolejności możesz utracić możliwość cofnięcia części polecenia. -- `languages` (wymagane) — listę języków, których serwer dotyczy, zdefiniowanych [tutaj](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) (rozszerzenia plików także działają); -- `command` (wymagane) - tablicę komendy i jej argumentów -- `watched_files` - tablicę tablic z kluczami `pattern` (glob), które będą powiadomiać serwer o zmianie plików, zgodnie z powiadomieniami o [zmianie plików śledzonych](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didChangeWatchedFiles). +Zamiast zwracać akcje z funkcji, które ich oczekują, możesz też po prostu czytać i zapisywać pliki bezpośrednio przez `io.open()`. Spowoduje to przeładowanie zasobów, a to z kolei wyczyści historię cofania. diff --git a/docs/pl/manuals/editor.md b/docs/pl/manuals/editor.md index 533e6534..9f94e40f 100644 --- a/docs/pl/manuals/editor.md +++ b/docs/pl/manuals/editor.md @@ -1,163 +1,336 @@ --- -title: Edytor Defold -brief: Ta instrukcja opisuje ogólnie Edytor Defold, jak wygląda i działa oraz jak w nim się poruszać. +title: Przegląd edytora +brief: Ta instrukcja przedstawia, jak wygląda i działa edytor Defold oraz jak się po nim poruszać. --- -# Edytor Defold +# Przegląd edytora -Edytor Defold pozwala przeglądać i zarządzać plikami w Twoim projekcie w wydajny sposób. Edytowanie różnych plików otwiera odpowiednie widoki ukazujące wszystkie niezbędne informacje. +Edytor pozwala sprawnie przeglądać i modyfikować wszystkie pliki oraz foldery w projekcie gry. Po otwarciu pliku edytor wybiera odpowiedni widok dla jego typu i pokazuje powiązane informacje w osobnych panelach. ## Uruchamianie Edytora -Kiedy uruchamiasz Edytor Defold zostaje najpierw otwarte okno wyboru i tworzenia projektu. Wybierz spośród: +Po uruchomieniu edytora Defold zobaczysz ekran wyboru i tworzenia projektu. Kliknij to, co chcesz zrobić: -Home (Strona domowa) -: Kliknij, żeby zobaczyć swoje ostatnio otwierane projekty. To jest domyślny widok. +MY PROJECTS +: Tutaj znajdziesz ostatnio otwierane projekty, dzięki czemu możesz szybko do nich wrócić. To domyślny widok ekranu startowego. -New Project (Nowy Projekt) -: Kliknij, jeśli chcesz stworzyć nowy projekt. Następnie wybierz bazę swojego projektu spośród dostępnych szablonów (z zakładki *From Template*), tutoriali (*From Tutorial*) lub wypróbować jecen z przykładowych projektów (*From Sample*). + Jeśli wcześniej nie otwierałeś żadnych projektów albo usunąłeś je z listy, zobaczysz dwa przyciski. `Open From Disk…` pozwala znaleźć i otworzyć projekt przez systemową przeglądarkę plików, a `Create New Project` przełącza do zakładki `TEMPLATES`. - ![new project](images/editor/new_project.png) + ![my projects](images/editor/start_no_projects.png) - Kiedy utworzysz nowy projekt będzie on zapisany na Twoim lokalnym dysku, tak jak wszystkie zmiany, które w nim zrobisz. + Jeśli wcześniej otwierałeś już projekty, zobaczysz ich listę, jak na ilustracji poniżej: -Szczegóły dotyczące różnych zakładek znajdziesz w [instrukcji do rozpoczynania projektu](https://www.defold.com/manuals/project-setup/). + ![my projects](images/editor/start_my_projects.png) -## Widoki w Edytorze +TEMPLATES +: Zawiera puste lub prawie puste projekty startowe, przygotowane do szybkiego rozpoczęcia nowego projektu Defold dla wybranych platform albo z użyciem określonych rozszerzeń. -Edytor Defold jest podzielony na oddzielne widoki/sekcje, które zawierają specyficzne informacje. +TUTORIALS +: Zawiera projekty z samouczkami, które można uruchamiać, analizować i modyfikować, jeśli chcesz uczyć się krok po kroku. -![Editor 2](images/editor/editor2_overview.png) +SAMPLES +: Zawiera projekty przygotowane do prezentowania określonych zastosowań. -Widok *Assets* (Zasoby) -: Zawiera listę wszystkich plików projektu, reprezentowaną podobnie do systemowego eksploratora plików, zgodnie z hierarchią katalogów. Możesz klikać, przewijać i rozwijać elementy: + ![New project](images/editor/start_templates.png) - - Kliknij dwukrotnie lewym przyciskem myszki nazwę pliku, żeby otworzyć go w Edytorze. - - Przeciągaj i upuszczaj pliki, aby zmieniać ich lokalizację w strukturze projektu lub dodawać nowe pliki z dysku. - - Kliknij prawy przycisk myszki, żeby otworzyć _menu kontekstowe_, z którego możesz utworzyć nowe pliki i foldery, zmienić nazwę, usunąć czy śledzić zależności i wiele więcej. +Gdy utworzysz nowy projekt, zostanie on zapisany na lokalnym dysku, a wszystkie kolejne zmiany również będą zapisywane lokalnie. -Widok *Editor* (Edytor) +Więcej o dostępnych opcjach przeczytasz w [instrukcji o konfiguracji projektu](https://www.defold.com/manuals/project-setup/). -: Centralna sekcja wyświetla aktualnie otwarty plik w Edytorze odpowiedniem dla danego typu pliku. Wszystkie rodzaje takich Edytorów, które są wizualne pozwalają na manipulację widokiem kamery: +## Język edytora -- Przesuwanie: Alt + Lewy przycisk myszki. -- Oddalanie/przybliżanie: Alt + Prawy przycisk myszki (myszki trójprzyciskowe) lub Ctrl + Lewy przycisk myszki (jeden przycisk). Jeśli myszka ma kółko, może ono być również używane do przybliżania i oddalania. -- Obracaj w 3D: Ctrl + Lewy przycisk myszki. +W lewym dolnym rogu ekranu startowego znajduje się wybór języka. Możesz wybrać jedną z aktualnie dostępnych lokalizacji językowych od wersji Defold 1.11.2. Ta sama opcja jest dostępna także w edytorze w `File ▸ Preferences ▸ General ▸ Editor Language`. -W prawym górnym rogu Edytora aktualnie otwartego pliku (sceny) znajduje się zestaw narzędzi obsługi widoku kamery: *Move* (Przesuwanie), *Rotate* (Obracanie) and *Scale* (Skalowanie). +![Languages](images/editor/languages.png) -![toolbar](images/editor/toolbar.png) +## Panele edytora -Widok *Outline* (Zawartość pliku) -: Widok ten pokazuje zawartość aktualnie otwartego pliku, w strukturze drzewa. Odzwierciedla widok Edytora i pozwala na wykonywanie operacji na zawartości: +Edytor Defold jest podzielony na zestaw paneli, czyli widoków pokazujących określone informacje. - - Kliknij lewym przyciskem myszki aby wybrać wskazany element. Przytrzymaj klawisz Shift lub Option, żeby zaznaczyć wiele elementów. - - Przeciągaj i upuszczaj elementy, żeby zmieniać ich położenie w strukturze. Upuść obiekty gry (game object) na innym obiekcie w kolekcji, żeby stworzyć relację rodzic-dziecko. - - Kliknij prawy przycisk myszki, żeby otworzyć _menu kontekstowe_, z którego możesz utworzyć nowe komponenty, usunąć wybrane i wiele więcej. +![Editor 2](images/editor/editor_overview.png) -Widok *Properties* (Właściwości)) -: Widok ten pokazuje właściwości aktualnie wybranego komponentu, takie jak Pozycja, Rotacja, Animacja, Id, etc. +### 1. Panel Assets -Widok *Tools* (Narzędzia) -: Dolny widok pokazuje w zależności od wybranej zakładki: konsolę (ang. *Console*) wyświetlającą logi działającego programu, Edytor krzywych (ang. *Curve Editor*) umożliwiający edytowanie wykresu krzywej, używany np. przy tworzeniu efektów cząsteczkowych (particle fx), błędy budowania (ang. *Build Errors*) i wyniki wyszukiwania (ang. *Search Results*). Konsola jest również używana podczas używania zintegrowanego debuggera. +Pokazuje wszystkie pliki i foldery należące do projektu w strukturze drzewa odpowiadającej układowi na dysku. Możesz klikać i przewijać, aby poruszać się po liście. W tym widoku wykonuje się wszystkie operacje związane z plikami: -Widok *Changed Files* (Zmienione pliki): -: Widok pokazuje wszystkie pliki, które zostały zmienione, dodane lub usunięte z Twojego projektu od ostatniej zapisanej w systemie kontroli wersji zmiany (commit). This view lists any files that has been changed, added or deleted in your project. By synchronizing the project regularly you can bring your local copy in sync with what is stored in the project Git repository, that way you can collaborate within a team, and you won’t lose your work if unfortune strikes. Some file oriented operations can be performed in this view: + - Left Mouse Click, aby wybrać plik lub folder. Przytrzymując ⇧ Shift, rozszerzysz zaznaczenie, a przytrzymując Ctrl/⌘ Cmd, zaznaczysz lub odznaczysz kliknięty element. + - Double Mouse Click na pliku, aby otworzyć go w edytorze właściwym dla tego typu pliku. + - Drag and Drop, aby dodać pliki z innych miejsc na dysku do projektu albo przenosić pliki i foldery w obrębie projektu. + - Right Mouse Click, aby otworzyć _Context Menu_, z którego możesz tworzyć nowe pliki i foldery, zmieniać nazwy, usuwać elementy, śledzić zależności plików i wykonywać inne operacje. - - Double click a file to open a diff view of the file. Editor 2 opens the file in a suitable editor, just like in the assets view. - - Right click a file to open a pop up menu from where you can open a diff view, revert all changes done to the file, find the file on the filesystem and more (editor 2). +### 2. Panel edytora -## Edytowanie równolegle (Side-by-side) +Środkowy widok pokazuje aktualnie otwarty plik w edytorze odpowiednim dla jego typu. Na przykład pliki skryptów otwierają się we wbudowanym Code Editor, a komponenty wizualne w trójwymiarowym Visual Editor. Wszystkie Visual Editors pozwalają zmieniać widok kamery: -Jeśli masz otwartych kilka plików jednocześnie, dla każdego z nich pokazywana jest osobna zakładka na górnym pasku Edytora Defold. Możliwe jest również otworzenie dwóch Edytorów/.paneli naraz, jeden obok drugiego. Wybierz plik, klikająć prawym przyciskiem myszy na danej zakładce w górnym pasku i wybierz Move to Other Tab Pane z menu kontekstowego. +- Przesuwanie: Alt/⌥ Option + Left Mouse Button lub Right Mouse Button +- Przybliżanie i oddalanie: Scroll Mouse Wheel albo Alt/⌥ Option + Right Mouse Button +- Obracanie w 3D wokół zaznaczenia: Ctrl/^ Control + Left Mouse Button + +#### Pasek narzędzi + +W prawym górnym rogu widoku sceny znajduje się pasek narzędzi z narzędziami do manipulacji obiektami. Od lewej są to: + +*Move* (W), *Rotate* (E), *Scale* (R), *Grid Settings* `▦`, *Align Camera 2D/3D* `2D`, przełącznik *Camera Perspective/Orthographic* oraz *Visibility Filters* `👁`. + +![Toolbar](images/editor/toolbar.png) + +### 3. Panel Outline + +Ten widok pokazuje zawartość aktualnie edytowanego pliku w strukturze hierarchicznego drzewa. Outline odzwierciedla widok edytora i pozwala wykonywać operacje na elementach: + + - Left Mouse Click, aby zaznaczyć element. Przytrzymując ⇧ Shift, rozszerzysz zaznaczenie, a przytrzymując Ctrl/⌘ Cmd, zaznaczysz lub odznaczysz kliknięty element. + - Drag and Drop, aby przenosić elementy. Upuszczenie obiektu gry na inny obiekt gry w kolekcji tworzy relację rodzic-dziecko. + - Right Mouse Click, aby otworzyć _Context Menu_, z którego możesz dodawać elementy, usuwać zaznaczone obiekty i wykonywać inne operacje. + +Widoczność obiektów gry i komponentów wizualnych można przełączać, klikając małą ikonę oka `👁` po prawej stronie elementu na liście. Funkcja jest dostępna od Defold 1.9.8. + +![Outline](images/editor/outline.png) + +### 4. Panel Properties + +Ten widok pokazuje właściwości powiązane z aktualnie zaznaczonym elementem, na przykład Id, URL, Position, Rotation, Scale, właściwości specyficzne dla komponentu oraz własne właściwości skryptów. + +Możesz też Drag ikonę strzałki `↕` i poruszać myszą, aby zmieniać wartość danej właściwości liczbowej. Ta funkcja jest dostępna od wersji 1.10.2. + +![Properties](images/editor/properties.png) + +### 5. Panel Tools + +Ten widok zawiera kilka kart: + +*Console* +: pokazuje błędy, ostrzeżenia, informacje wypisywane przez silnik oraz komunikaty, które sam wypisujesz, gdy gra jest uruchomiona. + +*Build Errors* +: pokazuje błędy z procesu budowania. + +*Search Results* +: pokazuje wyniki wyszukiwania w całym projekcie po użyciu Ctrl/⌘ Cmd + Shift + F, jeśli klikniesz `Keep Results`. + +*Curve Editor* +: jest używany podczas edytowania krzywych w [Particle Editor](/manuals/particlefx/). + +Panel Tools służy również do pracy ze zintegrowanym debuggerem. Więcej informacji znajdziesz w [instrukcji debugowania](/manuals/debugging/). + +### 6. Panel Changed Files + +Jeśli projekt używa rozproszonego systemu kontroli wersji Git, ten widok pokazuje wszystkie pliki zmienione, dodane lub usunięte w projekcie. Regularna synchronizacja projektu pozwala utrzymywać lokalną kopię zgodną z tym, co znajduje się w repozytorium Git projektu. Dzięki temu łatwiej pracować zespołowo i uniknąć utraty efektów pracy. Więcej o Git znajdziesz w [instrukcji kontroli wersji](/manuals/version-control/). W tym widoku można wykonywać część operacji na plikach: + + - Left Mouse Click, aby wybrać plik. Przytrzymując ⇧ Shift, rozszerzysz zaznaczenie, a przytrzymując Ctrl/⌘ Cmd, zaznaczysz lub odznaczysz kliknięty element. Jeśli zaznaczony jest jeden zmieniony plik, możesz kliknąć `Diff`, aby zobaczyć różnice. Kliknięcie `Revert` cofa zmiany we wszystkich zaznaczonych plikach. + - Double Left Mouse Click na pliku, aby otworzyć jego widok. Edytor otworzy plik w odpowiednim edytorze, tak jak w panelu `Assets`. + - Right Mouse Click na pliku, aby otworzyć menu podręczne, z którego możesz wyświetlić `diff`, cofnąć wszystkie zmiany w pliku, znaleźć go w systemie plików i wykonać inne operacje. + +### Pasek menu + +Na górze widoku edytora, a na Macu w systemowym pasku menu, znajduje się pasek z sześcioma menu: `File`, `Edit`, `View`, `Project`, `Debug` i `Help`. Ich funkcje opisano w odpowiednich instrukcjach. + +### Pasek stanu + +Na dolnym pasku edytora znajduje się wąski obszar, w którym wyświetlany jest status, na przykład: + +- gdy dostępna jest nowa wersja, zobaczysz klikalny przycisk `Update Available`; patrz sekcja o aktualizowaniu edytora poniżej +- podczas budowania lub bundlowania będzie tam widoczny postęp operacji + +## Rozmiar i widoczność paneli + +Rozmiar paneli można zmieniać w edytorze przez Dragging granic pomiędzy opisanymi wyżej sześcioma panelami. + +Widoczność paneli można przełączać z menu `View` albo skrótami: + +- `Toggle Assets Pane` (F6) przełącza widoczność paneli `Assets` i `Changed Files` +- `Toggle Changed Files` przełącza widoczność samego panelu `Changed Files` +- `Toggle Tools Pane` (F7) przełącza widoczność panelu `Tools` +- `Toggle Properties Pane` (F8) przełącza widoczność paneli `Outline` i `Properties` + +![Panes Visibility](images/editor/editor_panes.png) + +W menu `View` możesz też przełączać lub zmieniać inne ustawienia widoczności, takie jak siatka, prowadnice czy kamera. Możesz też dopasować widok do zaznaczenia za pomocą `Frame Selection` lub klawisza F, a także przełączać się między domyślnym widokiem 2D i 3D za pomocą `Realign Camera` lub klawisza .. Wiele z tych funkcji jest również dostępnych z paska narzędzi albo przez skróty. + +## Zakładki + +Jeśli masz otwartych kilka plików, u góry widoku edytora pojawi się osobna zakładka dla każdego pliku. Zakładki w obrębie jednego panelu można przestawiać przez Drag and Drop, aby zamieniać ich kolejność. Możesz też: + +- Right Mouse Click na zakładce, aby otworzyć _Context Menu_ +- kliknąć `Close` (Ctrl/⌘ Cmd + W), aby zamknąć jedną zakładkę +- kliknąć `Close Others`, aby zamknąć wszystkie zakładki poza wybraną +- kliknąć `Close All` (Ctrl/⌘ Cmd + Shift + W), aby zamknąć wszystkie zakładki w aktywnym panelu +- wybrać `➝| Open As`, aby użyć innego niż domyślny edytora albo zewnętrznego narzędzia ustawionego w `File ▸ Preferences ▸ Code ▸ Custom Editor`; więcej informacji znajdziesz w [instrukcji Preferences](/manuals/editor-preferences) + +![Tabs](images/editor/tabs_custom.png) + +## Edycja obok siebie + +Możliwe jest otwarcie dwóch widoków edytora obok siebie. + +- Right Mouse Click na zakładce edytora, który chcesz przenieść, a następnie wybierz `Move to Other Tab Pane` ![2 panes](images/editor/2-panes.png) -Następnie, możesz również z tego samego menu kontekstowego wybrać opcje Swap With Other Tab Pane, żeby zamienić panele miejscami lub Join Tab Panes, żeby z powrotem połączyć panele w jeden. +Z tego samego menu zakładki możesz też użyć `Swap with Other Tab Pane`, aby przenieść wybraną zakładkę między panelami, albo `Join Tab Panes`, aby z powrotem połączyć oba panele w jeden. ## Edytor sceny -Kliknij dwukrotnie lewym przyciskiem myszki na kolekcji lub obiekcie gry, żeby otworzyć *Edytor Sceny*: +Dwukrotne kliknięcie kolekcji, obiektu gry albo pliku komponentu wizualnego otwiera *Scene Editor*. Domyślnie wszystkie sceny wizualne otwierają się w ortograficznym widoku 2D: + +![Scene Editor](images/editor/2d_scene.png) + +Jeśli pracujesz nad projektem 3D, warto zajrzeć do paska narzędzi i dostosować *Grid Settings* `▦`, na przykład przełączyć wyrównanie kamery między 2D i 3D przez `2D` lub klawisz ., ustawić wyświetlanie siatki na płaszczyźnie `Y` albo innej, która będzie dla Ciebie bardziej intuicyjna, i przełączyć kamerę na perspektywiczną za pomocą przełącznika na pasku narzędzi albo `View` ▸ `Perspective Camera`: + +![Scene Editor 3D](images/editor/3d_scene.png) + +### Manipulowanie obiektami + +Left Mouse Click na obiekcie w głównym oknie zaznacza go. Prostokąt lub prostopadłościan otaczający obiekt w widoku edytora zostanie podświetlony na kolor cyjan, aby wskazać zaznaczony element. Zaznaczony obiekt zostanie też podświetlony w widoku `Outline`, jak na ilustracji powyżej. + +Możesz też zaznaczać obiekty w następujący sposób: + + - Left Mouse Click i Drag, aby zaznaczyć wszystkie obiekty mieszczące się w obszarze zaznaczenia + - Left Mouse Click na obiektach w `Outline`; przytrzymując ⇧ Shift, rozszerzysz zaznaczenie, a przytrzymując Ctrl/⌘ Cmd, zaznaczysz lub odznaczysz kliknięty element + +#### Narzędzie Move -![Select object](images/editor/select.png) +![Move tool](images/editor/icon_move.png){.left} -Wybieranie obiektów: -: Kliknij na obiekt w głównym oknie, żeby go wybrać. Prostokąt wokół wybranego obiektu zostanie podświetlony na zielono. Wybrany obiekty zostanie również podświetlony w widoku *Outline* po prawej stronie. +Aby przesuwać obiekty, użyj *Move Tool*. Narzędzie znajduje się na pasku narzędzi w prawym górnym rogu edytora sceny albo możesz włączyć je klawiszem W. - Obiekty możesz wybierać również: +![Move object](images/editor/move.png){.inline}![Move object 3D](images/editor/move_3d.png){.inline} - - Klikając i przeciągając, żeby wybrać wszystkie obiekty w zaznaczonym, prostokątnym obszarze. - - Klikając na obiekt w widoku Outline po prawej stronie. +Gizmo zmienia się i pokazuje zestaw manipulatorów, czyli kwadratów i strzałek. Zaznaczony manipulator zmienia kolor na pomarańczowy. Możesz je Drag, aby przesuwać obiekty: - Naciśnij i przytrzymaj Shift lub ⌘ (Mac) / Ctrl (Win/Linux) podczas wybierania obiektów, aby wybrać więcej na raz. +- środkowy cyjanowy kwadrat przesuwa obiekt tylko w przestrzeni ekranu +- trzy czerwone, zielone i niebieskie strzałki przesuwają obiekt tylko wzdłuż odpowiednio osi X, Y i Z +- trzy czerwone, zielone i niebieskie kwadratowe uchwyty przesuwają obiekt tylko po wybranej płaszczyźnie, na przykład X-Y (niebieska), a po obróceniu kamery w 3D także X-Z (zielona) i Y-Z (czerwona) -Narzędzie przesuwania (Move) -: ![Move tool](images/editor/icon_move.png){.left} - Do przesuwania obiektów można użyć narzędzia przesuwania *Move*. Znajdziesz je w pasku narzędzi w prawym górnym rogu Edytora sceny lub klikając klawisz W. +#### Narzędzie Rotate - ![Move object](images/editor/move.png) +![Rotate tool](images/editor/icon_rotate.png){.left} - Nad wybranym obiektem wyświetla się zestaw wizualnych manipulatorów (kwadraty i strzałki). Klikaj i przeciągaj środkowym kwadratem, aby dowolnie przesuwać obiektem po ekranie lub klikaj i przeciągaj pojedyncze strzałki, aby przesuwać obiekt tylko wzdłuż wybranej osi. Są tutaj również kwadratowe wskaźniki umożliwiające poruszanie się po płaszczyznach XY oraz X-Z i Y-Z (widoczne po obróceniu kamery). +Aby obracać obiekty, użyj *Rotate Tool*, wybierając je na pasku narzędzi albo naciskając E. -Narzędzie obracania (Rotate) -: ![Rotate tool](images/editor/icon_rotate.png){.left} - Do obracania obiektów, można użyć narzędzia obracania *Rotate* wybierając je z górnego paska narzędzi lub naciskając klawisz E. +![Rotate object](images/editor/rotate.png){.inline}![Rotate object 3D](images/editor/rotate_3d.png){.inline} - ![Move object](images/editor/rotate.png) +To narzędzie składa się z czterech okrągłych manipulatorów, które możesz Drag, aby obracać obiekt. Zaznaczony manipulator zmienia kolor na pomarańczowy: - Nad wybranym obiektem wyświetla się zestaw wizualnych, okrągłych manipulatorów. Pomarańczowy manipulator obraca obiektem w płaszczyźnie ekranu, a pozostałe wokół osi X, Y i Z. Pamiętaj, że domyślny widok jest prostopadły do osi X i Y, więc okręgi służące do obrotu wokół tych osi są widoczne wtedy po prostu jako linie. +- zewnętrzny, największy, cyjanowy manipulator obraca obiekt w płaszczyźnie ekranu +- trzy mniejsze czerwone, zielone i niebieskie manipulatory pozwalają obracać osobno wokół osi X, Y i Z; w widoku ortograficznym 2D dwa z nich są prostopadłe do osi X i Y, więc są widoczne tylko jako linie przecinające obiekt -Narzędzie skalowania (Scale) -: ![Scale tool](images/editor/icon_scale.png){.left} - Do skalowania obiektów, można użyć narzędzia skalowania *Scale* wybierając je z górnego paska narzędzi lub naciskając klawisz R. +#### Narzędzie Scale - ![Scale object](images/editor/scale.png) +![Scale tool](images/editor/icon_scale.png){.left} - Nad wybranym obiektem wyświetla się zestaw wizualnych, kwadratowych manipulatorów. Środkowy kwadrat skaluje obiekt jednakowo wzdłuż każdej z osi (włącznie z osią Z), a pozostałe odpowiednio wokół osi X, Y i Z. Oprócz tego pokazane są wtedy również kwadraty pozwalające na skalowanie wzdłuż dwóch osi jednocześnie, parami: X-Y, X-Z i Y-Z. +Aby skalować obiekty, użyj *Scale Tool*, wybierając je na pasku narzędzi albo naciskając R. -## Tworzenie nowego pliku +![Scale object](images/editor/scale.png){.inline}![Scale object 3D](images/editor/scale_3d.png){.inline} -Żeby utworzyć nowy plik kliknij z górnego menu File ▸ New... i wybierz typ pliku z menu lub użyj menu kontekstowego: +To narzędzie składa się z zestawu kwadratowych i sześciennych manipulatorów, które możesz Drag, aby skalować obiekty. Zaznaczony manipulator zmienia kolor na pomarańczowy: -Kliknij prawy przycisk myszki na docelowej lokalizacji w panelu *Assets* po lewej stronie i wybierz New... ▸ [file type]: +- środkowy cyjanowy sześcian skaluje obiekt równomiernie we wszystkich osiach, także w osi Z +- trzy czerwone, niebieskie i zielone manipulatory składające się z sześcianów skalują obiekt osobno wzdłuż osi X, Y i Z +- trzy czerwone, niebieskie i zielone manipulatory składające się z sześcianów skalują obiekt osobno w płaszczyznach X-Y, X-Z i Y-Z + +### Filtry widoczności + +Kliknij ikonę oka `👁` na pasku narzędzi, aby przełączać widoczność różnych typów komponentów oraz obwiedni i linii pomocniczych. `Component Guides` ma też skrót Ctrl + H w Windows/Linux lub ^ Ctrl + ⌘ Cmd + H na Macu. + +![Visibility filters](images/editor/visibilityfilters.png) + +## Tworzenie nowych plików projektu + +Aby utworzyć nowy plik zasobu, wybierz `File ▸ New…`, a następnie typ pliku z menu albo użyj menu kontekstowego: + +Right Mouse Click w docelowym miejscu w przeglądarce `Assets`, a następnie wybierz `New… ▸ [file type]`: ![create file](images/editor/create_file.png) -Podaj odpowiednią nazwę dla pliku. Pełna nazwa pliku uwzględniająca końcówkę znajduję się w polu *Path* (ścieżka) w oknie dialogowym: +Wpisz odpowiednią *Name* dla nowego pliku, a w razie potrzeby zmień *Location*. Pełna nazwa pliku wraz z rozszerzeniem jest pokazywana w polu *Preview* w oknie dialogowym: ![create file name](images/editor/create_file_name.png) +## Szablony + +Możesz zdefiniować własne szablony dla każdego projektu. W tym celu utwórz w katalogu głównym projektu folder `templates` i dodaj do niego pliki `default.*` z odpowiednimi rozszerzeniami, na przykład `/templates/default.gui` albo `/templates/default.script`. Dodatkowo, jeśli w tych plikach użyjesz znacznika `{{NAME}}`, zostanie on zastąpiony nazwą pliku podaną w oknie tworzenia pliku. + +Jeśli dla danego typu pliku istnieje szablon, każdy nowo tworzony plik tego typu zostanie zainicjalizowany zawartością odpowiedniego pliku z katalogu `templates`. + +![Templates](images/editor/templates.png) + ## Importowanie plików do projektu -Aby dodać pliki (obrazki, dźwięki, modele, itp.) do Twojego projektu, po prostu przeciągnij i upuść je w odpowiednim miejscu w panelu *Assets* po lewej stronie. Utworzysz w ten sposób _kopię_ danego pliku w docelowej lokalizacji projektu. Przeczytaj więcej na temat [importowania plików w tej instrukcji](/manuals/importing-assets/). +Aby dodać do projektu pliki zasobów, takie jak obrazy, dźwięki czy modele, po prostu przeciągnij je i upuść we właściwe miejsce w przeglądarce *Assets*. Spowoduje to utworzenie _kopii_ plików w wybranej lokalizacji w strukturze projektu. Więcej informacji znajdziesz w [instrukcji importowania zasobów](/manuals/importing-assets/). ![Import files](images/editor/import.png) -## Aktualizowanie Edytora +## Aktualizowanie edytora -Edytor automatycznie wyszukuje aktualizacje, jeśli ma dostęp do internetu. Kiedy aktualizacja jest dostępna, informacja o możliwości zaktualizowania pojawi się w prawym dolnym rogu Edytora i na stronie startowej z wyborem projektu. Naciśnięcie przycisku `Update Available` spowoduje pobranie aktualizacji i zainstalowanie jej. +Edytor automatycznie sprawdza aktualizacje, gdy ma połączenie z internetem. Gdy wykryje nową wersję, w lewym dolnym rogu ekranu wyboru projektu albo w prawym dolnym rogu okna edytora pojawi się niebieski klikalny odnośnik `Update Available`. -![Update from project selection](images/editor/update-project-selection.png) +![Update from project selection](images/editor/update_start.png) +![Update from Editor](images/editor/update_available.png) -![Update from editor](images/editor/update-main.png) +Kliknij odnośnik `Update Available`, aby pobrać i zainstalować aktualizację. Pojawi się okno potwierdzenia z dodatkowymi informacjami. Kliknij `Download Update`, aby kontynuować. -## Skróty klawiszowe +![Update Editor popup](images/editor/update.png) -Skróty opisane są w [instrukcji o skrótach klawiszowych](/manuals/editor-keyboard-shortcuts). +Postęp pobierania będzie widoczny na dolnym pasku stanu: -## Logi Edytora -Jeśli napotkasz jakiekolwiek problemy z Edytorem Defold warto [to zaraportować](/manuals/getting-help/#getting-help). Dobrą pkratyką jest dodanie plików z logami z Edytora. Można je znaleźć tutaj: +![Download progress](images/editor/download_status.png) - * Windows: `C:\Użytkownicy\ **Twoja nazwa użytkownika** \AppData\Local\Defold` (ang: `C:\Users\ **Your Username** \AppData\Local\Defold`) - * macOS: `/Users/ **Your Username** /Library/Application Support/` or `~/Library/Application Support/Defold` - * Linux: `~/.Defold` +Po pobraniu aktualizacji niebieski odnośnik zmieni się na `Restart to Update`. Kliknij go, aby ponownie uruchomić i otworzyć zaktualizowany edytor. -Można też dostać się do logów, kiedy Edytor jest uruchomiony z linii poleceń lub terminalu. Aby uruchomić Edytor z terminalu w systemie macOS użyj komendy: +![Restart to update](images/editor/restart_to_update.png) +## Preferencje + +Ustawienia edytora możesz zmieniać w oknie `Preferences`. Aby je otworzyć, kliknij `File ▸ Preferences…` albo użyj skrótu Ctrl/⌘ Cmd + ,. + +Więcej szczegółów znajdziesz w [instrukcji Preferencje](/manuals/editor-preferences). + +![Preferences](images/editor/preferences.png) + +## Logi edytora + +Jeśli napotkasz problem z edytorem i chcesz zgłosić błąd przez `Help ▸ Report Issue`, warto dołączyć pliki logów samego edytora. Aby otworzyć ich lokalizację w systemowej przeglądarce plików, kliknij `Help ▸ Show Logs`. + +Więcej informacji znajdziesz w [instrukcji uzyskiwania pomocy](/manuals/getting-help/#getting-help). + +![Show Logs](images/editor/show_logs.png) + +Pliki logów edytora można znaleźć tutaj: + + * Windows: `C:\Users\ **Your Username** \AppData\Local\Defold` + * macOS: `/Users/ **Your Username** /Library/Application Support/` albo `~/Library/Application Support/Defold` + * Linux: `$XDG_STATE_HOME/Defold` albo `~/.local/state/Defold` + +Możesz też uzyskać dostęp do logów edytora, gdy uruchomisz go z terminala lub wiersza poleceń. Aby uruchomić edytor, użyj polecenia: + +```shell +# Linux: +$ ./path/to/Defold/Defold + +# macOS: +$ ./path/to/Defold.app/Contents/MacOS/Defold ``` -$ > ./path/to/Defold.app/Contents/MacOS/Defold + +## Serwer edytora + +Gdy edytor otwiera projekt, uruchamia serwer WWW na losowym porcie. Serwer może służyć do komunikacji z edytorem z poziomu innych aplikacji. Od wersji 1.11.0 numer portu jest zapisywany w pliku `.internal/editor.port`. + +Dodatkowo od wersji 1.11.0 plik wykonywalny edytora obsługuje opcję wiersza poleceń `--port` lub `-p`, która pozwala wskazać port przy uruchamianiu. Na przykład: + +```shell +# Windows +.\path\to\Defold\Defold.exe --port 8181 + +# Linux: +./path/to/Defold/Defold --port 8181 + +# macOS: +./path/to/Defold/Defold.app/Contents/MacOS/Defold --port 8181 ``` +## Stylizacja edytora + +Wygląd edytora można zmieniać za pomocą własnej stylizacji. Więcej informacji znajdziesz w [instrukcji stylizacji edytora](/manuals/editor-styling.md). ## FAQ :[Editor FAQ](../shared/editor-faq.md) diff --git a/docs/pl/manuals/extender-docker-images.md b/docs/pl/manuals/extender-docker-images.md new file mode 100644 index 00000000..e3b3cefd --- /dev/null +++ b/docs/pl/manuals/extender-docker-images.md @@ -0,0 +1,46 @@ +--- +title: Dostępne obrazy Docker +brief: Ten dokument opisuje dostępne obrazy Docker oraz wersje Defold, które z nich korzystały. +--- + +# Dostępne obrazy Docker +Poniżej znajduje się lista wszystkich dostępnych obrazów Docker w publicznym rejestrze. Można ich używać do uruchamiania usługi Extender w środowisku ze starszymi SDK, które nie są już wspierane. + +|SDK |Tag obrazu |Nazwa platformy (w konfiguracji usługi Extender) |Wersja Defold, która korzystała z obrazu | +|------------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------|-----------------------------------------| +|Linux latest |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-linux-env:latest` |`linux-latest` |Wszystkie wersje Defold | +|Android NDK25 |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-android-ndk25-env:latest` |`android-ndk25` |Od 1.4.3 | +|Emscripten 2.0.11 |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-emsdk-2011-env:latest` |`emsdk-2011` |Do 1.7.0 | +|Emscripten 3.1.55 |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-emsdk-3155-env:latest` |`emsdk-3155` |[1.8.0-1.9.3] | +|Emscripten 3.1.65 |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-emsdk-3165-env:latest` |`emsdk-3165` |Od 1.9.4 | +|Winsdk 2019 |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-winsdk-2019-env:latest` |`winsdk-2019` |Do 1.6.1 | +|Winsdk 2022 |`europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-winsdk-2022-env:latest` |`winsdk-2022` |Od 1.6.2 | + +# Jak używać starszych obrazów Docker +Aby użyć starszego środowiska, wykonaj poniższe kroki: +1. Zmodyfikuj `docker-compose.yml` z repozytorium Extender [odnośnik](https://github.com/defold/extender/blob/dev/server/docker/docker-compose.yml). Trzeba dodać jeszcze jedną definicję usługi z potrzebnym obrazem Docker. Na przykład jeśli chcesz użyć obrazu Docker zawierającego Emscripten 2.0.11, dodaj poniższą definicję usługi: + ```yml + emscripten_2011-dev: + image: europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-emsdk-2011-env:latest + extends: + file: common-services.yml + service: remote_builder + profiles: + - all + - web + networks: + default: + aliases: + - emsdk-2011 + ``` + Najważniejsze pola: + * **profiles** - lista profili uruchamiających usługę. Nazwy profili przekazuje się do polecenia `docker compose` za pomocą argumentu `--profile `. + * **networks** - lista sieci, z których powinien korzystać kontener Docker. Do uruchomienia usługi Extender używana jest sieć o nazwie `default`. Ważne jest ustawienie aliasów sieciowych usługi, ponieważ będą używane w późniejszej konfiguracji Extender. +2. Dodaj definicję zdalnego buildera w [`application-local-dev-app.yml`](https://github.com/defold/extender/blob/dev/server/configs/application-local-dev-app.yml) w sekcji `extender.remote-builder.platforms`. W tym przykładzie będzie ona wyglądać tak: + ```yml + emsdk-2011: + url: http://emsdk-2011:9000 + instanceId: emsdk-2011 + ``` + Adres URL powinien mieć postać `http://:9000`, gdzie `service_network_alias` to alias sieciowy ze kroku 1. 9000 to standardowy port usługi Extender (może być inny, jeśli korzystasz z niestandardowej konfiguracji Extender). +3. Uruchom lokalny Extender zgodnie z opisem w sekcji [Jak uruchomić lokalny Extender z prekonfigurowanymi artefaktami](/manuals/extender-local-setup#how-to-run-local-extender-with-preconfigured-artifacts). diff --git a/docs/pl/manuals/extender-local-setup.md b/docs/pl/manuals/extender-local-setup.md new file mode 100644 index 00000000..69beab06 --- /dev/null +++ b/docs/pl/manuals/extender-local-setup.md @@ -0,0 +1,133 @@ +--- +title: Konfiguracja lokalnego serwera budowania +brief: Instrukcja opisuje, jak skonfigurować i uruchomić lokalny serwer budowania +--- + +# Konfiguracja lokalnego serwera budowania + +Istnieją dwa sposoby uruchomienia lokalnego serwera budowania, znanego też jako Extender: +1. Uruchomienie lokalnego serwera budowania z wcześniej przygotowanymi artefaktami. +2. Uruchomienie lokalnego serwera budowania z artefaktami zbudowanymi lokalnie. + +## Jak uruchomić lokalny Extender ze wstępnie skonfigurowanymi artefaktami + +Zanim uruchomisz lokalny serwer budowania, musisz zainstalować następujące oprogramowanie: + +* [Docker](https://www.docker.com/) - Docker to zestaw produktów typu platform as a service, które wykorzystują wirtualizację na poziomie systemu operacyjnego do dostarczania oprogramowania w pakietach zwanych kontenerami. Aby uruchamiać lokalnie serwery budowania w chmurze na swojej maszynie deweloperskiej, musisz zainstalować [Docker Desktop](https://www.docker.com/products/docker-desktop/) +* Google Cloud CLI - Google Cloud CLI to zestaw narzędzi do tworzenia zasobów Google Cloud i zarządzania nimi. Narzędzia można [zainstalować bezpośrednio od Google](https://cloud.google.com/sdk/docs/install) albo z menedżera pakietów, takiego jak Brew, Chocolatey lub Snap. +* Potrzebujesz też konta Google, aby pobierać kontenery z platformowymi serwerami budowania. + +Po zainstalowaniu powyższego oprogramowania wykonaj poniższe kroki, aby zainstalować i uruchomić chmurowe serwery budowania Defold: + +**Uwaga dla użytkowników Windows**: do wykonania poniższych poleceń użyj terminala Git Bash. + +1. __Autoryzuj się w Google Cloud i utwórz Application default credentials__ - Podczas pobierania obrazów kontenerów Docker musisz mieć konto Google, abyśmy mogli monitorować korzystanie z publicznego rejestru kontenerów, dbać o uczciwe korzystanie z zasobów i tymczasowo zawieszać konta, które pobierają obrazy w nadmiernej liczbie. + + ```sh + gcloud auth login + ``` +2. __Skonfiguruj Docker do używania Artifact Registry__ - Docker musi być skonfigurowany tak, aby podczas pobierania obrazów kontenerów z publicznego rejestru kontenerów pod adresem `europe-west1-docker.pkg.dev` używał `gcloud` jako pomocnika poświadczeń. + + ```sh + gcloud auth configure-docker europe-west1-docker.pkg.dev + ``` +3. __Sprawdź, czy Docker i Google Cloud są poprawnie skonfigurowane__ - Potwierdź, że Docker i Google Cloud zostały poprawnie skonfigurowane, pobierając obraz bazowy używany przez wszystkie obrazy kontenerów serwera budowania. Zanim uruchomisz poniższe polecenie, upewnij się, że Docker Desktop działa: + ```sh + docker pull --platform linux/amd64 europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-base-env:latest + ``` +4. __Sklonuj repozytorium Extender__ - Gdy Docker i Google Cloud są już poprawnie skonfigurowane, jesteśmy prawie gotowi do uruchomienia serwera. Zanim go uruchomimy, musimy sklonować repozytorium Git zawierające serwer budowania: + ```sh + git clone https://github.com/defold/extender.git + cd extender + ``` +5. __Pobierz gotowe pliki JAR__ - Następnym krokiem jest pobranie gotowego serwera (`extender.jar`) i narzędzia do scalania manifestów (`manifestmergetool.jar`): + ```sh + TMP_DIR=$(pwd)/server/_tmp + APPLICATION_DIR=$(pwd)/server/app + # ustaw wymaganą wersję Extender i Manifest merge tool + # wersje znajdziesz na stronie wydań GitHub: https://github.com/defold/extender/releases + # albo możesz pobrać najnowszą wersję (zobacz przykład kodu poniżej) + EXTENDER_VERSION=2.6.5 + MANIFESTMERGETOOL_VERSION=1.3.0 + echo "Pobieranie gotowych plików JAR do ${APPLICATION_DIR}" + rm -rf ${TMP_DIR} + mkdir -p ${TMP_DIR} + rm -rf ${APPLICATION_DIR} + mkdir -p ${APPLICATION_DIR} + + gcloud artifacts files download \ + --project=extender-426409 \ + --location=europe-west1 \ + --repository=extender-maven \ + --destination=${TMP_DIR} \ + com/defold/extender/server/${EXTENDER_VERSION}/server-${EXTENDER_VERSION}.jar + + gcloud artifacts files download \ + --project=extender-426409 \ + --location=europe-west1 \ + --repository=extender-maven \ + --destination=${TMP_DIR} \ + com/defold/extender/manifestmergetool/${MANIFESTMERGETOOL_VERSION}/manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar + + cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep server-${EXTENDER_VERSION}.jar) ${APPLICATION_DIR}/extender.jar + cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar) ${APPLICATION_DIR}/manifestmergetool.jar + ``` +6. __Uruchom serwer__ - Możemy teraz uruchomić serwer, wykonując główne polecenie `docker compose`: +```sh +docker compose -p extender -f server/docker/docker-compose.yml --profile up +``` +gdzie *profile* może mieć jedną z następujących wartości: +* **all** - uruchamia zdalne instancje dla każdej platformy +* **android** - uruchamia instancję frontendu i zdalne instancje do budowania wersji Android +* **web** - uruchamia instancję frontendu i zdalne instancje do budowania wersji Web +* **linux** - uruchamia instancję frontendu i zdalne instancje do budowania wersji Linux +* **windows** - uruchamia instancję frontendu i zdalne instancje do budowania wersji Windows +* **consoles** - uruchamia instancję frontendu i zdalne instancje do budowania wersji Nintendo Switch/PS4/PS5 +* **nintendo** - uruchamia instancję frontendu i zdalne instancje do budowania wersji Nintendo Switch +* **playstation** - uruchamia instancję frontendu i zdalne instancje do budowania wersji PS4/PS5 +* **metrics** - uruchamia VictoriaMetrics i Grafana jako backend metryk oraz narzędzie do wizualizacji +Więcej informacji o argumentach `docker compose` znajdziesz pod adresem https://docs.docker.com/reference/cli/docker/compose/. + +Gdy docker compose działa, możesz użyć **http://localhost:9000** jako adresu Build Server w preferencjach edytora albo jako wartości `--build-server`, jeśli do budowania projektu używasz Boba. + +Do polecenia można przekazać kilka profili. Na przykład: +```sh +docker compose -p extender -f server/docker/docker-compose.yml --profile android --profile web --profile windows up +``` +Powyższy przykład uruchamia instancję frontendu oraz instancje Android, Web i Windows. + +Aby zatrzymać usługi, naciśnij Ctrl+C, jeśli docker compose działa w trybie nieodłączonym, albo +```sh +docker compose -p extender down +``` +jeśli docker compose uruchomiono w trybie odłączonym, na przykład z przekazaną flagą -d do polecenia `docker compose up`. + +Jeśli chcesz pobrać najnowsze wersje plików JAR, możesz użyć poniższego polecenia, aby ustalić ich najnowsze wersje: +```sh + EXTENDER_VERSION=$(gcloud artifacts versions list \ + --project=extender-426409 \ + --location=europe-west1 \ + --repository=extender-maven \ + --package="com.defold.extender:server" \ + --sort-by="~createTime" \ + --limit=1 \ + --format="value(name)") + + MANIFESTMERGETOOL_VERSION=$(gcloud artifacts versions list \ + --project=extender-426409 \ + --location=europe-west1 \ + --repository=extender-maven \ + --package="com.defold.extender:manifestmergetool" \ + --sort-by="~createTime" \ + --limit=1 \ + --format="value(name)") +``` + +### A co z macOS i iOS? + +Kompilacje dla macOS i iOS są wykonywane na prawdziwym sprzęcie Apple przy użyciu serwera budowania działającego w trybie stand-alone, bez Dockera. Zamiast tego Xcode, Java i inne wymagane narzędzia są instalowane bezpośrednio na maszynie, a serwer budowania działa jako zwykły proces Java. Jak to skonfigurować, dowiesz się z [dokumentacji serwera budowania na GitHub](https://github.com/defold/extender?tab=readme-ov-file#running-as-a-stand-alone-server-on-macos). + + +## Jak uruchomić lokalny Extender z artefaktami zbudowanymi lokalnie + +Aby ręcznie zbudować i uruchomić lokalny serwer budowania, postępuj zgodnie z [instrukcjami w repozytorium Extender na GitHub](https://github.com/defold/extender). diff --git a/docs/pl/manuals/extensions-best-practices.md b/docs/pl/manuals/extensions-best-practices.md new file mode 100644 index 00000000..33b70cca --- /dev/null +++ b/docs/pl/manuals/extensions-best-practices.md @@ -0,0 +1,127 @@ +--- +title: Rozszerzenia natywne - dobre praktyki +brief: Ta instrukcja opisuje dobre praktyki przy tworzeniu rozszerzeń natywnych. +--- + +# Dobre praktyki + +Pisanie kodu wieloplatformowego bywa trudne, ale istnieją sposoby, aby ułatwić zarówno jego tworzenie, jak i utrzymanie. + + +## Struktura projektu + +Przy tworzeniu rozszerzenia warto zadbać o kilka rzeczy, które pomagają zarówno w jego rozwijaniu, jak i późniejszym utrzymaniu. + +### API Lua + +Powinno istnieć tylko jedno API Lua i jedna jego implementacja. Dzięki temu znacznie łatwiej zapewnić takie samo działanie na wszystkich platformach. + +Jeśli dana platforma nie powinna obsługiwać rozszerzenia, zaleca się po prostu nie rejestrować modułu Lua. Dzięki temu można wykryć obsługę, sprawdzając nil: + +```lua + if myextension ~= nil then + myextension.do_something() + end +``` + +### Struktura folderów + +W rozszerzeniach często stosuje się następującą strukturę folderów: + +``` + /root + /input + /main -- Wszystkie pliki właściwego projektu przykładowego + /... + /myextension -- Rzeczywisty katalog główny rozszerzenia + ext.manifest + /include -- Zewnętrzne pliki include używane przez inne rozszerzenia + /libs + / -- Zewnętrzne biblioteki dla wszystkich obsługiwanych platform + /src + myextension.cpp -- API Lua rozszerzenia i funkcje cyklu życia rozszerzenia + Zawiera też ogólne implementacje funkcji API Lua. + myextension_private.h -- Twoje wewnętrzne API, które zaimplementuje każda platforma (np. `myextension_Init` itd.) + myextension.mm -- Potrzebny, jeśli dla iOS/macOS są wymagane natywne wywołania. Implementuje `myextension_Init` itd. dla iOS/macOS + myextension_android.cpp -- Potrzebny, jeśli dla Androida są wymagane wywołania JNI. Implementuje `myextension_Init` itd. dla Androida + /java + / -- Dowolne pliki Java potrzebne dla Androida + /res -- Dowolne zasoby potrzebne dla danej platformy + /external + README.md -- Notatki/skrypty dotyczące tego, jak budować lub pakować zewnętrzne biblioteki + /bundleres -- Zasoby, które powinny zostać dołączone do bundla (zob. game.project oraz [bundle_resources setting]([physics scale setting](/manuals/project-settings/#project)) + / + game.project + game.appmanifest -- Dodatkowe informacje o konfiguracji aplikacji +``` + +Zwróć uwagę, że `myextension.mm` i `myextension_android.cpp` są potrzebne tylko wtedy, gdy wykonujesz konkretne natywne wywołania dla danej platformy. + +#### Foldery platform + +W niektórych miejscach architektura platformy jest używana jako nazwa folderu, aby określić, których plików użyć podczas kompilacji lub bundlowania aplikacji. Mają one postać: + + - + +Aktualna lista to: + + arm64-ios, armv7-ios, x86_64-ios, arm64-android, armv7-android, x86_64-linux, x86_64-osx, x86_64-win32, x86-win32 + +Na przykład biblioteki specyficzne dla platformy umieszczaj w: + + /libs + /arm64-ios + /libFoo.a + /arm64-android + /libFoo.a + + +## Pisanie kodu natywnego + +W kodzie źródłowym Defold C++ jest używany bardzo oszczędnie, a większość kodu ma bardzo C-podobny charakter. Szablonów prawie się tam nie stosuje, z wyjątkiem kilku klas kontenerów, ponieważ szablony zwiększają zarówno czas kompilacji, jak i rozmiar pliku wykonywalnego. + +### Wersja C++ + +Kod źródłowy Defold jest budowany z użyciem domyślnej wersji C++ każdego kompilatora. Sam kod źródłowy Defold nie używa wersji C++ wyższej niż C++98. Chociaż do zbudowania rozszerzenia można użyć nowszej wersji, może ona wiązać się ze zmianami ABI. To może uniemożliwić używanie jednego rozszerzenia razem z innymi rozszerzeniami w silniku lub z [asset portal](/assets). + +Kod źródłowy Defold unika korzystania z najnowszych funkcji i wersji C++. Głównie dlatego, że przy tworzeniu silnika gier nie ma potrzeby wprowadzania nowych funkcji, ale też dlatego, że śledzenie najnowszych możliwości C++ jest czasochłonne, a ich naprawdę dobre opanowanie wymagałoby dużo cennego czasu. + +Ma to też dodatkową korzyść dla twórców rozszerzeń: Defold utrzymuje stabilne ABI. Warto również podkreślić, że używanie najnowszych funkcji C++ może uniemożliwić kompilację kodu na różnych platformach z powodu różnego poziomu wsparcia. + +### Bez wyjątków C++ + +Defold nie korzysta z wyjątków w silniku. Wyjątków z reguły unika się w silnikach gier, ponieważ dane są w większości znane wcześniej, na etapie tworzenia. Wyłączenie obsługi wyjątków C++ zmniejsza rozmiar pliku wykonywalnego i poprawia wydajność działania. + +### Standard Template Libraries - STL + +Ponieważ silnik Defold nie używa kodu STL, poza niektórymi algorytmami i matematyką (`std::sort`, `std::upper_bound` itd.), użycie STL w twoim rozszerzeniu może się sprawdzić. + +Pamiętaj jednak, że niezgodności ABI mogą utrudnić używanie twojego rozszerzenia razem z innymi rozszerzeniami lub bibliotekami firm trzecich. + +Unikanie bibliotek STL, które w dużym stopniu opierają się na szablonach, poprawia też czas budowania, a co ważniejsze, zmniejsza rozmiar pliku wykonywalnego. + +#### Ciągi znaków + +W silniku Defold zamiast `std::string` używa się `const char*`. Używanie `std::string` jest częstą pułapką przy mieszaniu różnych wersji C++ lub wersji kompilatorów, ponieważ może prowadzić do niedopasowania ABI. Użycie `const char*` i kilku funkcji pomocniczych pozwala tego uniknąć. + +### Ukrywaj funkcje + +Jeśli to możliwe, używaj słowa kluczowego `static` dla funkcji lokalnych względem danej jednostki kompilacji. Pozwala to kompilatorowi na pewne optymalizacje, co może zarówno poprawić wydajność, jak i zmniejszyć rozmiar pliku wykonywalnego. + +## Biblioteki firm trzecich + +Wybierając bibliotekę firm trzecich do użycia, niezależnie od języka, rozważ następujące kwestie: + +* Funkcjonalność - Czy rozwiązuje konkretny problem, który masz? +* Wydajność - Czy powoduje narzut wydajnościowy podczas działania? +* Rozmiar biblioteki - O ile większy będzie końcowy plik wykonywalny? Czy to akceptowalne? +* Zależności - Czy wymaga dodatkowych bibliotek? +* Wsparcie - W jakim stanie jest biblioteka? Czy ma wiele otwartych zgłoszeń? Czy jest nadal utrzymywana? +* Licencja - Czy można jej użyć w tym projekcie? + + +## Zależności open source + +Zawsze upewnij się, że masz dostęp do swoich zależności. Na przykład jeśli zależysz od czegoś na GitHubie, nic nie stoi na przeszkodzie, aby to repozytorium zostało usunięte albo nagle zmieniło kierunek rozwoju lub właściciela. Możesz ograniczyć to ryzyko, tworząc fork repozytorium i używając własnego forka zamiast projektu upstream. + +Pamiętaj, że kod z biblioteki zostanie wstrzyknięty do twojej gry, więc upewnij się, że biblioteka robi to, co powinna, i nic więcej! diff --git a/docs/pl/manuals/extensions-cocoapods.md b/docs/pl/manuals/extensions-cocoapods.md new file mode 100644 index 00000000..08dddad9 --- /dev/null +++ b/docs/pl/manuals/extensions-cocoapods.md @@ -0,0 +1,27 @@ +--- +title: Używanie zależności CocoaPods w kompilacjach na iOS i macOS +brief: Ta instrukcja wyjaśnia, jak używać CocoaPods do rozwiązywania zależności w kompilacjach na iOS i macOS. +--- + +# CocoaPods + +[CocoaPods](https://cocoapods.org/) to menedżer zależności dla projektów Cocoa w Swift i Objective-C. CocoaPods jest zwykle używany do zarządzania zależnościami i integrowania ich w projektach Xcode. Defold nie używa Xcode podczas budowania na iOS i macOS, ale nadal używa CocoaPods do rozwiązywania zależności na serwerze buildów. + + +## Rozwiązywanie zależności + +Rozszerzenia natywne mogą zawierać plik `Podfile` w folderach `manifests/ios` i `manifests/osx`, aby określić zależności rozszerzenia. Przykład: + +``` +platform :ios '11.0' + +pod 'FirebaseCore', '10.22.0' +pod 'FirebaseInstallations', '10.22.0' +``` + +Serwer buildów zbierze pliki `Podfile` ze wszystkich rozszerzeń i użyje ich do rozwiązania wszystkich zależności oraz dołączenia ich podczas budowania kodu natywnego. + +Przykłady: + +* [Firebase](https://github.com/defold/extension-firebase/blob/master/firebase/manifests/ios/Podfile) +* [Facebook](https://github.com/defold/extension-facebook/blob/master/facebook/manifests/ios/Podfile) diff --git a/docs/pl/manuals/extensions-debugging-android.md b/docs/pl/manuals/extensions-debugging-android.md new file mode 100644 index 00000000..d9995ca2 --- /dev/null +++ b/docs/pl/manuals/extensions-debugging-android.md @@ -0,0 +1,6 @@ +--- +title: Debugowanie na Androidzie +brief: Ta instrukcja opisuje, jak debugować kompilację uruchomioną na urządzeniu z Androidem. +--- + +Przeniesiono do [podręcznika o debugowaniu kodu natywnego na Androidzie](/manuals/debugging-native-code-android). diff --git a/docs/pl/manuals/extensions-debugging-ios.md b/docs/pl/manuals/extensions-debugging-ios.md new file mode 100644 index 00000000..9e00ae0e --- /dev/null +++ b/docs/pl/manuals/extensions-debugging-ios.md @@ -0,0 +1,6 @@ +--- +title: Debugowanie na iOS/macOS +brief: Ta instrukcja opisuje, jak debugować kompilację za pomocą Xcode. +--- + +Przeniesiono do [podręcznika o debugowaniu kodu natywnego na iOS](/manuals/debugging-native-code-ios). diff --git a/docs/pl/manuals/extensions-debugging.md b/docs/pl/manuals/extensions-debugging.md new file mode 100644 index 00000000..3c1388c2 --- /dev/null +++ b/docs/pl/manuals/extensions-debugging.md @@ -0,0 +1,6 @@ +--- +title: Debugowanie rozszerzeń +brief: Ta instrukcja opisuje kilka sposobów debugowania aplikacji zawierającej rozszerzenia natywne. +--- + +Więcej informacji znajdziesz w [podręczniku debugowania kodu natywnego](/manuals/debugging-native-code). diff --git a/docs/pl/manuals/extensions-defold-sdk.md b/docs/pl/manuals/extensions-defold-sdk.md new file mode 100644 index 00000000..7fb6576b --- /dev/null +++ b/docs/pl/manuals/extensions-defold-sdk.md @@ -0,0 +1,16 @@ +--- +title: Natywne rozszerzenia - Defold SDK +brief: Ta instrukcja opisuje, jak pracować z Defold SDK podczas tworzenia natywnych rozszerzeń. +--- + +# Defold SDK + +Defold SDK zawiera funkcje potrzebne do zadeklarowania natywnego rozszerzenia oraz do komunikacji z niskopoziomową natywną warstwą platformy, na której działa aplikacja, i wysokopoziomową warstwą Lua, w której tworzona jest logika gry. + +## Użycie + +Z Defold SDK korzystasz, dołączając plik nagłówkowy `dmsdk/sdk.h`: + + #include + +Dostępne funkcje i przestrzenie nazw Defold SDK są opisane w naszej [dokumentacji API](/ref/overview_cpp). Pliki nagłówkowe Defold SDK są udostępniane jako osobne archiwum `defoldsdk_headers.zip` dla każdego wydania Defold opublikowanego na [GitHub](https://github.com/defold/defold/releases). Możesz używać tych plików nagłówkowych do podpowiadania kodu w wybranym edytorze. diff --git a/docs/pl/manuals/extensions-ext-manifests.md b/docs/pl/manuals/extensions-ext-manifests.md new file mode 100644 index 00000000..30cffb92 --- /dev/null +++ b/docs/pl/manuals/extensions-ext-manifests.md @@ -0,0 +1,75 @@ +--- +title: Natywne rozszerzenia - manifesty rozszerzeń +brief: Ta instrukcja opisuje manifest rozszerzenia i to, jak łączy się on z manifestem aplikacji oraz manifestem silnika. +--- + +# Pliki manifestów rozszerzenia, aplikacji i silnika + +Manifest rozszerzenia to plik konfiguracyjny z flagami i definicjami używanymi podczas budowania pojedynczego rozszerzenia. Tę konfigurację łączy się z konfiguracją na poziomie aplikacji oraz z konfiguracją bazową samego silnika Defold. + +## Manifest aplikacji + +Manifest aplikacji (plik `.appmanifest`) to konfiguracja na poziomie aplikacji określająca sposób budowania gry na serwerach buildów. Manifest aplikacji pozwala usuwać z silnika części, których nie używasz. Jeśli nie potrzebujesz silnika fizyki, możesz usunąć go z pliku wykonywalnego, aby zmniejszyć jego rozmiar. Dowiedz się, jak wykluczać nieużywane funkcje [w instrukcji manifestu aplikacji](/manuals/app-manifest). + +## Manifest silnika + +Silnik Defold ma manifest budowania (`build.yml`), który jest dołączany do każdej wersji silnika i Defold SDK. Manifest kontroluje, których wersji SDK używać, jakich kompilatorów, linkerów i innych narzędzi używać oraz jakie domyślne flagi kompilacji i linkowania przekazywać tym narzędziom. Manifest można znaleźć w pliku share/extender/build_input.yml [na GitHubie](https://github.com/defold/defold/blob/dev/share/extender/build_input.yml). + +## Manifest rozszerzenia + +Manifest rozszerzenia (`ext.manifest`) z kolei jest plikiem konfiguracyjnym przeznaczonym konkretnie dla rozszerzenia. Kontroluje sposób kompilacji i linkowania kodu źródłowego rozszerzenia oraz to, jakie dodatkowe biblioteki mają zostać dołączone. + +Wszystkie trzy pliki manifestów używają tej samej składni, dzięki czemu można je łączyć i w pełni kontrolować sposób budowania rozszerzeń oraz gry. + +Dla każdego budowanego rozszerzenia manifesty są łączone w następujący sposób: + + manifest = merge(game.appmanifest, ext.manifest, build.yml) + +Dzięki temu użytkownik może nadpisać domyślne zachowanie silnika, a także zachowanie każdego rozszerzenia. Na potrzeby końcowego etapu linkowania łączymy manifest aplikacji z manifestem build.yml: + + manifest = merge(game.appmanifest, build.yml) + + +### Plik ext.manifest + +Poza nazwą rozszerzenia plik manifestu może zawierać flagi kompilacji zależne od platformy, flagi linkowania, biblioteki i frameworki. Jeśli plik *ext.manifest* nie zawiera sekcji "platforms" albo którejś platformy brakuje na liście, platforma, dla której tworzysz pakiet, nadal się zbuduje, ale bez dodatkowych ustawionych flag. + +Oto przykład: + +```yaml +name: "AdExtension" + +platforms: + arm64-ios: + context: + frameworks: ["CoreGraphics", "CFNetwork", "GLKit", "CoreMotion", "MessageUI", "MediaPlayer", "StoreKit", "MobileCoreServices", "AdSupport", "AudioToolbox", "AVFoundation", "CoreGraphics", "CoreMedia", "CoreMotion", "CoreTelephony", "CoreVideo", "Foundation", "GLKit", "JavaScriptCore", "MediaPlayer", "MessageUI", "MobileCoreServices", "OpenGLES", "SafariServices", "StoreKit", "SystemConfiguration", "UIKit", "WebKit"] + flags: ["-stdlib=libc++"] + linkFlags: ["-ObjC"] + libs: ["z", "c++", "sqlite3"] + defines: ["MY_DEFINE"] + + armv7-ios: + context: + frameworks: ["CoreGraphics", "CFNetwork", "GLKit", "CoreMotion", "MessageUI", "MediaPlayer", "StoreKit", "MobileCoreServices", "AdSupport", "AudioToolbox", "AVFoundation", "CoreGraphics", "CoreMedia", "CoreMotion", "CoreTelephony", "CoreVideo", "Foundation", "GLKit", "JavaScriptCore", "MediaPlayer", "MessageUI", "MobileCoreServices", "OpenGLES", "SafariServices", "StoreKit", "SystemConfiguration", "UIKit", "WebKit"] + flags: ["-stdlib=libc++"] + linkFlags: ["-ObjC"] + libs: ["z", "c++", "sqlite3"] + defines: ["MY_DEFINE"] +``` + +#### Dozwolone klucze + +Dozwolone klucze dla flag kompilacji zależnych od platformy to: + +* `frameworks` - frameworki Apple do dołączenia podczas budowania (iOS i macOS) +* `weakFrameworks` - frameworki Apple do opcjonalnego dołączenia podczas budowania (iOS i macOS) +* `flags` - flagi przekazywane do kompilatora +* `linkFlags` - flagi przekazywane do linkera +* `libs` - dodatkowe biblioteki do dołączenia podczas linkowania +* `defines` - definicje ustawiane podczas budowania +* `aaptExtraPackages` - dodatkowa nazwa pakietu, która ma zostać wygenerowana (Android) +* `aaptExcludePackages` - wyrażenie regularne (lub dokładne nazwy) pakietów do wykluczenia (Android) +* `aaptExcludeResourceDirs` - wyrażenie regularne (lub dokładne nazwy) katalogów zasobów do wykluczenia (Android) +* `excludeLibs`, `excludeJars`, `excludeSymbols` - te flagi służą do usuwania elementów wcześniej zdefiniowanych w kontekście platformy. + +Dla wszystkich słów kluczowych stosujemy filtr białej listy, aby uniknąć nieprawidłowej obsługi ścieżek i dostępu do plików spoza folderu przesyłania builda. diff --git a/docs/pl/manuals/extensions-gradle.md b/docs/pl/manuals/extensions-gradle.md new file mode 100644 index 00000000..0b35d017 --- /dev/null +++ b/docs/pl/manuals/extensions-gradle.md @@ -0,0 +1,31 @@ +--- +title: Korzystanie z zależności Gradle w kompilacjach Androida +brief: Ta instrukcja wyjaśnia, jak używać Gradle do rozwiązywania zależności w kompilacjach Androida. +--- + +# Gradle dla Androida + +W przeciwieństwie do tego, jak zwykle buduje się aplikacje Android, Defold nie używa [Gradle](https://gradle.org/) do całego procesu budowania. Zamiast tego Defold używa bezpośrednio narzędzi wiersza poleceń Android, takich jak `aapt2` i `bundletool`, w lokalnym budowaniu, a Gradle wykorzystuje tylko podczas rozwiązywania zależności na serwerze budowania. + + +## Rozwiązywanie zależności + +Rozszerzenia natywne mogą zawierać plik `build.gradle` w folderze `manifests/android`, aby określić zależności rozszerzenia. Przykład: + +``` +repositories { + mavenCentral() +} + +dependencies { + implementation 'com.google.firebase:firebase-installations:17.2.0' + implementation 'com.google.android.gms:play-services-base:18.2.0' +} +``` + +Serwer budowania zbierze pliki `build.gradle` ze wszystkich rozszerzeń i użyje ich do rozwiązywania wszystkich zależności oraz dołączenia ich podczas budowania kodu natywnego. + +Przykłady: + +* [Firebase](https://github.com/defold/extension-firebase/blob/master/firebase/manifests/android/)build.gradle +* [Facebook](https://github.com/defold/extension-facebook/blob/master/facebook/manifests/android/build.gradle) diff --git a/docs/pl/manuals/extensions-manifest-merge-tool.md b/docs/pl/manuals/extensions-manifest-merge-tool.md new file mode 100644 index 00000000..a966d36c --- /dev/null +++ b/docs/pl/manuals/extensions-manifest-merge-tool.md @@ -0,0 +1,359 @@ +--- +title: Natywne rozszerzenia - narzędzia scalania manifestów +brief: Ta instrukcja opisuje, jak działa scalanie manifestów aplikacji +--- + +# Manifesty aplikacji + +Dla niektórych platform obsługujemy rozszerzenia, które dostarczają fragmenty manifestów aplikacji. +Może to być fragment `AndroidManifest.xml`, `Info.plist` albo `engine_template.html`. + +Każdy fragment manifestu rozszerzenia jest stosowany kolejno, począwszy od bazowego manifestu aplikacji. +Manifest bazowy jest albo domyślnym manifestem (w `builtins\manifests\\...`), albo niestandardowym manifestem dostarczonym przez użytkownika. + +## Nazewnictwo i struktura + +Manifesty rozszerzeń muszą być umieszczone w określonej strukturze, aby rozszerzenie działało zgodnie z przeznaczeniem. + + /myextension + ext.manifest + /manifests + /android + AndroidManifest.xml + /ios + Info.plist + /osx + Info.plist + /web + engine_template.html + + +## Android + +Platforma Android ma już narzędzie do scalania manifestów oparte na `ManifestMerger2`, a my używamy go w `bob.jar` do tego samego zadania. +Pełny zestaw instrukcji dotyczących modyfikowania manifestów Androida znajdziesz w [ich dokumentacji](https://developer.android.com/studio/build/manifest-merge). + +::: important +Jeśli w manifeście rozszerzenia nie ustawisz `android:targetSdkVersion` dla swojej aplikacji, automatycznie zostaną dodane następujące uprawnienia: `WRITE_EXTERNAL_STORAGE`, `READ_PHONE_STATE`, `READ_EXTERNAL_STORAGE`. Więcej na ten temat znajdziesz w oficjalnej dokumentacji [tutaj](https://developer.android.com/studio/build/manifest-merge#implicit_system_permissions). +Zalecamy użycie: `` +::: +### Przykład + +Manifest bazowy + +```xml + + + + + + + + +``` + +Manifest rozszerzenia + +```xml + + + + + + + + + +``` + +Wynik + +```xml + + + + + + + + + + +``` + +## iOS / macOS + +W przypadku `Info.plist` używamy własnej implementacji do scalania list i słowników. Na kluczach można określić atrybuty scalania `merge`, `keep` lub `replace`, przy czym `merge` jest domyślny. + +### Przykład + +Manifest bazowy + +```xml + + + + + NSAppTransportSecurity + + NSExceptionDomains + + foobar.net + + testproperty + + + + + INT + 8 + + REAL + 8.0 + + + BASE64 + SEVMTE8gV09STEQ= + + + Array1 + + + Foobar + + a + + + + + + Array2 + + + Foobar + + a + + + + + +``` + +Manifest rozszerzenia + +```xml + + + + + NSAppTransportSecurity + + NSExceptionDomains + + facebook.com + + NSIncludesSubdomains + + NSThirdPartyExceptionRequiresForwardSecrecy + + + + + INT + 42 + + + REAL + 16.0 + + BASE64 + Rk9PQkFS + + Array1 + + + Foobar + + b + + + + + Array2 + + + Foobar + + b + + + + + +``` + +Wynik: + +```xml + + + + + + NSAppTransportSecurity + + NSExceptionDomains + + foobar.net + + testproperty + + + facebook.com + + NSIncludesSubdomains + + NSThirdPartyExceptionRequiresForwardSecrecy + + + + + + + INT + 8 + + + REAL + 16.0 + + + BASE64 + SEVMTE8gV09STEQ= + + + INT + 42 + + + Array1 + + + Foobar + + a + b + + + + + + Array2 + + + Foobar + + a + + + + Foobar + + b + + + + + +``` + + +## HTML5 + +Dla szablonu HTML oznaczyliśmy każdą sekcję, aby można było je dopasowywać, na przykład "engine-start". +Następnie można określić atrybuty `merge` albo `keep`. `merge` jest domyślny. + +### Przykład + +Manifest bazowy + +```html + + + + + + + + +``` + +Manifest rozszerzenia + +```html + + + + + + +``` + +Wynik + +```html + + + + + + + + + +``` diff --git a/docs/pl/manuals/extensions-script-api.md b/docs/pl/manuals/extensions-script-api.md new file mode 100644 index 00000000..fa77bc64 --- /dev/null +++ b/docs/pl/manuals/extensions-script-api.md @@ -0,0 +1,53 @@ +--- +title: Dodawanie autouzupełniania edytora do rozszerzeń natywnych +brief: Ta instrukcja wyjaśnia, jak utworzyć definicję API skryptu, aby edytor Defold mógł oferować autouzupełnianie użytkownikom rozszerzenia. +--- + +# Autouzupełnianie dla rozszerzeń natywnych + +Edytor Defold udostępnia podpowiedzi autouzupełniania dla wszystkich funkcji API Defold i generuje sugestie dla modułów Lua wymaganych przez twoje skrypty. Nie potrafi jednak automatycznie oferować podpowiedzi autouzupełniania dla funkcjonalności wystawianej przez rozszerzenia natywne. Rozszerzenie natywne może dostarczyć definicję API w osobnym pliku, aby włączyć podpowiedzi autouzupełniania także dla API rozszerzenia. + +## Tworzenie definicji API skryptu + +Plik definicji API skryptu ma rozszerzenie `.script_api`. Musi być zapisany w formacie [YAML](https://yaml.org/) i znajdować się razem z plikami rozszerzenia. Oczekiwany format definicji API skryptu wygląda tak: + +```yml +- name: Nazwa rozszerzenia + type: table + desc: Opis rozszerzenia + members: + - name: Nazwa pierwszego elementu + type: Typ elementu + desc: Opis elementu + # jeśli typ elementu to "function" + parameters: + - name: Nazwa pierwszego parametru + type: Typ parametru + desc: Opis parametru + - name: Nazwa drugiego parametru + type: Typ parametru + desc: Opis parametru + # jeśli typ elementu to "function" + returns: + - name: Nazwa pierwszej wartości zwracanej + type: Typ wartości zwracanej + desc: Opis wartości zwracanej + examples: + - desc: Pierwszy przykład użycia elementu + - desc: Drugi przykład użycia elementu + + - name: Nazwa drugiego elementu + ... +``` + +Typami mogą być dowolne z `table, string , boolean, number, function`. Jeśli wartość może mieć wiele typów, zapisuje się ją jako `[type1, type2, type3]`. +::: sidenote +Typy nie są obecnie wyświetlane w edytorze. Warto mimo to je podawać, aby były dostępne, gdy edytor zyska obsługę wyświetlania informacji o typach. +::: + +## Przykłady + +Przykłady rzeczywistego użycia znajdziesz w następujących projektach: + +* [Facebook extension](https://github.com/defold/extension-facebook/tree/master/facebook/api) +* [WebView extension](https://github.com/defold/extension-webview/blob/master/webview/api/webview.script_api) diff --git a/docs/pl/manuals/extensions.md b/docs/pl/manuals/extensions.md new file mode 100644 index 00000000..99ef4f74 --- /dev/null +++ b/docs/pl/manuals/extensions.md @@ -0,0 +1,249 @@ +--- +title: Pisanie natywnych rozszerzeń dla Defold +brief: Ta instrukcja wyjaśnia, jak pisać natywne rozszerzenia dla silnika Defold i jak kompilować je z użyciem chmurowych kompilatorów bez konfiguracji. +--- + +# Natywne rozszerzenia + +Jeśli potrzebujesz niestandardowej integracji z zewnętrznym oprogramowaniem lub sprzętem na niskim poziomie, gdzie Lua nie wystarcza, Defold SDK pozwala pisać rozszerzenia do silnika w C, C++, Objective-C, Java lub JavaScript, zależnie od platformy docelowej. Typowe zastosowania natywnych rozszerzeń to: + +- Integracja z konkretnym sprzętem, na przykład z kamerą w telefonie. +- Integracja z zewnętrznymi niskopoziomowymi API, na przykład z API sieci reklamowych, które nie pozwalają na komunikację sieciową w sposób, w jaki można by użyć Luasocket. +- Obliczenia o wysokiej wydajności i przetwarzanie danych. + +## Serwer budowania + +Defold udostępnia gotowy punkt startowy do pracy z natywnymi rozszerzeniami dzięki chmurowemu rozwiązaniu do budowania. Każde natywne rozszerzenie, które zostanie dodane do projektu gry, bezpośrednio lub przez [Library Project](/manuals/libraries/), staje się częścią zwykłej zawartości projektu. Nie ma potrzeby budowania specjalnych wersji silnika i rozsyłania ich do członków zespołu. Robi się to automatycznie - każdy członek zespołu, który zbuduje i uruchomi projekt, otrzyma plik wykonywalny silnika specyficzny dla projektu, z wszystkimi natywnymi rozszerzeniami wbudowanymi na stałe. + +![Budowanie w chmurze](images/extensions/cloud_build.png) + +Defold udostępnia serwer budowania w chmurze bezpłatnie i bez żadnych ograniczeń użycia. Serwer jest hostowany w Europie, a URL, pod który wysyłany jest kod natywny, konfiguruje się w oknie [Editor Preferences](/manuals/editor-preferences/#extensions) albo przez opcję wiersza poleceń `--build-server` narzędzia [bob](/manuals/bob/#usage). Jeśli chcesz uruchomić własny serwer, [postępuj zgodnie z tymi instrukcjami](/manuals/extender-local-setup). + +## Układ projektu + +Aby utworzyć nowe rozszerzenie, utwórz folder w katalogu głównym projektu. Ten folder będzie zawierał wszystkie ustawienia, kod źródłowy, biblioteki i zasoby związane z rozszerzeniem. Serwer budowania rozpoznaje strukturę folderów i zbiera wszystkie pliki źródłowe oraz biblioteki. + +``` + myextension/ + │ + ├── ext.manifest + │ + ├── src/ + │ + ├── include/ + │ + ├── lib/ + │ └──[platforms] + │ + ├── manifests/ + │ └──[platforms] + │ + └── res/ + └──[platforms] + +``` +*ext.manifest* +: Folder rozszerzenia _musi_ zawierać plik *ext.manifest*. Jest to plik konfiguracyjny z flagami i definicjami używanymi podczas budowania pojedynczego rozszerzenia. Definicję formatu pliku znajdziesz w [instrukcji o manifestach rozszerzenia](https://defold.com/manuals/extensions-ext-manifests/). + +*src* +: Ten folder powinien zawierać wszystkie pliki z kodem źródłowym. + +*include* +: Ten opcjonalny folder zawiera pliki include. + +*lib* +: Ten opcjonalny folder zawiera wszystkie skompilowane biblioteki, od których zależy rozszerzenie. Pliki biblioteki należy umieszczać w podfolderach nazwanych według `platform` albo `architecture-platform`, zależnie od tego, jakie architektury są obsługiwane przez twoje biblioteki. + + :[platforms](../shared/platforms.md) + +*manifests* +: Ten opcjonalny folder zawiera dodatkowe pliki używane podczas procesu budowania lub pakowania. Szczegóły znajdziesz poniżej. + +*res* +: Ten opcjonalny folder zawiera dodatkowe zasoby, od których zależy rozszerzenie. Pliki zasobów należy umieszczać w podfolderach nazwanych według `platform` albo `architecture-platform`, tak samo jak podfoldery w "lib". Dozwolony jest też podfolder `common`, zawierający pliki zasobów wspólne dla wszystkich platform. + +### Pliki manifestu + +Opcjonalny folder *manifests* rozszerzenia zawiera dodatkowe pliki używane podczas procesu budowania i pakowania. Pliki należy umieszczać w podfolderach nazwanych według `platform`: + +* `android` - Ten folder przyjmuje plik-szablon manifestu, który zostanie scalony z główną aplikacją ([jak opisano tutaj](/manuals/extensions-manifest-merge-tool)). + * Folder może też zawierać plik `build.gradle` z zależnościami, które mają być rozwiązywane przez Gradle. + * Na koniec folder może też zawierać zero lub więcej plików ProGuard (eksperymentalnych). +* `ios` - Ten folder przyjmuje plik-szablon manifestu, który zostanie scalony z główną aplikacją ([jak opisano tutaj](/manuals/extensions-manifest-merge-tool)). + * Folder może też zawierać plik `Podfile` z zależnościami, które mają być rozwiązywane przez CocoaPods. +* `osx` - Ten folder przyjmuje plik-szablon manifestu, który zostanie scalony z główną aplikacją ([jak opisano tutaj](/manuals/extensions-manifest-merge-tool)). +* `web` - Ten folder przyjmuje plik-szablon manifestu, który zostanie scalony z główną aplikacją ([jak opisano tutaj](/manuals/extensions-manifest-merge-tool)). + + +## Udostępnianie rozszerzenia + +Rozszerzenia są traktowane tak samo jak inne zasoby w projekcie i można je udostępniać w ten sam sposób. Jeśli folder natywnego rozszerzenia zostanie dodany jako folder biblioteki, można go udostępniać i używać jako zależności projektu. Więcej informacji znajdziesz w [instrukcji o bibliotekach](/manuals/libraries/). + + +## Prosty przykład rozszerzenia + +Zbudujmy bardzo proste rozszerzenie. Najpierw tworzymy nowy folder główny *`myextension`* i dodajemy plik *`ext.manifest`* zawierający nazwę rozszerzenia `MyExtension`. Zwróć uwagę, że ta nazwa jest symbolem C++ i musi odpowiadać pierwszemu argumentowi `DM_DECLARE_EXTENSION` (patrz niżej). + +![Manifest](images/extensions/manifest.png) + +```yaml +# Symbol C++ w twoim rozszerzeniu +name: "MyExtension" +``` + +Rozszerzenie składa się z jednego pliku C++, *`myextension.cpp`*, który tworzymy w folderze `src`. + +![Plik C++](images/extensions/cppfile.png) + +Plik źródłowy rozszerzenia zawiera następujący kod: + +```cpp +// myextension.cpp +// Definicje biblioteki rozszerzenia +#define LIB_NAME "MyExtension" +#define MODULE_NAME "myextension" + +// dołącz Defold SDK +#include + +static int Reverse(lua_State* L) +{ + // Oczekiwana liczba elementów na stosie Lua + // po wyjściu tej struktury z zakresu + DM_LUA_STACK_CHECK(L, 1); + + // Sprawdź i pobierz parametr tekstowy ze stosu + char* str = (char*)luaL_checkstring(L, 1); + + // Odwróć łańcuch znaków + int len = strlen(str); + for(int i = 0; i < len / 2; i++) { + const char a = str[i]; + const char b = str[len - i - 1]; + str[i] = b; + str[len - i - 1] = a; + } + + // Umieść odwrócony łańcuch na stosie + lua_pushstring(L, str); + + // Zwróć 1 element + return 1; +} + +// Funkcje udostępnione do Lua +static const luaL_reg Module_methods[] = +{ + {"reverse", Reverse}, + {0, 0} +}; + +static void LuaInit(lua_State* L) +{ + int top = lua_gettop(L); + + // Zarejestruj nazwy w Lua + luaL_register(L, MODULE_NAME, Module_methods); + + lua_pop(L, 1); + assert(top == lua_gettop(L)); +} + +dmExtension::Result AppInitializeMyExtension(dmExtension::AppParams* params) +{ + return dmExtension::RESULT_OK; +} + +dmExtension::Result InitializeMyExtension(dmExtension::Params* params) +{ + // Zainicjalizuj Lua + LuaInit(params->m_L); + printf("Registered %s Extension\n", MODULE_NAME); + return dmExtension::RESULT_OK; +} + +dmExtension::Result AppFinalizeMyExtension(dmExtension::AppParams* params) +{ + return dmExtension::RESULT_OK; +} + +dmExtension::Result FinalizeMyExtension(dmExtension::Params* params) +{ + return dmExtension::RESULT_OK; +} + + +// Defold SDK używa makra do ustawiania punktów wejścia rozszerzenia: +// +// DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final) + +// MyExtension to symbol C++, który przechowuje wszystkie istotne dane rozszerzenia. +// Musi odpowiadać polu name w `ext.manifest` +DM_DECLARE_EXTENSION(MyExtension, LIB_NAME, AppInitializeMyExtension, AppFinalizeMyExtension, InitializeMyExtension, 0, 0, FinalizeMyExtension) +``` + +Zwróć uwagę na makro `DM_DECLARE_EXTENSION`, które służy do deklarowania różnych punktów wejścia do kodu rozszerzenia. Pierwszy argument `symbol` musi odpowiadać nazwie podanej w *ext.manifest*. W tym prostym przykładzie nie ma potrzeby definiować żadnych punktów wejścia "update" ani "on_event", więc w tych miejscach do makra przekazano `0`. + +Teraz wystarczy zbudować projekt (Project ▸ Build). Spowoduje to wysłanie rozszerzenia do serwera budowania, który wygeneruje własny silnik z nowym rozszerzeniem wbudowanym na stałe. Jeśli serwer budowania napotka jakiekolwiek błędy, pojawi się okno dialogowe z błędami budowania. + +Aby przetestować rozszerzenie, utwórz obiekt gry i dodaj do niego komponent skryptu z krótkim kodem testowym: + +```lua +local s = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" +local reverse_s = myextension.reverse(s) +print(reverse_s) --> ZYXWVUTSRQPONMLKJIHGFEDCBAzyxwvutsrqponmlkjihgfedcba +``` + +I to wszystko! Utworzyliśmy w pełni działające natywne rozszerzenie. + + +## Cykl życia rozszerzenia + +Jak widzieliśmy wyżej, makro `DM_DECLARE_EXTENSION` służy do deklarowania różnych punktów wejścia do kodu rozszerzenia: + +`DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)` + +Punkty wejścia pozwalają uruchamiać kod w różnych momentach cyklu życia rozszerzenia: + +* Start silnika + * Uruchamiają się systemy silnika + * Rozszerzenie `app_init` + * Rozszerzenie `init` - wszystkie API Defold są już zainicjalizowane. To zalecany moment w cyklu życia rozszerzenia na utworzenie wiązań Lua do kodu rozszerzenia. + * Inicjalizacja skryptów - wywoływana jest funkcja `init()` plików skryptów. +* Pętla silnika + * Aktualizacja silnika + * Rozszerzenie `update` + * Aktualizacja skryptów - wywoływana jest funkcja `update()` plików skryptów. + * Zdarzenia silnika (minimalizacja/maksymalizacja okna itp.) + * Rozszerzenie `on_event` +* Zamykanie silnika (lub ponowne uruchomienie) + * Finalizacja skryptów - wywoływana jest funkcja `final()` plików skryptów. + * Rozszerzenie `final` + * Rozszerzenie `app_final` + +## Zdefiniowane identyfikatory platform + +Następujące identyfikatory są definiowane przez serwer budowania dla każdej odpowiedniej platformy: + +* `DM_PLATFORM_WINDOWS` +* `DM_PLATFORM_OSX` +* `DM_PLATFORM_IOS` +* `DM_PLATFORM_ANDROID` +* `DM_PLATFORM_LINUX` +* `DM_PLATFORM_HTML5` + +## Dzienniki serwera budowania + +Dzienniki serwera budowania są dostępne, gdy projekt korzysta z natywnych rozszerzeń. Dziennik serwera budowania (`log.txt`) jest pobierany razem z własnym silnikiem podczas budowania projektu, przechowywany w pliku `.internal/%platform%/build.zip` i rozpakowywany także do folderu budowania projektu. + +## Przykłady rozszerzeń + +* [Podstawowy przykład rozszerzenia](https://github.com/defold/template-native-extension) (rozszerzenie z tej instrukcji) +* [Przykład rozszerzenia Android](https://github.com/defold/extension-android) +* [Przykład rozszerzenia HTML5](https://github.com/defold/extension-html5) +* [Rozszerzenie odtwarzacza wideo dla macOS, iOS i Android](https://github.com/defold/extension-videoplayer) +* [Rozszerzenie kamery dla macOS i iOS](https://github.com/defold/extension-camera) +* [Rozszerzenie In-app Purchase dla iOS i Android](https://github.com/defold/extension-iap) +* [Rozszerzenie Firebase Analytics dla iOS i Android](https://github.com/defold/extension-firebase-analytics) + +[Portal zasobów Defold](https://www.defold.com/assets/) także zawiera kilka natywnych rozszerzeń. diff --git a/docs/pl/manuals/facebook.md b/docs/pl/manuals/facebook.md new file mode 100644 index 00000000..f8d286c9 --- /dev/null +++ b/docs/pl/manuals/facebook.md @@ -0,0 +1,6 @@ +--- +title: Facebook w silniku Defold +brief: Facebook w silniku Defold. +--- + +[Ta instrukcja została przeniesiona tutaj](/extension-facebook). diff --git a/docs/pl/manuals/factory.md b/docs/pl/manuals/factory.md index 1a40dbf9..dff3c105 100644 --- a/docs/pl/manuals/factory.md +++ b/docs/pl/manuals/factory.md @@ -1,19 +1,19 @@ --- -title: Fabryka -brief: Ta instrukcja opisuje komponent fabryki służący do tworzenia obiektów gry z komponentami w czasie działania programu. +title: Instrukcja komponentu Factory +brief: Ta instrukcja wyjaśnia, jak używać komponentów Factory do dynamicznego tworzenia obiektów gry w czasie działania. --- -# Fabryka +# Komponenty Factory -Komponenty fabryki w Defoldzie służą do dynamicznego generowania obiektów gry z puli obiektów podczas działania gry. +Komponenty Factory służą do dynamicznego tworzenia obiektów gry z puli obiektów w działającej grze. -Gdy dodajesz komponent fabryki do obiektu gry, w właściwości *Prototype* określasz, jaki plik obiektu gry fabryka powinna używać jako prototyp (nazywany również "prefabem", "szablonem" czy "blueprintem" w innych silnikach) dla wszystkich nowych obiektów gry, które tworzy. +Gdy dodajesz komponent Factory do obiektu gry, we właściwości *Prototype* określasz, którego pliku obiektu gry fabryka ma używać jako prototypu dla wszystkich nowych obiektów, które tworzy. W innych silnikach taki prototyp bywa nazywany również "prefabem" albo "blueprintem". -![Fabryka](images/factory/factory_collection.png) +![Factory component](images/factory/factory_collection.png) -![Fabryka](images/factory/factory_component.png) +![Factory component](images/factory/factory_component.png) -Aby wywołać utworzenie obiektu gry, należy wywołać funkcję `factory.create()`: +Aby uruchomić tworzenie obiektu gry, wywołaj `factory.create()`: ```lua -- factory.script @@ -25,22 +25,22 @@ factory.create(component, p) ![Spawned game object](images/factory/factory_spawned.png) -`factory.create()` przyjmuje 5 parameterów: +`factory.create()` przyjmuje 5 parametrów: `url` -: Identyfikator komponentu fabryki, który ma utworzyć nowy obiekt gry. +: Id komponentu Factory, który ma utworzyć nowy obiekt gry. `[position]` -: (opcjonalne) pozycja w przestrzeni świata (world position) nowego obiektu gry. Powinien to być `vector3`. Jeśli nie określisz pozycji, obiekt gry zostanie utworzony w pozycji komponentu fabryki. +: (opcjonalnie) Pozycja nowego obiektu gry w przestrzeni świata. Powinien to być `vector3`. Jeśli nie podasz pozycji, obiekt gry pojawi się w pozycji komponentu Factory. `[rotation]` -: (opcjonalne) obrót w przestrzeni świata (world rotation) nowego obiektu gry. Powinien to być kwaternion - `quat`. +: (opcjonalnie) Obrót nowego obiektu gry w przestrzeni świata. Powinien to być `quat`. `[properties]` -: (opcjonalne) tabela Lua z wartościami właściwości skryptu do zainicjowania obiektu gry. Zobacz szczegóły w [instrukcji o właściwościach skryptu](/manuals/script-properties). +: (opcjonalnie) Tabela Lua z wartościami właściwości skryptu, którymi ma zostać zainicjowany obiekt gry. Więcej informacji o właściwościach skryptu znajdziesz w [instrukcji Script property](/manuals/script-properties). `[scale]` -: (opcjonalne) skala utworzonego obiektu gry. Skalę można wyrazić jako liczbę - `number` (większą niż 0), która określa jednolitą skalę we wszystkich osiach. Możesz też podać `vector3`, gdzie każdy komponent określa skalę w odpowiedniej osi. +: (opcjonalnie) Skala utworzonego obiektu gry. Skalę można podać jako `number` większy od 0, co oznacza jednolite skalowanie we wszystkich osiach. Możesz też przekazać `vector3`, w którym każdy składnik określa skalowanie w odpowiadającej osi. Na przykład: @@ -49,12 +49,11 @@ Na przykład: local p = go.get_position() p.y = vmath.lerp(math.random(), min_y, max_y) local component = "#star_factory" --- Utwórz obiekt z obrotem 0, ale podwójną skalą. --- Ustaw wartość punktową "score" na 10. +-- Utwórz obiekt bez obrotu, ale z podwójną skalą. +-- Ustaw wartość właściwości score gwiazdy na 10. factory.create(component, p, nil, { score = 10 }, 2.0) -- <1> ``` - -1. Ustala wartość punktową obiektu gry gwiazdy. +1. Ustawia właściwość "score" obiektu gry gwiazdy. ```lua -- star.script @@ -78,20 +77,18 @@ function on_message(self, message_id, message, sender) end end ``` - 1. Właściwość skryptu "score" jest zdefiniowana z wartością domyślną. -2. Odwołuje się do właściwości skryptu "score" jako przechowywanej wartości w "self". +2. Odwołuje się do właściwości skryptu "score" jako do wartości przechowywanej w `self`. -![utworzone obiekty](images/factory/factory_spawned2.png) +![Spawned game object with property and scaling](images/factory/factory_spawned2.png) ::: sidenote -Defold obecnie nie obsługuje nieliniowego skalowania kształtów kolizji. Jeśli podasz wartość nieliniowego skalowania, na przykład `vmath.vector3(1.0, 2.0, 1.0)` to sprite zostanie odpowiednio przeskalowany, ale kształty kolizji nie. +Defold nie obsługuje obecnie niejednorodnego skalowania kształtów kolizji. Jeśli podasz wartość niejednorodnego skalowania, na przykład `vmath.vector3(1.0, 2.0, 1.0)`, sprite zostanie przeskalowany poprawnie, ale kształty kolizji już nie. ::: +## Adresowanie obiektów utworzonych przez Factory -## Adresowanie obiektów utworzonych z fabryki - -Mechanizm adresowania Defolda umożliwia dostęp do każdego obiektu i komponentu w trakcie działania gry. [Instrukcja adresowania](/manuals/addressing/) zawiera szczegółowe informacje na temat działania tego systemu. Ten mechanizm można również wykorzystać do dostępu do utworzonych obiektów gry i ich komponentów. Najczęściej wystarcza użycie identyfikatora utworzonego obiektu, na przykład w celu wysłania wiadomości: +Mechanizm adresowania Defold pozwala uzyskać dostęp do każdego obiektu i komponentu w działającej grze. [Instrukcja Addressing](/manuals/addressing/) szczegółowo wyjaśnia, jak ten system działa. Tego samego mechanizmu można używać również dla utworzonych obiektów gry i ich komponentów. Często wystarczy użyć id utworzonego obiektu, na przykład podczas wysyłania wiadomości: ```lua local function create_hunter(target_id) @@ -102,10 +99,10 @@ end ``` ::: sidenote -Przesłanie wiadomości bezpośrednio do obiektu gry, a nie do określonego komponentu, w rzeczywistości wysyła wiadomość do wszystkich komponentów tego obiektu. Zazwyczaj nie stanowi to problemu, ale warto pamiętać, jeśli obiekt ma wiele komponentów. +Wysłanie wiadomości do samego obiektu gry zamiast do konkretnego komponentu w praktyce rozsyła ją do wszystkich komponentów tego obiektu. Zwykle nie stanowi to problemu, ale warto o tym pamiętać, jeśli obiekt ma dużo komponentów. ::: -Ale co, jeśli musisz uzyskać dostęp do konkretnego komponentu na utworzonym obiekcie gry, na przykład, aby wyłączyć obiekt kolizji lub zmienić obraz sprite'a? Rozwiązaniem jest skonstruowanie adresu URL na podstawie identyfikatora obiektu gry i identyfikatora komponentu: +Co jednak zrobić, gdy chcesz uzyskać dostęp do konkretnego komponentu utworzonego obiektu gry, na przykład aby wyłączyć obiekt kolizji albo zmienić obraz sprite'a? Rozwiązaniem jest zbudowanie adresu URL z id obiektu gry i id komponentu. ```lua local function create_guard(unarmed) @@ -120,9 +117,9 @@ local function create_guard(unarmed) end ``` -## Śledzenie utworzonych obiektów i rodziców +## Śledzenie utworzonych obiektów i obiektu nadrzędnego -Wywołując `factory.create()` otrzymujesz identyfikator nowego obiektu gry, co pozwala na przechowywanie go do użycia później. Jednym z powszechnych zastosowań jest generowanie obiektów i dodawanie ich identyfikatorów do tabeli, dzięki czemu można je usunąć w późniejszym momencie, na przykład podczas resetowania układu poziomu: +Gdy wywołasz `factory.create()`, otrzymasz z powrotem id nowego obiektu gry, dzięki czemu możesz zachować je do późniejszego użycia. Jednym z typowych zastosowań jest tworzenie obiektów i dodawanie ich id do tabeli, aby później usunąć je wszystkie, na przykład podczas resetowania układu poziomu: ```lua -- spawner.script @@ -130,41 +127,42 @@ self.spawned_coins = {} ... --- Spawn a coin and store it in the "coins" table. +-- Utwórz monetę i zapisz ją w tabeli "coins". local id = factory.create("#coinfactory", coin_position) table.insert(self.spawned_coins, id) ``` -I później: +A później: ```lua -- spawner.script --- Usuń utworzone monety +-- Usuń wszystkie utworzone monety. for _, coin_id in ipairs(self.spawned_coins) do go.delete(coin_id) end --- lub alternatywnie: +-- albo alternatywnie go.delete(self.spawned_coins) ``` -Warto też wiedzieć jakie obiekty się utworzyło w świecie gry. Przykładem może być obiekt, którego instancję chcemy mieć tylko jedną w jednym czasie. Utworzony obiekt musi wtedy poinformować swojego twórcę (spawner) kiedy jest usunięty lub nieaktywny, dzięki czemu spawner będzie mógł utworzyć następną instancję: +Zdarza się też, że chcesz, aby utworzony obiekt wiedział, który obiekt gry go utworzył. Jednym z przykładów jest autonomiczny obiekt, który może istnieć tylko w jednej instancji naraz. Taki obiekt musi poinformować spawner, że został usunięty lub zdezaktywowany, aby można było utworzyć kolejny: ```lua -- spawner.script --- Utwórz drona i ustaw jego rodzica na url tego skryptu +-- Utwórz drona i ustaw jego parent na URL tego komponentu skryptu self.spawned_drone = factory.create("#dronefactory", drone_position, nil, { parent = msg.url() }) ... function on_message(self, message_id, message, sender) if message_id == hash("drone_dead") then - self.spawed_drone = nil + self.spawned_drone = nil end end ``` -A to logika utworzonego obiektu: +Logika utworzonego obiektu wygląda tak: + ```lua -- drone.script go.property("parent", msg.url()) @@ -172,77 +170,78 @@ go.property("parent", msg.url()) ... function final(self) - -- I'm dead. + -- Umieram. msg.post(self.parent, "drone_dead") end ``` -## Dynamiczne ładowanie zasobów fabryki +## Dynamiczne ładowanie zasobów Factory -Zaznaczając opcję *Load Dynamically* (Ładuj dynamicznie) we właściwościach fabryki, silnik Defold odkłada w czasie ładowanie zasobów związanych z fabryką. +Po zaznaczeniu pola *Load Dynamically* we właściwościach Factory silnik odracza ładowanie zasobów powiązanych z fabryką. ![Load dynamically](images/factory/load_dynamically.png) -Gdy opcja jest niezaznaczona, silnik ładuje zasoby prototypu, gdy komponent fabryki jest ładowany, więc są one od razu gotowe do generowania. +Gdy pole nie jest zaznaczone, silnik ładuje zasoby prototypu podczas ładowania komponentu Factory, więc są one od razu gotowe do użycia. -Z opcją zaznaczoną, masz dwie możliwości użycia fabryki: +Gdy pole jest zaznaczone, masz dwa sposoby użycia: -Synchroniczne wczytywanie -: Wywołaj [`factory.create()`](/ref/factory/#factory.create), gdy chcesz generować obiekty. Spowoduje to synchroniczne ładowanie zasobów, co może powodować przycięcia w zależności od wielkości zasobu, a następnie tworzenie nowych instancji. +Ładowanie synchroniczne +: Wywołaj [`factory.create()`](/ref/factory/#factory.create), gdy chcesz utworzyć obiekty. Spowoduje to synchroniczne załadowanie zasobów, co może wywołać przycięcie, a następnie utworzenie nowych instancji. ```lua function init(self) - -- Gdy komponent fabryki jest ładowany, nie są jeszcze dostępne zasoby fabryki. - -- Wywołanie create bez wcześniejszego wywołania load spowoduje synchroniczne - -- ładowanie zasobów. + -- Gdy zostanie wczytana kolekcja nadrzędna fabryki, + -- zasoby fabryki nie są jeszcze załadowane. Wywołanie create + -- bez wcześniejszego load utworzy zasoby synchronicznie. self.go_id = factory.create("#factory") end function final(self) - -- Usuwa obiekty gry. Zasoby zostaną zwolnione. - -- W tym przypadku zasoby zostaną usunięte, ponieważ komponent fabryki - -- nie trzyma referencji. + -- Usuń obiekt gry. Zmniejszy to licznik referencji zasobów. + -- W tym przypadku zasoby zostaną usunięte, ponieważ komponent + -- fabryki nie trzyma już do nich referencji. go.delete(self.go_id) - -- Wywołanie unload nie spowoduje żadnych działań, - -- ponieważ komponent fabryki nie trzyma referencji. + -- Wywołanie unload nic nie zrobi, bo fabryka nie ma referencji. factory.unload("#factory") end ``` -Asynchroniczne wczytywanie -: Wywołaj [`factory.load()`](/ref/factory/#factory.load), aby jawnie załadować zasoby asynchronicznie. Po zakończeniu ładowania zasobów, są one gotowe do generowania - wywołane wtedy zostanie wywołanie zwrotne (callback). +Ładowanie asynchroniczne +: Wywołaj [`factory.load()`](/ref/factory/#factory.load), aby jawnie załadować zasoby asynchronicznie. Gdy zasoby będą gotowe do tworzenia obiektów, otrzymasz wywołanie zwrotne. ```lua function load_complete(self, url, result) - -- Ładowanie jest zakończone, zasoby są gotowe do generowania. + -- Ładowanie zakończone, zasoby są gotowe do tworzenia instancji. self.go_id = factory.create(url) end function init(self) - -- Gdy komponent fabryki jest ładowany, nie są jeszcze dostępne zasoby fabryki. - -- Wywołanie load spowoduje ładowanie zasobów. + -- Gdy zostanie wczytana kolekcja nadrzędna fabryki, + -- zasoby fabryki nie są jeszcze załadowane. Wywołanie load + -- spowoduje ich wczytanie. factory.load("#factory", load_complete) end function final(self) - -- Usuwa obiekt gry. Zasoby nie zostaną zwolnione, - -- ponieważ komponent fabryki nadal trzyma referencję. + -- Usuń obiekt gry. Zmniejszy to licznik referencji zasobów. + -- W tym przypadku zasoby nie zostaną usunięte, ponieważ komponent + -- fabryki nadal trzyma do nich referencję. go.delete(self.go_id) - -- Wywołanie unload spowoduje zwolnienie zasobów trzymanych przez komponent fabryki, - -- co spowoduje zniszczenie zasobów. + -- Wywołanie unload zmniejszy licznik referencji zasobów + -- trzymanych przez komponent fabryki, co doprowadzi do ich usunięcia. factory.unload("#factory") end ``` ## Dynamiczny prototyp -Możliwa jest zmiana prototypu *Prototype*, który ma utworzyć fabryka, zaznaczając opcję *Dynamic Prototype* we właściwościach fabryki. +Można zmienić, który *Prototype* fabryka może tworzyć, zaznaczając pole *Dynamic Prototype* we właściwościach komponentu. ![Dynamic prototype](images/factory/dynamic_prototype.png) -Gdy opcja *Dynamic Prototype* jest zaznaczona, komponent fabryki może zmieniać prototyp, używając funkcji `factory.set_prototype()`. Przykład: +Gdy opcja *Dynamic Prototype* jest włączona, komponent Factory może zmieniać prototyp przy użyciu funkcji `factory.set_prototype()`. Przykład: ```lua factory.unload("#factory") -- zwolnij poprzednie zasoby @@ -251,18 +250,17 @@ local enemy_id = factory.create("#factory") ``` ::: important -Gdy opcja *Dynamic Prototype* jest ustawiona, ilość komponentów w kolekcji nie może być optymalizowana, a zawierająca kolekcja będzie korzystać z domyślnych liczby komponentów z pliku *game.project*. +Gdy opcja *Dynamic Prototype* jest włączona, liczby komponentów w kolekcji nie można zoptymalizować, a kolekcja właściciela będzie używać domyślnych liczników komponentów z pliku *game.project*. ::: +## Limity instancji -## Limit instancji - -Ustawienie *max_instances* w ustawieniach związanych z kolekcją (*Collection related settings*) ogranicza łączną liczbę instancji obiektów gry, które mogą istnieć w świecie (główna kolekcja "main.collection" wczytana podczas uruchamiania lub dowolny świat wczytany za pośrednictwem pełnomocnika kolekcji). Wszystkie obiekty gry, które istnieją w świecie, są wliczane do tego limitu, niezależnie od tego, czy są umieszczone ręcznie w edytorze, czy generowane dynamicznie za pomocą skryptu. +Ustawienie projektu *max_instances* w sekcji *Collection related settings* ogranicza łączną liczbę instancji obiektów gry, które mogą istnieć w świecie. Dotyczy to main.collection wczytywanej przy starcie i każdego świata załadowanego przez pełnomocnika kolekcji. Do tego limitu wliczają się wszystkie obiekty gry istniejące w świecie, niezależnie od tego, czy zostały ręcznie umieszczone w edytorze, czy utworzone w czasie działania przez skrypt. -![Limit instancji](images/factory/factory_max_instances.png) +![Maksymalna liczba instancji](images/factory/factory_max_instances.png) -Jeśli ustawisz *max_instances* na 1024 i masz 24 ręcznie umieszczone obiekty gry w swojej głównej kolekcji, możesz utworzyć dodatkowe 1000 obiektów gry. Gdy tylko usuniesz obiekt gry, będziesz mógł utworzyć nową instancję. +Jeśli ustawisz *max_instances* na 1024 i masz 24 ręcznie umieszczone obiekty gry w głównej kolekcji, możesz utworzyć jeszcze 1000 obiektów gry. Gdy tylko usuniesz jakiś obiekt gry, możesz utworzyć kolejną instancję. -## Pula obiektów gry +## Ponowne używanie obiektów gry -Może się wydawać, że dobrym pomysłem jest zapisywanie utworzonych obiektów gry w puli i ponowne ich użycie. Jednak silnik Defold wykonuje już pulowanie obiektów pod spodem, więc dodatkowe obciążenie spowolni działanie. Szybsze i bardziej przejrzyste jest usuwanie obiektów gry i tworzenie nowych. +Może się wydawać, że dobrym pomysłem jest przechowywanie utworzonych obiektów gry w puli i ponowne ich wykorzystywanie. Silnik i tak wykonuje takie ponowne używanie obiektów wewnętrznie, więc dodatkowy narzut tylko spowolni działanie. Szybciej i czyściej jest usuwać obiekty gry i tworzyć nowe. diff --git a/docs/pl/manuals/file-access.md b/docs/pl/manuals/file-access.md new file mode 100644 index 00000000..32ec0cc7 --- /dev/null +++ b/docs/pl/manuals/file-access.md @@ -0,0 +1,138 @@ +--- +title: Praca z plikami +brief: Ta instrukcja wyjaśnia, jak zapisywać i odczytywać pliki oraz wykonywać inne operacje na plikach. +--- + +# Praca z plikami +Istnieje wiele różnych sposobów tworzenia plików i uzyskiwania do nich dostępu. Ścieżki do plików oraz sposób korzystania z nich zależą od typu pliku i jego lokalizacji. + +## Funkcje dostępu do plików i folderów +Defold udostępnia kilka różnych funkcji do pracy z plikami: + +* Możesz użyć standardowych funkcji [`io.*`](https://defold.com/ref/stable/io/) do odczytu i zapisu plików. Funkcje te dają bardzo precyzyjną kontrolę nad całym procesem I/O. + +```lua +-- otwórz myfile.txt do zapisu w trybie binarnym +-- w razie błędu zwraca nil oraz komunikat o błędzie +local f, err = io.open("path/to/myfile.txt", "wb") +if not f then + print("Something went wrong while opening the file", err) + return +end + +-- zapisz do pliku, wymuś zapis na dysk, a potem zamknij plik +f:write("Foobar") +f:flush() +f:close() + +-- otwórz myfile.txt do odczytu w trybie binarnym +-- w razie błędu zwraca nil oraz komunikat o błędzie +local f, err = io.open("path/to/myfile.txt", "rb") +if not f then + print("Something went wrong while opening the file", err) + return +end + +-- odczytaj cały plik jako łańcuch znaków +-- w razie błędu zwraca nil +local s = f:read("*a") +if not s then + print("Error while reading file") + return +end + +print(s) -- Foobar +``` + +* Możesz użyć [`os.rename()`](https://defold.com/ref/stable/os/#os.rename:oldname-newname) i [`os.remove()`](https://defold.com/ref/stable/os/#os.remove:filename) do zmieniania nazw plików i ich usuwania. + +* Możesz użyć [`sys.save()`](https://defold.com/ref/stable/sys/#sys.save:filename-table) i [`sys.load()`](https://defold.com/ref/stable/sys/#sys.load:filename) do odczytu i zapisu tabel Lua. Dodatkowe funkcje [`sys.*`](https://defold.com/ref/stable/sys/) pomagają w rozwiązywaniu ścieżek do plików w sposób niezależny od platformy. + +```lua +-- pobierz ścieżkę niezależną od platformy do pliku "highscore" dla aplikacji "mygame" +local path = sys.get_save_file("mygame", "highscore") + +-- zapisz tabelę Lua z danymi +local ok = sys.save(path, { highscore = 100 }) +if not ok then + print("Failed to save", path) + return +end + +-- wczytaj dane +local data = sys.load(path) +print(data.highscore) -- 100 +``` + + +## Lokalizacje plików i folderów +Lokalizacje plików i folderów można podzielić na trzy kategorie: + +* Pliki specyficzne dla aplikacji, tworzone przez twoją aplikację +* Pliki i foldery dołączone do aplikacji +* Pliki systemowe, do których uzyskuje dostęp twoja aplikacja + +### Jak zapisywać i odczytywać pliki specyficzne dla aplikacji +Podczas zapisywania i odczytywania plików specyficznych dla aplikacji, takich jak wyniki, ustawienia użytkownika i stan gry, zaleca się używanie lokalizacji dostarczonej przez system operacyjny i przeznaczonej właśnie do tego celu. Możesz użyć [`sys.get_save_file()`](https://defold.com/ref/stable/sys/#sys.get_save_file:application_id-file_name), aby uzyskać bezwzględną ścieżkę do pliku zależną od systemu operacyjnego. Gdy masz już tę ścieżkę bezwzględną, możesz korzystać z funkcji `sys.*`, `io.*` i `os.*` (patrz wyżej). + +[Sprawdź przykład pokazujący, jak używać `sys.save()` i `sys.load()`](/examples/file/sys_save_load/). + +### Jak uzyskiwać dostęp do plików dołączonych do aplikacji +Pliki możesz dołączać do aplikacji za pomocą zasobów pakietu i zasobów niestandardowych. + +#### Zasoby niestandardowe +:[Zasoby niestandardowe](../shared/custom-resources.md) + +```lua +-- Wczytaj dane poziomu do łańcucha znaków +local data, error = sys.load_resource("/assets/level_data.json") +-- Zdekoduj łańcuch JSON do tabeli Lua +if data then + local data_table = json.decode(data) + pprint(data_table) +else + print(error) +end +``` + +#### Zasoby pakietu +:[Zasoby pakietu](../shared/bundle-resources.md) + +```lua +local path = sys.get_application_path() +local f = io.open(path .. "/mycommonfile.txt", "rb") +local txt, err = f:read("*a") +if not txt then + print(err) + return +end +print(txt) +``` + +::: sidenote +Ze względów bezpieczeństwa przeglądarki internetowe, a przez to także każdy kod JavaScript uruchamiany w przeglądarce, nie mają dostępu do plików systemowych. Operacje na plikach w kompilacjach HTML5 w silniku Defold nadal działają, ale tylko na „wirtualnym systemie plików” korzystającym z API IndexedDB w przeglądarce. Oznacza to, że nie ma sposobu na dostęp do zasobów pakietu przy użyciu funkcji `io.*` lub `os.*`. Możesz jednak uzyskać do nich dostęp za pomocą `http.request()`. +::: + + +#### Porównanie zasobów niestandardowych i zasobów pakietu + +| Cecha | Zasoby niestandardowe | Zasoby pakietu | +|----------------------------|-------------------------------------------|----------------------------------------------| +| Szybkość wczytywania | Szybsza - pliki wczytywane z archiwum binarnego | Wolniejsza - pliki wczytywane z systemu plików | +| Wczytywanie części plików | Nie - tylko całe pliki | Tak - można odczytywać dowolne bajty z pliku | +| Modyfikacja po zbudowaniu | Nie - pliki przechowywane są w archiwum binarnym | Tak - pliki są przechowywane w lokalnym systemie plików | +| Obsługa HTML5 | Tak | Tak - ale dostęp odbywa się przez HTTP, a nie przez I/O plików | + + +### Dostęp do plików systemowych +Dostęp do plików systemowych może być ograniczony przez system operacyjny ze względów bezpieczeństwa. Możesz użyć natywnego rozszerzenia [`extension-directories`](https://defold.com/assets/extensiondirectories/), aby uzyskać bezwzględną ścieżkę do niektórych często używanych katalogów systemowych (np. documents, resource, temp). Gdy masz już bezwzględną ścieżkę do tych plików, możesz używać funkcji `io.*` i `os.*` do uzyskiwania do nich dostępu (patrz wyżej). + +::: sidenote +Ze względów bezpieczeństwa przeglądarki internetowe, a przez to także każdy kod JavaScript uruchamiany w przeglądarce, nie mają dostępu do plików systemowych. Operacje na plikach w kompilacjach HTML5 w silniku Defold nadal działają, ale tylko na „wirtualnym systemie plików” korzystającym z API IndexedDB w przeglądarce. Oznacza to, że nie ma sposobu na dostęp do plików systemowych w kompilacjach HTML5. +::: + +## Rozszerzenia +W [Asset Portal](https://defold.com/assets/) znajduje się kilka zasobów, które upraszczają dostęp do plików i folderów. Na przykład: + +* [Lua File System (LFS)](https://defold.com/assets/luafilesystemlfs/) - funkcje do pracy z katalogami, uprawnieniami do plików itp. +* [DefSave](https://defold.com/assets/defsave/) - moduł pomagający zapisywać i wczytywać konfigurację oraz dane gracza między sesjami. diff --git a/docs/pl/manuals/flash.md b/docs/pl/manuals/flash.md index 5f7f3118..0d5842f0 100644 --- a/docs/pl/manuals/flash.md +++ b/docs/pl/manuals/flash.md @@ -1,152 +1,152 @@ --- title: Defold dla użytkowników Flasha -brief: Ta instrukcja przedstawia Defold jako alternatywę dla deweloperów znających Flasha. Opisuje kluczowe koncepty Flasha i odpowiadające im narzędzia w Defoldzie. +brief: Ta instrukcja przedstawia Defold jako alternatywę dla twórców gier we Flashu. Omawia kluczowe pojęcia używane w tworzeniu gier we Flashu i pokazuje odpowiadające im narzędzia oraz metody w Defoldzie. --- # Defold dla użytkowników Flasha -Ta instrukcja przedstawia Defold jako alternatywę dla deweloperów znających Flasha. Opisuje kluczowe koncepty Flasha i odpowiadające im narzędzia w Defoldzie. +Ta instrukcja przedstawia Defold jako alternatywę dla twórców gier we Flashu. Omawia kluczowe pojęcia używane w tworzeniu gier we Flashu i pokazuje odpowiadające im narzędzia oraz metody w Defoldzie. ## Wprowadzenie -Jednymi z kluczowych zalet Flasha były jego przystępność i niski próg wejściowy. Nowi użytkownicy mogli nauczyć się szybko programu i tworzyć proste gry przy niewielkim nakładzie czasowym. Defold ma podobne zalety, dzięki udostępnieniu deweloperom narzędzi dedykowanych do tworzenia gier, jak i również oferując bardziej zaawansowanym użytkownikom spełnianie trudniejszych wymagań (przykładowo poprzez udostępnienie deweloperom możliwości edycji skryptu renderowania). +Jedną z głównych zalet Flasha była jego dostępność i niski próg wejścia. Nowi użytkownicy mogli szybko opanować program i w krótkim czasie tworzyć proste gry. Defold oferuje podobną korzyść, bo dostarcza zestaw narzędzi przeznaczonych do projektowania gier, a jednocześnie daje zaawansowanym twórcom możliwość budowania bardziej złożonych rozwiązań, na przykład przez edycję domyślnego skryptu renderowania. -Gry Flashowe były tworzone w języku ActionScript (ostatnia wersja - 3.0), a gry w Defold są tworzone z wykorzystaniem języka Lua. Nie skupiamy się tutaj jednak na szczegółowym porównaniu ActionScript z Lua. [Instrukcja o Lua w Defoldzie](/manuals/lua) jest dobrym wprowadzeniem do programowania w Lua w Defoldzie i sama odwołuje się do niezwykle przydatnej, oficjalnej [instrukcji programowania w Lua](https://www.lua.org/pil/) (pierwsza edycja), która jest dostępna za darmo w internecie. +Gry we Flashu są programowane w ActionScript (wersja 3.0 była najnowszą), a w Defoldzie skrypty pisze się w Lua. Ta instrukcja nie porównuje szczegółowo Lua i ActionScript 3.0. [Instrukcja Defold o Lua](/manuals/lua) dobrze wprowadza w programowanie w Lua w Defoldzie i odsyła do niezwykle przydatnej, darmowej [Programming in Lua](https://www.lua.org/pil/) (pierwsze wydanie), dostępnej online. -Artykuł Jesse'ego Warden'a pokazuje [porównanie Lua i ActionScript](http://jessewarden.com/2011/01/lua-for-actionscript-developers.html), które może być dobrym punktem startowym. Pamiętaj jendak, że istnieją głębsze różnice między tym jak Defold i Flash są skonstruowane niż tylko to, co jest widoczne pod względem języka. ActionScript i Flash są zorientowane obiektowo (object oriented) w sensie klas dziedziczeniem. Defold nie ma klas, ani dziedziczenia. Zawiera on jednak koncept *obiektu gry* (*game object*) który posiada reprezentację audiowizualną, logikę i dane. Operacje na obiektach gry są wykonywane przez *funkcje* udostępnione w API Defolda. Ponadto, Defold zaleca reaktywne podejście z użyciem *wiadomości* (*messages*) do komunikacji pomiędzy obiektami. Wiadomości te są konstruktem wyższej abstrakcji niż wywołanie funkcji i nie są przeznaczone do używania ich jakby były takimi wywołaniami. Te różnice są ważne i wymagają nieco przyzwyczajenia, ale nie będą też dogłębniej pokryte w tej tylko instrukcji. +Artykuł Jesse'ego Warden'a zawiera [podstawowe porównanie ActionScript i Lua](http://jessewarden.com/2011/01/lua-for-actionscript-developers.html), które może być dobrym punktem wyjścia. Warto jednak pamiętać, że Defold i Flash różnią się głębiej niż tylko na poziomie języka. ActionScript i Flash są obiektowe w klasycznym sensie, z klasami i dziedziczeniem. Defold nie ma klas ani dziedziczenia. Zamiast tego wprowadza pojęcie obiektu gry (ang. *game object*), który może zawierać reprezentację audiowizualną, zachowanie i dane. Operacje na obiektach gry wykonuje się za pomocą *funkcji* dostępnych w API Defold. Defold zachęca też do używania *wiadomości* do komunikacji między obiektami. Wiadomości są konstruktem wyższego poziomu niż wywołania metod i nie służą do używania ich w taki sposób. Te różnice są istotne i wymagają chwili, by się do nich przyzwyczaić, ale nie będą tu omawiane szczegółowo. -Zamiast tego, ten poradnik pozwala przejrzeć kluczowe aspekty tworzenia gier we Flashu o pokazać najbliższe im odpowiedniki w Defoldzie. Omówione są podobieństwa i różnice, a także często spotykane pułapki, aby umożliwić szybkie przejście z Flasha do Defolda. +Zamiast tego ta instrukcja pokazuje najważniejsze pojęcia znane z tworzenia gier we Flashu i wskazuje ich najbliższe odpowiedniki w Defoldzie. Omawia podobieństwa i różnice oraz typowe pułapki, aby ułatwić przejście z Flasha do Defolda. ## Klipy filmowe i obiekty gry -Klipy filmowe (Movie clips) są kluczowym komponentem tworzenia gier we Flashu. Są to symbole z unikalnymi osiami czasowymi (timeline). Najbliższym odpowiednikiem w Defoldzie jest obiekt gry (game object). +Klipy filmowe są kluczowym elementem tworzenia gier we Flashu. Są to symbole, z których każdy ma własną oś czasu. Najbliższym odpowiednikiem w Defoldzie jest obiekt gry. ![game object and movieclip](images/flash/go_movieclip.png) -Jednak w przeciwieństwie do klipów, Defoldowe obiekty gry nie mają osi czasu. Składają się zamiast tego z wielu różnych komponentów, takich jak między innymi sprite'y, dźwięki i skryptu (więcej szczegółów na temat komponentów znajdziesz w [dokumentacji o podstwowych elementach](/manuals/building-blocks) i powiązanych). Obiekty gry na obrazku poniżej zawierają komponenty: sprite i skrypt. Skrypt jest wykorzystywany do kontrolowania zachowania i wyglądu obiektu w trakcie jego istnienia: +W przeciwieństwie do klipów filmowych we Flashu obiekty gry w Defoldzie nie mają osi czasu. Zamiast tego składają się z wielu komponentów. Do komponentów należą między innymi sprites, dźwięki i skrypty (więcej informacji o dostępnych komponentach znajdziesz w [dokumentacji o building blocks](/manuals/building-blocks) i powiązanych materiałach). Obiekt gry na zrzucie poniżej składa się ze sprite'a i skryptu. Komponent skryptu służy do sterowania zachowaniem i wyglądem obiektów gry w trakcie ich cyklu życia: ![script component](images/flash/script_component.png) -Gdy klipy filmowe mogą zawierać inne klipy, obiekty gry nie mogą *zawierać* innych obiektów. Aczkolwiek, obiekty gry mogą być *dziećmi* innych obiektów, tworząc hierarchię, dzięki której można je przemieszczać, skalować czy obracać jednocześnie. +Klipy filmowe mogą zawierać inne klipy filmowe, natomiast obiekty gry nie mogą *zawierać* innych obiektów gry. Mogą jednak być *podpięte* jako dzieci innych obiektów gry, tworząc hierarchie, które można wspólnie przesuwać, skalować lub obracać. -## Flash — ręczne tworzenie klipów +## Flash — ręczne tworzenie klipów filmowych -We Flashu, instancje klipów filmowych mogą być dodawane do sceny ręcznie przez przeciąganie ich z biblioteki na oś czasu. Pokazane to jest na obrazku poniżej, gdzie każde logo Flasha jest instancją klipu "logo": +We Flashu instancje klipów filmowych można dodawać do sceny ręcznie, przeciągając je z biblioteki na oś czasu. Pokazuje to zrzut poniżej, gdzie każde logo Flasha jest instancją klipu filmowego "logo": ![manual movie clips](images/flash/manual_movie_clips.png) ## Defold — ręczne tworzenie obiektów gry -Jak wspomniano, Defold nie posiada konceptu osi czasu. Zamiast tego obiekty są zorganizowane w kolekcji (collections). Kolekcje są kontenerami (czy prefabami), które mają w sobie obiekty gry i/lub inne kolekcje. Ogólnie, gra może składać się z jednej kolekcji (pierwsza, podstawowa kolekcja nazywana jest bootstrap). Częściej jednak, gry wykorzystują ich więcej, czy to poprzez ręczne dodanie ich do głównej, bootstrapowej kolekcji “main”, czy to przez dynamiczne załadowanie kolekcji przez [pełnomocnika kolekcji](/manuals/collection-proxy). Idea dynamicznego załadowywania kolekcji (np. jako poziomów, okien menu czy scen) nie ma odpowiednika we Flashu. +Jak wspomniano wcześniej, Defold nie ma pojęcia osi czasu. Zamiast tego obiekty gry są organizowane w kolekcjach. Kolekcje są kontenerami, czyli prefabami, które przechowują obiekty gry i inne kolekcje. W najprostszym przypadku gra może składać się tylko z jednej kolekcji. Częściej Defold korzysta z wielu kolekcji, dodanych ręcznie do bootstrapowej kolekcji "main" albo wczytywanych dynamicznie przez [collection proxy](/manuals/collection-proxy). Pojęcie wczytywania "poziomów" lub "ekranów" nie ma bezpośredniego odpowiednika we Flashu. -W poniższym przykładzie, główna kolekcja "main" zawiera trzy instancje (pokazane po prawej, w panelu *Outline*) z obiektami gry "logo" (które można zobaczyć po lewej, w panelu *Assets*): +W przykładzie poniżej kolekcja "main" zawiera trzy instancje klipu filmowego "logo" (na liście po prawej, w oknie *Outline*), widoczne jako obiekty gry "logo" po lewej, w oknie *Assets*: ![manual game objects](images/flash/manual_game_objects.png) -## Flash — odwoływanie się do ręcznie stworzonych klipów +## Flash — odwoływanie się do ręcznie utworzonych klipów filmowych -Odwoływanie się do ręcznie stworzonych klipów we Flashu wymaga używania ręcznie zdefiniowanych nazw instancji: +Odwoływanie się do ręcznie utworzonych klipów filmowych we Flashu wymaga użycia ręcznie zdefiniowanej nazwy instancji: ![flash instance name](images/flash/flash_instance_name.png) -## Defold - ID obiektu gry +## Defold — identyfikator obiektu gry -W Defoldzie, każdy obiekt gry i komponent mają swój unikalny ID i można się do nich odwoływać poprzez adresy. W większości przypadków prosta nazwa lub skrót są wystarczające, na przykład: +W Defoldzie wszystkie obiekty gry i komponenty są adresowane przez adres. W większości przypadków wystarcza prosta nazwa albo skrót. Na przykład: -- `"."` adres obecnego obiektu gry -- `"#"` adres obecnego komponentu (skryptu). -- `"logo"` adres obiektu gry o ID: "logo". -- `"#script"` adres komponentu o ID: "script" w obecnym obiekcie gry. -- `"logo#script"` adres komponentu o ID: "script" w obiekcie gry o ID: "logo". +- `"."` adresuje bieżący obiekt gry. +- `"#"` adresuje bieżący komponent, czyli skrypt. +- `"logo"` adresuje obiekt gry o id `"logo"`. +- `"#script"` adresuje komponent o id `"script"` w bieżącym obiekcie gry. +- `"logo#script"` adresuje komponent o id `"script"` w obiekcie gry o id `"logo"`. -Adres ręcznie umieszczonych obiektów gry jest zdeterminowany przez nadane *Id* (zobacz prawy, dolny róg obrazka). ID musi być unikalne dla danego pliku kolekcji. Edytor automatycznie ustawia id za Ciebie, ale możesz je zmienić dla każdej instancji obiektu, któ©y tworzysz. +Adres ręcznie umieszczonych obiektów gry jest określany przez właściwość *Id* przypisaną do instancji (zobacz prawy dolny róg zrzutu). Id musi być unikalne w obrębie bieżącego pliku kolekcji. Edytor ustawia id automatycznie, ale można je zmienić dla każdej tworzonej instancji obiektu gry. ![game object id](images/flash/game_object_id.png) ::: sidenote -Możesz znaleźć id obiektu używając następującego kodu `print(go.get_id())` w skrypcie, będącym komponentem danego obiektu. Spowoduje to wyświetlenie id obecnego obiektu w konsoli. +Id obiektu gry można odczytać, uruchamiając w jego komponencie skryptu taki kod: `print(go.get_id())`. Wypisze on id bieżącego obiektu gry w konsoli. ::: -Model adresowania i przesyłania wiadomości to kluczowe koncepty w tworzeniu gier w Defoldzie. Ta [instrukcja adresowania](/manuals/addressing) i ta [instrukcja przesyłania wiadomości](/manuals/message-passing) wyjaśniają je w szczegółach. +Model adresowania i przesyłanie wiadomości to kluczowe pojęcia w tworzeniu gier w Defoldzie. [Instrukcja adresowania](/manuals/addressing) i [instrukcja przesyłania wiadomości](/manuals/message-passing) omawiają je szczegółowo. -## Flash — dynamiczne tworzenie klipów +## Flash — dynamiczne tworzenie klipów filmowych -Aby dynamicznie utworzyć klipy filmowe we Flashu, najpierw należy stworzyć połaczenie w ActionScripcie (Linkage): +Aby dynamicznie tworzyć klipy filmowe we Flashu, najpierw trzeba skonfigurować ActionScript Linkage: ![actionscript linkage](images/flash/actionscript_linkage.png) -Tworzy to klasę (Logo w tym przypadu), która później pozwala na tworzenie nowych instancji tej klasy. Dodawanie instancji klasy Logo do sceny wygląda następująco: +Tworzy to klasę (w tym przypadku Logo), która umożliwia tworzenie nowych instancji tej klasy. Dodanie instancji klasy Logo do Stage może wyglądać tak: ```as var logo:Logo = new Logo(); addChild(logo); ``` -## Defold — tworzenie obiektów gry wykorzystując fabryki +## Defold — tworzenie obiektów gry za pomocą fabryk -W Defoldzie, dynamiczne tworzenie obiektów gry jest możliwe poprzez wykorzystanie *fabryk* (*factories*). Fabryki są komponentami służącymi do tworzenia instancji specyficznych obiektów gry. W tym przykładzie, fabryka została utworzona z obiektem gry "logo" jako prototypem: +W Defoldzie dynamiczne tworzenie obiektów gry odbywa się za pomocą *fabryk*. Fabryki to komponenty służące do tworzenia kopii konkretnego obiektu gry. W tym przykładzie fabrykę utworzono na podstawie obiektu gry "logo" użytego jako prototyp: ![logo factory](images/flash/logo_factory.png) -Ważne jest, że fabryki, jak każdy inny komponent, muszą być dodane do obiektu gry zanim zostaną użyte. W tym przykładzie, stworzyliśmy obiekt gry nazwany "factories", aby zawrzeć w nim komponenty - fabryki: +Warto pamiętać, że fabryki, podobnie jak wszystkie komponenty, trzeba dodać do obiektu gry, zanim będzie można ich użyć. W tym przykładzie utworzono obiekt gry "factories", aby przechowywał komponent fabryki: ![factory component](images/flash/factory_component.png) -Do wywołania tworzenia instancji obiektu gry logo używamy funkcji: +Funkcja tworząca instancję obiektu gry logo wygląda tak: ```lua local logo_id = factory.create("factories#logo_factory") ``` -Adres URL jest wymaganym parametrem funkcji `factory.create()`. Ponadto, można dodać opcjonalne parametry do zdefiniowania pozycji, rotacji, właściwości i skali. Więcej szczegółów na temat fabryk znajdziesz w [instrukcji do fabryk](/manuals/factory). Warto zaznaczyć, że wywołanie `factory.create()` zwraca id utworzonego obiektu. To id może być zapisane (np. w tabeli) i utrzymywane, aby później móc się do niego odnieść. +Adres jest wymaganym parametrem `factory.create()`. Dodatkowo można podać parametry opcjonalne ustawiające pozycję, rotację, właściwości i skalę. Więcej informacji o komponencie fabryki znajdziesz w [instrukcji fabryki](/manuals/factory). Warto też zauważyć, że `factory.create()` zwraca id utworzonego obiektu gry. Id można później zapisać w tabeli, czyli odpowiedniku tablicy w Lua, i odwoływać się do niego później. -## Flash - Scena +## Flash — Stage -We Flashu, wykorzystuje się Oś czasu (na górze obrazka poniżej) i Scenę (poniżej osi): +We Flashu znamy Timeline, widoczną w górnej części zrzutu poniżej, oraz Stage, widoczną pod Timeline: ![timeline and stage](images/flash/stage.png) -Jak wspomniano wyżej, scena jest najważniejszym pojemnikiem gry Flashowej i jest tworzona przy każdym eksporcie projektu. Scena ma domyślnie jedno dziecko, główną oś *MainTimeline*. Każdy klip genrowany w projekcie ma swoją własną oś i może być jednocześnie kontenerem na inne elementy, w tym inne klipy. +Jak wspomniano wcześniej w części o klipach filmowych, Stage jest zasadniczo najwyższym kontenerem gry we Flashu i powstaje przy każdym eksporcie projektu. Stage ma domyślnie jedno dziecko, *`MainTimeline`*. Każdy klip filmowy wygenerowany w projekcie ma własną oś czasu i może służyć jako kontener dla innych symboli, w tym klipów filmowych. -## Defold — Kolekcja +## Defold — kolekcje -Defoldowym odpowiednikiem Flashowej sceny jest kolekcja (collection). Wraz ze startem silnika Defold tworzy on nowy świat gry na podstawie pliku głównej kolekcji bootstrapowej. Domyślnie, plik ten nazywany jest "main.collection", ale możesz zmienić tę nazwę jak i kolekcję, która jest najpierw wczytywane poprzez odpowiednie pole w pliku *game.project*: +Odpowiednikiem Stage we Flashu w Defoldzie jest kolekcja. Gdy silnik się uruchamia, tworzy nowy świat gry na podstawie zawartości pliku kolekcji. Domyślnie ten plik nazywa się main.collection, ale można zmienić kolekcję wczytywaną przy starcie, edytując plik ustawień *game.project* w katalogu głównym każdego projektu Defold: ![game.project](images/flash/game_project.png) -Kolekcje są również pojemnikami/kontenerami używanymi do organizowania obiektów gry i innych kolekcji. Zawartość kolekcji może również zostać utworzona dynamicznie przez skrypt wykorzystujący komponent fabryki kolekcji ([collection factory](/manuals/collection-factory/#spawning-a-collection)), co działa identycznie jak dla fabryk pojedynczych obiektów. Jest to przydatne przy tworzeniu instancji grup elementów jak np. przeciwników w grze czy zbioru monet do zebrania na poziomie. Na poniższym obrazku ręcznie umieszczono dwie instancje kolekcji "logos" w głównej kolekcji "main". +Kolekcje są kontenerami używanymi w edytorze do organizowania obiektów gry i innych kolekcji. Zawartość kolekcji można też tworzyć w czasie działania gry za pomocą [collection factory](/manuals/collection-factory/#spawning-a-collection), która działa tak samo jak zwykła fabryka obiektów gry. Jest to przydatne na przykład do tworzenia grup przeciwników albo wzorców zbieralnych monet. Na zrzucie poniżej ręcznie umieszczono dwie instancje kolekcji "logos" w kolekcji "main". ![collection](images/flash/collection.png) -W niektórych przypadkach, możesz chcieć załadować kompletnie nowy świat gry. Pełnomocnik kolekcji ([collection proxy](/manuals/collection-proxy/)) pozwala na stworzenie takiego nowego świata gry bazując na zawartości pliku kolekcji. Może to być przydatne do wczytywania nowych poiomów w grze, mini gier lub cutscenek. +W niektórych sytuacjach chcesz wczytać całkowicie nowy świat gry. Komponent [collection proxy](/manuals/collection-proxy/) pozwala utworzyć nowy świat gry na podstawie zawartości pliku kolekcji. Przydaje się to przy wczytywaniu nowych poziomów, minigier lub cutscenek. ## Flash — oś czasu -Oś czasu we Flashu jest używana głównie do tworzenia animacji poprzez zmiany klatek lub kształtu i ruchu. Ogólne ustawienie klatek na sekundę, czyli FPS (frames per second) definiuje długość z jaką wyświetlana jest klatka. Zaawansowani użytkownicy mogą modyfikować ogólną liczbę klatek na sekundę bądź indywidualnie klipy filmowe. +Oś czasu we Flashu służy przede wszystkim do animacji, z użyciem różnych technik klatka po klatce albo tweenów kształtu i ruchu. Ogólne ustawienie FPS projektu określa czas wyświetlania jednej klatki. Zaawansowani użytkownicy mogą zmieniać ogólny FPS gry, a nawet FPS pojedynczych klipów filmowych. -Zmiany kształtu pozwalają na interpolację grafiki wektorowej między dwoma stanami. Jest to najczęściej wykorzystywane do prostych zmian kształtu lub transformowania jednego kształtu w inny, jak np. poniższa demonstracja zmiany kwadradtu w trójkąt: +Tweeny kształtu pozwalają interpolować grafikę wektorową między dwoma stanami. Jest to zwykle przydatne tylko dla prostych kształtów i zastosowań, co pokazuje przykład przekształcania kwadratu w trójkąt: ![timeline](images/flash/timeline.png) -Zmiany ruchu pozwalają na animowanie różnych właściwości obiektu, nie tylko pozycji, ale także rotacji czy rozmiaru. W poniższym przykładzie, wszystkie wymienione właściowści są modyfikowane: +Tweeny ruchu pozwalają animować różne właściwości obiektu, w tym rozmiar, pozycję i rotację. W przykładzie poniżej zmodyfikowano wszystkie wymienione właściwości. ![motion tween](images/flash/tween.png) -## Defold — animowanie właściwości +## Defold — animacja właściwości -Defold operuje natomiast na grafice rastrowej, stąd nie ma bezpośredniego odpowiednika animowania ruchu jak we Flashu. Jednak, zamiast tego oferuje potężne [animowanie właściwości](/ref/go/#go.animate). Jest to wywoływane przez skrypt poprzez funkcję `go.animate()`. Funkcja ta animuje wybraną właściwość (property) (takie jak kolor, skala, rotacja czy pozycja) od wartości początkowej do docelowej, używając jednej z wielu funkcji złagodnienia (easing functions), włączając w to przygotowane przez użytkownika funkcje. Podczas gdy Flash wymagał od użytkowników pracy przy tworzeniu bardziej zaawansowanych funkcji łagodzenia, Defold zawiera już zdefiniowane [wiele takich funkcji](/manuals/animation/#easing) wbudowanych w silnik. +Defold pracuje na obrazach rastrowych, a nie grafice wektorowej, więc nie ma odpowiednika tweeningu kształtu. Ma jednak bardzo mocny odpowiednik tweeningu ruchu w postaci [animacji właściwości](/ref/go/#go.animate). Wykonuje się ją ze skryptu za pomocą funkcji `go.animate()`. Funkcja go.animate() animuje właściwość, taką jak kolor, skala, rotacja albo pozycja, od wartości początkowej do docelowej, korzystając z jednej z wielu dostępnych funkcji easing, w tym także własnych. Tam, gdzie Flash wymagał własnej implementacji bardziej zaawansowanych funkcji easing, Defold ma w silniku [wiele funkcji easing](/manuals/animation/#easing). -Podczas gdy Flash wykorzystuje ramki kluczowe (keyframes) grafiki na osi casu animacji, jednym z głównych sposobów na animację grafiki w Defoldzie jest animacja poklatkowa (flipbook animation) zaimportowanych sekwencji. Animacje są zorganiozwane w komponencie galerii obrazów zwanym Atlas. Poniżej przedstawiony jest atlas dla postaci z animacją nazwaną "run". Sekwencja ta składa się z ramek: +Tam, gdzie Flash wykorzystuje klatki kluczowe grafiki na osi czasu, jedną z głównych metod animacji grafiki w Defoldzie jest animacja flipbook importowanych sekwencji obrazów. Animacje są organizowane w komponencie obiektu gry zwanym atlasem. W tym przykładzie atlas zawiera postać z sekwencją animacji o nazwie "run". Składa się ona z serii plików png: ![flipbook](images/flash/flipbook.png) -## Flash — indeks głębii +## Flash — indeks głębi -We Flashu lista wyświetlania (display list) determinuje co jest pokazywane w jakiej kolejności. Kolejność obiektów w kontenerze (jak np. Scena/Stage) jest ustalana na podstawie indeksu głębii. Obiektu dodane do kontenera używając funkcji `addChild()` będą automatycznie zajmowały pozycję na szczycie listy, czyli indeksy rozpoczynające się od 0 i zwiększające z każdym dodanym elementem. Na obrazku poniżej widzimy wygenerowane 3 instancje klipów filmowych "logo": +We Flashu display list określa, co jest wyświetlane i w jakiej kolejności. Kolejność obiektów w kontenerze, takim jak Stage, jest obsługiwana przez indeks. Obiekty dodane do kontenera metodą `addChild()` automatycznie zajmują najwyższą pozycję w indeksie, zaczynając od 0 i zwiększając ją przy każdym kolejnym obiekcie. Na zrzucie poniżej wygenerowano trzy instancje klipu filmowego "logo": ![depth index](images/flash/depth_index.png) -Pozycja w liście wyświetlania jest wskazywana przez liczbę obok każdej z instancji. Pomijając ustawianie klipów w osi x/y, poniższy kod pokazuje jak można generować klipy "logo": +Pozycje na display list są oznaczone numerami obok każdej instancji logo. Pomijając kod odpowiedzialny za pozycję x/y klipów filmowych, powyższy wynik można było uzyskać tak: ```as var logo1:Logo = new Logo(); @@ -158,33 +158,33 @@ addChild(logo2); addChild(logo3); ``` -To, czy obiekt jest wyświetlany nad czy pod innym jest zdeterminowane przez ich relatywną pozycję (indeks) w liście wyświetlania. Dobrze obrazuje to zamiana indeksów dwóch obiektów, np: +To, czy obiekt jest wyświetlany nad innym, czy pod nim, zależy od ich względnej pozycji w indeksie display list. Dobrze pokazuje to zamiana pozycji dwóch obiektów, na przykład: ```as swapChildren(logo2,logo3); ``` -Wynik wygląda następująco (ze zaktualizowanymi indeksami): +Wynik wyglądałby tak, jak poniżej, z zaktualizowaną pozycją indeksu: ![depth index](images/flash/depth_index_2.png) -## Defold — pozycja w osi Z +## Defold — pozycja Z -Pozycja obiektów gry w Defoldzie jest reprezentowana przez wektor składający się z trzech składowych: x, y, z. Pozycja w osi Z determinuje pozycję głębii, tak jak indeks we Flashu. W domyślnym, wbudowanym [skrypcie renderowania](/manuals/render), pozycje na osi Z są ograniczone między -1 a 1. +Pozycje obiektów gry w Defoldzie są reprezentowane przez wektory złożone z trzech składowych: x, y i z. Pozycja Z określa głębię obiektu gry. W domyślnym [skrypcie renderowania](/manuals/render) zakres dostępnych wartości Z wynosi od -1 do 1. ::: sidenote -Wtedy obiekty gry z pozycją poza zakresem -1 do 1 nie będę wyświetlane. Jest to częsta pułapka, w którą mogą wpaść nowi użytkownicy Defolda, więc warto pamiętać o tym, jeśli dany obiekt nie jest widoczny, kiedy spodziewasz się, że powinien być. +Obiekty gry z pozycją Z poza zakresem -1 do 1 nie będą renderowane, a więc nie będą widoczne. To częsta pułapka dla osób zaczynających pracę z Defoldem i warto o niej pamiętać, jeśli obiekt nie jest widoczny, mimo że powinien być. ::: -W przeciwieństwie do Flasha, gdzie tylko edytor ustawia indeks (i umożliwia ich modyfikację poprzez operacje *Bring Forward* czy *Send Backward*), Defold umożliwia bezpośrednie ustawienie pozycji na osi Z w edytorze oraz w kodzie. Na poniższym obrazku, widać obiekt "logo3" wyświetlony na samej górze i posiadający pozycję na osi Z: 0.2. Pozostałe obiekty mają wartości z odpowiednio 0.0 i 0.1. +W przeciwieństwie do Flasha, gdzie edytor tylko pośrednio sugeruje indeks głębi i pozwala zmieniać go poleceniami takimi jak *Bring Forward* i *Send Backward*, Defold pozwala ustawić pozycję Z obiektów bezpośrednio w edytorze. Na zrzucie poniżej widać, że "logo3" jest wyświetlony najwyżej i ma pozycję Z 0.2. Pozostałe obiekty gry mają pozycje Z 0.0 i 0.1. ![z-order](images/flash/z_order.png) -Zapamiętaj, że pozycja na osi Z obiektu gry zagnieżdżonego w kolekcji/ach jes determinowana przez jego własną pozycję Z razem z pozycją rodziców. Przykładowo, wyobraź sobie, że powyższe obiekty zostały umieszczone w kolekcji "logos", która z kolei została umieszczona w kolekcji głównej "main" (zobacz obrazek poniżej). Jeśli kolekcja "logos" ma pozycję Z 0.9, pozycje na osi Z obiektów gry będą dodane do pozycji ich kolekcji i będą wynosić kolejno 0.9, 1.0 oraz 1.1. Dlatego w domyślnym renderowaniu obiekt "logo3" nie będzie wyświetlany, ponieważ jego absolutna pozycja na osi Z jest większa niż 1. +Warto zauważyć, że pozycja Z obiektu gry zagnieżdżonego w jednej lub wielu kolekcjach zależy od jego własnej pozycji Z oraz pozycji wszystkich rodziców. Wyobraź sobie na przykład, że powyższe obiekty logo znajdują się w kolekcji "logos", a ta kolekcja jest umieszczona w "main" (zobacz zrzut poniżej). Gdyby kolekcja "logos" miała pozycję Z 0.9, pozycje Z obiektów wewnątrz wyniosłyby 0.9, 1.0 i 1.1. W efekcie "logo3" nie zostałby wyrenderowany, ponieważ jego pozycja Z byłaby większa niż 1. ![z-order](images/flash/z_order_outline.png) -Pozycja na osi Z obiektów gry może być zmieniona używając skryptu. Przykładowo jak w poniższym kodzie, który jest umieszczony w skrypcie obiektu gry: +Pozycję Z obiektu gry można oczywiście zmieniać w skrypcie. Załóżmy, że poniższy kod znajduje się w komponencie skryptu obiektu gry: ```lua local pos = go.get_position() @@ -192,114 +192,114 @@ pos.z = 0.5 go.set_position(pos) ``` -## Flash — detekcja kolizji za pomocą hitTestObject oraz hitTestPoint +## Flash `hitTestObject` i `hitTestPoint` - wykrywanie kolizji -Podstawowa detekcja kolizji we Flashu jest uzyskiwana dzięki funkcji `hitTestObject()`. W poniższym przykładzie, mamy dwa klipy filmowe: "bullet" i "bullseye". Są one przedstawione poniżej. Niebieski prostokąt jest widoczny, kiedy wybrany jest symbol w edytorze Flash i to właśnie ten prostokąt jest brany pod uwagę podczas wywołania funkcji `hitTestObject()`. +Podstawowe wykrywanie kolizji we Flashu realizuje się metodą `hitTestObject()`. W tym przykładzie są dwa klipy filmowe: "bullet" i "bullseye". Widać je na zrzucie poniżej. Niebieska ramka jest widoczna po zaznaczeniu symboli w edytorze Flasha i to właśnie ona decyduje o wyniku `hitTestObject()`. ![hit test](images/flash/hittest.png) -Wykrywanie kolizji używając funkcji `hitTestObject()` można wykonać w ten sposób: +Wykrywanie kolizji metodą `hitTestObject()` wygląda tak: ```as bullet.hitTestObject(bullseye); ``` -Wykorzystując jednak te prostokąty (boundary boxes) nie otrzymalibyśmy odpowiedniego wyniku w takim przypadku: +W tym przypadku użycie ramek ograniczających nie byłoby właściwe, bo trafienie zostałoby zarejestrowane w scenariuszu poniżej: ![hit test bounding box](images/flash/hitboundingbox.png) -Alternatywą dla `hitTestObject()` jest funkcja `hitTestPoint()`. Zawiera ona parametr `shapeFlag`, który pozwala na sprawdzanie kolizji w stosunku do faktycznych pikseli obrazka, a nie do prostokątu obejmującego cały obrazek. Wykrywanie kolizji używając funckji `hitTestPoint()` można wykonać w ten sposób: +Alternatywą dla `hitTestObject()` jest `hitTestPoint()`. Metoda ta ma parametr `shapeFlag`, który pozwala sprawdzać trafienia względem rzeczywistych pikseli obiektu, a nie względem ramki ograniczającej. Wykrywanie kolizji za pomocą `hitTestPoint()` mogłoby wyglądać tak: ```as bullseye.hitTestPoint(bullet.x, bullet.y, true); ``` -Powyższa linijka sprawdzi pozycje x i y obiektu pocisku (, który jest w lewym górnym rogu) w stosunku do aktualnego kształtu obiektu. Ponieważ funkcja `hitTestPoint()` sprawdza punkt, wybór odpowiedniego punktu/ów jest główną sprawa do wzięcia pod uwagę. +Ta linia sprawdza pozycję x i y pocisku w stosunku do kształtu celu. Ponieważ `hitTestPoint()` sprawdza punkt względem kształtu, wybór właściwego punktu lub punktów do sprawdzenia jest kluczowy. ## Defold — obiekty kolizji -Defold posiada wbudowany silnik fizyki, który może wykrywać kolizje i pozwala skryptom również na nie reagować. Detekcja kolizji w Defoldzie rozpoczyna się z przypisaniem komponentu zwanego obiektem kolizji (collision object) do obiektu gry. Na poniższym obrazku, mamy obiekt kolizji "bullet_collision_object" przypisany do obiektu gry "bullet". Kształt kolizji jest wskazywany przez czerwony prostokąt (widoczny tylko w edytorze, nie w grze): +Defold zawiera silnik fizyki, który potrafi wykrywać kolizje i pozwala skryptowi reagować na nie. Wykrywanie kolizji w Defoldzie zaczyna się od przypisania komponentów obiektu kolizji do obiektów gry. Na zrzucie poniżej dodano obiekt kolizji do obiektu gry "bullet". Obiekt kolizji jest oznaczony czerwonym półprzezroczystym prostokątem, widocznym tylko w edytorze: ![collision object](images/flash/collision_object.png) -Defold zawiera zmodyfikowaną wersję silnika fizyki Box2D, który umożliwia również realistyczną, automatyczną symulację kolizji i fizyki odbić. Ten poradnik zakłada wykorzystywanie obiektów kolizji kinematycznych, ponieważ najbliższe są one wykrywaniu kolizji we Flashu. Więcej szczegółów na temat komponentów kolizji dynamicznych znajdziesz w [instrukcji silnika fizyki](/manuals/physics). +Defold zawiera zmodyfikowaną wersję silnika fizyki Box2D, który może automatycznie symulować realistyczne kolizje. Ta instrukcja zakłada użycie kinematycznych obiektów kolizji, ponieważ najbardziej przypominają one wykrywanie kolizji we Flashu. Więcej o dynamicznych obiektach kolizji można przeczytać w [instrukcji fizyki](/manuals/physics). -Obiekt kolizji (collision object) zawiera następujące właściwości: +Komponent obiektu kolizji ma następujące właściwości: ![collision object properties](images/flash/collision_object_properties.png) -Kształt prostokąta został użyty, ponieważ najbardziej przypominał kształt pocisku. Inny kształt - sfera, została użyta do do obiektu celu ("bullseye"). Ustawienie typu kolizji na kinematyczną (Kinematic) oznacza, że rozwiązywanie efektu kolizji jest wykonywane przez skrypt, a nie wbudowany silnik symulacji fizyki (tak jak powyżej, więcej szczegółów w [instrukcji silnika fizyki](/manuals/physics)). Właściwości grupa (Group) i maska (Mask) determinują odpowiednio do jakiej grupy należy dany obiekt oraz z jakimi innymi grupami będzie on kolidował. Powyższe ustawienie oznacza, że obiekt pocisku będący w grupie "bullet" może kolidować z obiektami z grupy "target". Jednak, gdyby maska posiadała również inną grupę, jak poniżej: +Użyto kształtu box, bo najlepiej pasował do grafiki pocisku. Inny kształt używany przy kolizjach 2D, sphere, zostanie użyty dla celu. Ustawienie typu na Kinematic oznacza, że rozstrzyganie kolizji wykonuje skrypt, a nie wbudowany silnik fizyki. Więcej informacji o pozostałych typach znajdziesz w [instrukcji fizyki](/manuals/physics). Właściwości group i mask określają odpowiednio, do jakiej grupy należy obiekt i z jakimi grupami ma być sprawdzany. Bieżąca konfiguracja oznacza, że "bullet" może kolidować tylko z "target". Wyobraź sobie, że konfigurację zmieniono tak jak poniżej: ![collision group/mask](images/flash/collision_groupmask.png) -pociski mogłyby kolidować z obiektami z grup "target" oraz "bullet", czyli również z innymi pociskami. Dla obiektu celu "bullseye", odpowiednie właściwości ustawiamy jak poniżej: +Teraz pociski mogą kolidować z celami i innymi pociskami. Dla porównania obiekt kolizji dla celu wygląda tak: ![collision object bullet](images/flash/collision_object_bullet.png) -Zwróć uwagę, że teraz właściwość *Group* jest ustawiona jako "target", a właściwość *Mask* jest ustawiona jako "bullet". +Zwróć uwagę, że właściwość *Group* jest ustawiona na "target", a *Mask* na "bullet". -We Flashu, detekcja kolizji jest sprawdzana tylko, kiedy jawnie wywołamy ją ze skryptu. W Defoldzie natomiast detekcja kolizji jest sprawdzana ciągle, w tle, jeśli tylko obiekty kolizji są włączone. W momencie, kiedy nastąpi jakakolwiek kolizja, odpowiednie wiadomości są wysyłane do każdego z komponentów obiektów, które brały udział w kolizji (przy czym najważniejsze tutaj są komponenty skrypty). Wiadomości te, czyli [collision_response i contact_point_response](/manuals/physics-messages) zawierają wszystkie informacje wymagane do rozwiązania kolizji. +We Flashu wykrywanie kolizji odbywa się tylko wtedy, gdy zostanie jawnie wywołane ze skryptu. W Defoldzie wykrywanie kolizji działa cały czas w tle, dopóki obiekt kolizji jest włączony. Gdy dojdzie do kolizji, odpowiednie wiadomości są wysyłane do wszystkich komponentów obiektu gry, a przede wszystkim do komponentów skryptu. Są to wiadomości [collision_response i contact_point_response](/manuals/physics-messages), które zawierają wszystkie informacje potrzebne do rozwiązania kolizji w pożądany sposób. -Wykrywanie kolizji przez silnik Defold jest więc dużo bardziej zaawansowane niż we Flashu z możliwością wykrywania kolizji między dosyć skomplikowanymi kształtami przy niewielkim nakładzie pracy przy ich ustawianiu. Detekcja kolizji jest automatyczna, co oznacza sprawdzanie wielu obiektów pomiędzy wieloma grupami, więc bezpośrednie sprawdzanie kolizji nie jest wymagane. Największym brakiem jest więc tutaj brak odpowiednika flagi shapeFlag. Jednak, dla większości przypadków kombinacje podstawowych kształtów takich jak prostokąt i sfera są wystarczające. Dla najbardziej zaawansowanych pod tym względem przypadków dowolne kształty [są możliwe](//forum.defold.com/t/does-defold-support-only-three-shapes-for-collision-solved/1985). +Zaletą wykrywania kolizji w Defoldzie jest to, że jest bardziej zaawansowane niż we Flashu i pozwala wykrywać kolizje między względnie złożonymi kształtami przy niewielkim nakładzie pracy konfiguracyjnej. Wykrywanie kolizji jest automatyczne, więc nie trzeba iterować po różnych obiektach w poszczególnych grupach kolizji i ręcznie wykonywać testów trafień. Główną wadą jest brak odpowiednika `shapeFlag` z Flasha. Jednak w większości zastosowań wystarczają kombinacje podstawowych kształtów box i sphere. W bardziej złożonych przypadkach [można](//forum.defold.com/t/does-defold-support-only-three-shapes-for-collision-solved/1985) użyć własnych kształtów. -## Flash — zarządzanie zdarzeniami +## Flash — obsługa zdarzeń -Obiekty zdarzeń (event objects) i przypisani do nich reagujący (listeners) są wykorzystywane do wykrywania różnych zdarzeń (np. kliknięć myszką, naciśnięć klawiszy) i wykonywania określonych akcji w odpowiedzi na nie. Jest wiele różnych zdarzeń, z którymi można pracować. +Obiekty zdarzeń i powiązani z nimi listenerzy służą do wykrywania różnych zdarzeń, na przykład kliknięć myszą, naciśnięć przycisków czy wczytywania klipów, oraz do wyzwalania odpowiednich akcji. Do dyspozycji jest wiele różnych typów zdarzeń. -## Defold — funkcje call-back i przesyłanie wiadomości +## Defold — funkcje callback i wiadomości -Odpowiednikiem zarządzania zdarzeniami w Defoldzie składa się z kilku aspektów. Po pierwsze, każdy komponent skrypt posiada odpowiednie, specjalne funkcji callback-i odpowiadające na odpowiednie wydarzenia. Są to: +Odpowiednik systemu obsługi zdarzeń z Flasha w Defoldzie składa się z kilku elementów. Po pierwsze, każdy komponent skryptu ma zestaw funkcji callback wykrywających konkretne zdarzenia. Są to: init -: Wywoływana przez skrypt w momencie utworzenia i inicjalizacji komponentu. Odpowiednik funkcji konstruującej (constructor function) we Flashu. +: Wywoływana, gdy komponent skryptu jest inicjalizowany. Odpowiada funkcji konstruktora we Flashu. final -: Wywoływana przez skrypt w momencie zniszczenia i usunięcia komponentu. +: Wywoływana, gdy komponent skryptu jest niszczony, na przykład gdy usunięto obiekt gry utworzony w czasie działania. update -: Wywoływana w każdej ramce (frame). Odpowiednik funckji `enterFrame` we Flashu. +: Wywoływana w każdej klatce. Odpowiednik `enterFrame` we Flashu. fixed_update -: Wywoływana co stałą wartość czasu (zależną od FPS). +: Wywoływana ze stałą częstotliwością, zależną od FPS. on_message -: Wywoływana w momencie otrzymania przez skrypt wiadomości. +: Wywoływana, gdy komponent skryptu otrzyma wiadomość. on_input -: Wywoływana w momencie wykonania przez użytkownika akcji wejścia (np. na myszce lub na klawiaturze) wysyłanej do obiektu z włączonym odbieraniem takich akcji ([input focus](/ref/go/#acquire_input_focus)), gdzie skryp może na daną akcję zareagować. +: Wywoływana, gdy dane wejściowe użytkownika, na przykład z myszy lub klawiatury, zostaną wysłane do obiektu gry z [input focus](/ref/go/#acquire_input_focus), co oznacza, że obiekt otrzymuje całe wejście i może na nie reagować. on_reload -: Wywoływana w momencie przeładowania skryptu (hot reload). +: Wywoływana, gdy komponent skryptu zostanie przeładowany. -Funckje callbacki powyżej są opcjonalne i mogą zostać usunięte ze skryptu, jeśli nie są wywoływane. Jeśli chodzi o ustawienie akcji wejść, proszę sprawdzić to w [instrukcji do obsługi wejść (input)](/manuals/input). Warto wiedzieć, że powszechna pułapka może pojawić się przy korzystaniu z pełnomocników kolekcji - sprawdź [tę sekcję](/manuals/input/#input-dispatch-and-on_input) instrukcji do obsługi wejść. +Wszystkie wymienione wyżej funkcje callback są opcjonalne i można je usunąć, jeśli nie są używane. Informacje o konfiguracji wejścia znajdziesz w [instrukcji o wejściu](/manuals/input). Częstą pułapką jest praca z collection proxy - więcej informacji znajdziesz w [tej sekcji](/manuals/input/#input-dispatch-and-on_input) instrukcji o wejściu. -Jak to omówiono przy kolizjach, są one obsługiwane przez wysłanie wiadomości do biorących udział w kolizji komponentów. Skrypty otrzymują te wiadomości i są one obsługwane w funkcji on_message. +Jak opisano w sekcji o wykrywaniu kolizji, zdarzenia kolizji są obsługiwane przez wysyłanie wiadomości do obiektów gry, których dotyczą. Ich odpowiednie komponenty skryptu otrzymują wiadomość w funkcji callback on_message. ## Flash — symbole przycisków -Flash wykorzystuje dedykowane symbole dla przycisków (button symbols). Przyciski używają specyficznych metod obsługi zdarzeń (np. `click` albo `buttonDown`) do wykonywania danych operacji w reakcji na akcję użytkownika. Graficzny kształt przycisku w sekcji "Hit" symbolu przycisku określa obszar wykrywania wciśnięcia przycisku. +Flash używa osobnego typu symboli dla przycisków. Przyciski korzystają ze specyficznych metod obsługi zdarzeń, na przykład `click` i `buttonDown`, aby wykonywać akcje po wykryciu interakcji użytkownika. Graficzny kształt przycisku w sekcji Hit symbolu przycisku określa obszar trafienia przycisku. ![button](images/flash/button.png) -## Defold — sceny i skryptu graficznego interfejsu (GUI) +## Defold — sceny GUI i skrypty -Defold nie posiada natywnego komponentu przycisku, ani kształt nie może być łatwo określony dla obiektów gry w sposób w jaki przyciski są obsługiwane we Flashu. Zamiast tego, Defold używa komponenty graficznych interfejsów użytkownika ([GUI](/manuals/gui)), gdzie przykładowo pozycja elementów komponentów GUI nie jest zmieniona w zależności od zmian widoku kamery (jeśli ten jest zmieniany). API dla GUI w Defoldzie posiada również możliwość detekcji akcji wejść użytkownika, takich jak kliknięcia na obszarze wykrywania akcji elementów GUI. +Defold nie ma natywnego komponentu przycisku, ani nie da się łatwo wykrywać kliknięć względem kształtu konkretnego obiektu gry tak, jak obsługiwane są przyciski we Flashu. Najczęstszym rozwiązaniem jest użycie komponentu [GUI](/manuals/gui), częściowo dlatego, że pozycje elementów GUI w Defoldzie nie są zależne od kamery w grze, jeśli jest używana. API GUI zawiera też funkcje do sprawdzania, czy dane wejściowe, takie jak kliknięcia i dotyk, mieszczą się w granicach elementu GUI. ## Debugowanie -We Flashu, funkcja `trace()` pomaga przy debugowaniu. Defold posiada odpowiadającą funkcję `print()` wykorzystywaną w ten sam sposób: +We Flashu podczas debugowania przydatna jest komenda `trace()`. Odpowiednikiem w Defoldzie jest `print()`, używana tak samo jak `trace()`: ```lua print("Hello world!"") ``` -Można wyświetlić więcej zmiennych używając jednego wywołania funckji `print()`: +Jednym wywołaniem `print()` można wypisać wiele zmiennych: ```lua print(score, health, ammo) ``` -Istnieje też funkcja `pprint()` (pretty print), która wyświetla również zawartość całych tabeli, również zagnieżdżonych, jak na przykład w poniższym skrypcie: +Istnieje też funkcja `pprint()` (pretty print), przydatna przy pracy z tabelami. Wypisuje ona zawartość tabel, również zagnieżdżonych. Rozważ poniższy skrypt: ```lua factions = {"red", "green", "blue"} @@ -307,13 +307,13 @@ world = {name = "Terra", teams = factions} pprint(world) ``` -Tabela (`factions`) jest zagnieżdżona w tabeli (`world`). Używając funkcji `print(world)` zobaczymy tylko unikalne id tabeli, a nie jej zawartość: +To zawiera tabelę (`factions`) zagnieżdżoną w tabeli (`world`). Zwykłe `print()` wypisałoby tylko unikalne id tabeli, a nie jej zawartość: ``` DEBUG:SCRIPT: table: 0x7ff95de63ce0 ``` -Używając funkcji `pprint()` jak powyżej, otrzymamy ciekawszy wynik: +`pprint()` daje bardziej czytelny wynik: ``` DEBUG:SCRIPT: @@ -327,32 +327,32 @@ DEBUG:SCRIPT: } ``` -Jeśli Twoja gra wykorzystuje detekcję kolizji, możesz również włączyć debugowanie fizyki poprzez wysłanie poniższej wiadomości do systemu: +Jeśli gra korzysta z wykrywania kolizji, debugowanie fizyki można włączyć, wysyłając poniższą wiadomość: ```lua msg.post("@system:", "toggle_physics_debug") ``` -Debugowanie fizyki może być również włączone/wyłączone w ustawieniach projektu w pliku *game.project*. Przed włączeniem debugowania fizyki: +Debugowanie fizyki można też włączyć w ustawieniach projektu. Przed przełączeniem debugowania fizyki projekt wyglądałby tak: ![no debug](images/flash/no_debug.png) -Włączenie debugowania fizyki wyświetla dodatkowo kształty obiektów kolizji dodanych do obiektów gry: +Po włączeniu debugowania fizyki widać obiekty kolizji dodane do obiektów gry: ![with debug](images/flash/with_debug.png) -A kiedy dojdzie do kolizji, dane obiekty są podświetlone i wyświetlony jest wektor kolizji: +Gdy dojdzie do kolizji, odpowiednie obiekty kolizji zostają podświetlone. Dodatkowo wyświetlany jest wektor kolizji: ![collision](images/flash/collision.png) -Dodatkowo, jest jeszcze zaawansowany profiler, a więcej informacji o nim znajdziesz w [dokumentacji profilera](/ref/profiler/), np. monitorowanie wykorzystania CPU czy pamięci. Więcej technik debugowania znajdziesz w sekcji [debugowanie](/manuals/debugging). +Na koniec zajrzyj do [dokumentacji profilera](/ref/profiler/), aby dowiedzieć się, jak monitorować użycie CPU i pamięci. Więcej informacji o zaawansowanych technikach debugowania znajdziesz w [sekcji debugowania](/manuals/debugging) w instrukcji Defold. -## Gdzie dalej? +## Co dalej - [Przykłady Defold](/examples) - [Tutoriale](/tutorials) - [Instrukcje](/manuals) -- [API](/ref/go) +- [Reference](/ref/go) - [FAQ](/faq/faq) -Jeśli masz pytania lub utknąłeś [forum Defold](//forum.defold.com) jest najlepszym miejscem do znalezienia pomocy. +Jeśli masz pytania albo utkniesz, [forum Defold](//forum.defold.com) to dobre miejsce, by poprosić o pomoc. diff --git a/docs/pl/manuals/flipbook-animation.md b/docs/pl/manuals/flipbook-animation.md index 08c4cae4..d6ee4ed1 100644 --- a/docs/pl/manuals/flipbook-animation.md +++ b/docs/pl/manuals/flipbook-animation.md @@ -1,46 +1,46 @@ --- -title: Animacja poklatkowa - Flip-book -brief: Ta instrukcja opisuje wsparcie dla animacji poklatkowych w silniku Defold. +title: Animacje flip-book w podręczniku Defold +brief: Ta instrukcja opisuje, jak używać animacji flip-book w Defold. --- -# Animacja poklatkowa - flip-book +# Animacja flip-book -Animacja poklatkowa (ang. flip-book animation) składa się z serii obrazów (klatek animacji), które są pokazywane jeden za drugim, więc patrząc na nie sprawiają wrażenie ruchu. Technika ta jest bardzo podobna do tradycyjnej animacji używanej w kinematografii [https://pl.wikipedia.org/wiki/Animacja](https://pl.wikipedia.org/wiki/Animacja) i oferuje nieograniczoną kontrolę, ponieważ każda klatka może być modyfikowana indywidualnie. Jednakże pamięć zajmowana przez wszystkie obrazy składające się na taką animację może być duża w zależności od ilości klatek i ich wielkości. Płynność animacji zależy od liczby klatek pokazywanych w każdej sekundzie (FPS z ang. frames per second), co wymaga oczywiście większej ilości pracy. Animacje typu flip-book w Defoldzie są przechowywane albo jako indywidualne obrazy umieszczone w galerii zwanej [Atlas](/manuals/atlas), albo jako obrazy umieszczone w bezpośrednim sąsiedztwie, w poziomej sekwencji jak kafelki w tzw. Źródle Kafelków - [Tile Source](/manuals/tilesource). +Animacja flip-book składa się z serii nieruchomych obrazów wyświetlanych jeden po drugim. Technika ta jest bardzo podobna do tradycyjnej animacji poklatkowej (zobacz http://en.wikipedia.org/wiki/Traditional_animation). Daje niemal nieograniczone możliwości, ponieważ każdą klatkę można modyfikować osobno. Z drugiej strony koszt pamięci może być wysoki, bo każda klatka jest przechowywana jako osobny obraz. Płynność animacji zależy również od liczby obrazów wyświetlanych w każdej sekundzie, a zwiększenie tej liczby zwykle oznacza też więcej pracy dla silnika. Animacje flip-book w Defold są przechowywane albo jako osobne obrazy dodane do [Atlas](/manuals/atlas), albo jako [Tile Source](/manuals/tilesource) z wszystkimi klatkami ułożonymi w poziomy ciąg. ![Animation sheet](images/animation/animsheet.png){.inline} ![Run loop](images/animation/runloop.gif){.inline} ## Odtwarzanie animacji flip-book -Sprite'y i węzły GUI mogą odtwarzać animacje poklatkowe i masz nad tym całkowitą kontrolę w trakcie działania programu. +Sprite'y i węzły GUI box mogą odtwarzać animacje flip-book, a w czasie działania programu masz nad nimi dużą kontrolę. Sprite'y -: Aby odtworzyć animację w trakcie działania programu używa się funkcji [`sprite.play_flipbook()`](/ref/sprite/?q=play_flipbook#sprite.play_flipbook:url-id-[complete_function]-[play_properties]). Poniżej przykład. +: Aby odtworzyć animację w czasie działania programu, użyj funkcji [`sprite.play_flipbook()`](/ref/sprite/?q=play_flipbook#sprite.play_flipbook:url-id-[complete_function]-[play_properties]). Zobacz przykład poniżej. -Węzły GUI -: Aby odtworzyć animację w trakcie działania programu używa się funkcji [`gui.play_flipbook()`](/ref/gui/?q=play_flipbook#gui.play_flipbook:node-animation-[complete_function]-[play_properties]). Poniżej przykład. +Węzły GUI box +: Aby odtworzyć animację w czasie działania programu, użyj funkcji [`gui.play_flipbook()`](/ref/gui/?q=play_flipbook#gui.play_flipbook:node-animation-[complete_function]-[play_properties]). Zobacz przykład poniżej. ::: sidenote -Tryb odtwarzania (playback mode) "once ping-pong" odtworzy animację klatka po klatce do samego końca, a następnie odtworzy ją jeszcze raz w odwrotnej kolejności, od tyłu, ale do **drugiej** klatki animacji, a nie do pierwszej. Jest to zabieg służący łatwemu wiązaniu animacji w serie. +Tryb odtwarzania once ping-pong odtwarza animację do ostatniej klatki, a następnie odtwarza ją w odwrotnej kolejności aż do **drugiej** klatki animacji, a nie z powrotem do pierwszej. Dzięki temu łatwiej łączyć animacje w łańcuch. ::: -### Przykład animacji ze spritem +### Przykład ze sprite'em -Załóżmy, że Twoja gra posiada możliwość "uniku", która pozwala graczom nacisnąć klawisz, aby wykonać unik. Masz przygotowane 4 animacje, żeby w pełni pokazać unik: +Załóżmy, że w grze istnieje funkcja "dodge", dzięki której gracz może nacisnąć określony przycisk, aby wykonać unik. Przygotowano cztery animacje wspierające tę funkcję i zapewniające informację zwrotną: "idle" -: Zapętlona animacja stojącej postaci będącej w bezczynności. +: Zapętlona animacja postaci pozostającej bez ruchu. "dodge_idle" -: Zapętlona animacja postaci pochylonej, będącej w trakcie trwania uniku. +: Zapętlona animacja postaci pozostającej w pozycji uniku. "start_dodge" -: Jednokrtotnie odtwarzana animacja postaci w momencie przejścia animacji z pozycji stojącej do pochylonej w celu wykonania uniku. +: Animacja odtwarzana raz, przechodząca postać z pozycji stojącej do pozycji uniku. "stop_dodge" -: Jednokrtotnie odtwarzana animacja postaci w momencie przejścia animacji z pozycji uniku z powrotem do pozycji stojącej. +: Animacja odtwarzana raz, przechodząca postać z pozycji uniku z powrotem do pozycji stojącej. -Skrypt poniżej przedstawia potrzebną logikę: +Poniższy skrypt zawiera logikę: ```lua @@ -53,7 +53,7 @@ local function play_idle_animation(self) end function on_input(self, action_id, action) - -- "dodge" to nasza akcja zbindowana z inputem + -- "dodge" to nasza akcja wejściowa if action_id == hash("dodge") then if action.pressed then sprite.play_flipbook("#sprite", hash("start_dodge"), play_idle_animation) @@ -61,29 +61,30 @@ function on_input(self, action_id, action) self.dodge = true elseif action.released then sprite.play_flipbook("#sprite", hash("stop_dodge"), play_idle_animation) - -- zapamiętaj, że skończyliśmy unik + -- nie wykonujemy już uniku self.dodge = false end end end ``` -### Przykład animacji z węzłem GUI +### Przykład z węzłem GUI box -Przy wyborze obrazu i animacji dla węzła graficznego interfejsu użytkownika (ang. GUI), np. "box" albo "pie" tak naprawdę właśnie przypisujesz źródło obrazów (atlas lub tile source) i domyślną animację, tak samo jak w przypadku sprite'ów. Takie źródło grafiki jest statycznie przypisane do węzła, ale animacja może być zmieniona w trakcie trwania programu. Nieruchome obrazki są traktowane jako jednoklatkowa animacja, więc zamiana obrazu jest jednoznaczna z odtworzeniem innej animacji poklatkowej na węźle: +Wybierając animację albo obraz dla węzła, w praktyce przypisujesz jednocześnie źródło obrazu (atlas albo Tile Source) oraz domyślną animację. Źródło obrazu jest ustawione statycznie w węźle, ale bieżącą animację można zmieniać w czasie działania programu. Nieruchome obrazy są traktowane jak animacje jednoklatkowe, więc zmiana obrazu w czasie działania programu jest równoważna odtworzeniu dla węzła innej animacji flip-book: ```lua function init(self) local character_node = gui.get_node("character") - -- To wymaga, żeby węzły miały domyślne animacje w tym samym atlasie lub źródłe kafelków - -- co nowa animacja, którą odtwarzamy + -- To wymaga, aby węzeł miał domyślną animację w tym samym atlasie lub Tile Source + -- co nowa animacja/obraz, który odtwarzamy. gui.play_flipbook(character_node, "jump_left") end ``` -## Funkcje po zakończeniu animacji -Funckje `sprite.play_flipbook()` i `gui.play_flipbook()` przyjmują jako ostatni argument opcjonalną funkcję, która jest wywoływana w momencie zakończenia animacji, tzw. callback. Będzie ona wywołana po skończeniu animacji, więc tylko dla takich, które nie są zapętlone, czyli w trybach odtwarzania: `PLAYBACK_ONCE_*` i nie będzie wywołana w przypadku ręcznego anulowania animacji za pomocą `go.cancel_animations()`. Można użyć takiej funkcjonalności w celu wywołania specjalnych wydarzeń po skończonej animacji (np. procesu zadania obrażeń po skończonej animacji ataku) lub do połączenia różnych animacji w serie, jedna za drugą. Przykłady: +## Callbacki po zakończeniu + +Funkcje `sprite.play_flipbook()` i `gui.play_flipbook()` obsługują opcjonalną funkcję callback jako ostatni argument Lua. Zostanie ona wywołana, gdy animacja dotrze do końca. Nie jest wywoływana dla animacji zapętlonych. Callback można wykorzystać do uruchamiania zdarzeń po zakończeniu animacji albo do łączenia wielu animacji w łańcuch. Przykłady: ```lua local function flipbook_done(self) @@ -104,15 +105,3 @@ function init(self) gui.play_flipbook(gui.get_node("character"), "jump_left", flipbook_done) end ``` - -## Tryby odtwarzania - -Animacje można odtwarzać raz lub w pętli. Sposób odtwarzania animacji jest określany przez tryb odtwarzania (ang. Playback mode): - -* go.PLAYBACK_NONE -* go.PLAYBACK_ONCE_FORWARD -* go.PLAYBACK_ONCE_BACKWARD -* go.PLAYBACK_ONCE_PINGPONG -* go.PLAYBACK_LOOP_FORWARD -* go.PLAYBACK_LOOP_BACKWARD -* go.PLAYBACK_LOOP_PINGPONG diff --git a/docs/pl/manuals/font.md b/docs/pl/manuals/font.md index 4aee5f96..358c7113 100644 --- a/docs/pl/manuals/font.md +++ b/docs/pl/manuals/font.md @@ -1,88 +1,111 @@ --- -title: Fonty w Defoldzie -brief: Ta instrukcja opisuje jak używać fontów w Twoich grach. +title: Fonty w silniku Defold +brief: Ta instrukcja opisuje, jak Defold obsługuje fonty i jak wyświetlać je na ekranie w grach. --- # Pliki fontów -Fonty (w odróżnieniu od czcionki będącej jedynie określeniem materiału zecerskiego) są używane do wyświetlania tekstu w kompoentach typu Label (etykieta) i węzłów tekstowych GUI. Defold wspiera poniższe formaty plików określających fonty: +Fonty służą do renderowania tekstu w komponentach Label oraz węzłach tekstowych GUI. Defold obsługuje kilka formatów plików fontów: - TrueType - OpenType - BMFont -Fonty dodane do projektu są automatycznie konwertowane na format tekstury, który może być renderowany przez Defolda. Dostępne są dwie techniki renderowania czcionek, z własnymi korzyściami i wadami: +Fonty dodane do projektu są automatycznie konwertowane do formatu tekstury, który Defold potrafi renderować. Dostępne są dwie techniki renderowania fontów, a każda ma własne zalety i wady: - Bitmap -- Distance field (Pole odległości) +- Distance field -## Tworzenie fontów +## Fonty offline i runtime fonts -Aby stworzyć czcionkę do użycia w Defold, utwórz nowy plik fontu, wybierając opcję File ▸ New... z menu, a następnie wybierz Font. Możesz również kliknąć prawy przycisk myszy w lokalizacji w panelu *Assets* i wybrać New... ▸ Font. +Domyślnie konwersja do zrasteryzowanych obrazów glifów odbywa się podczas budowania projektu, czyli offline. Ma to tę wadę, że każdy font musi wyrasteryzować wszystkie możliwe glify już na etapie budowania, co może prowadzić do bardzo dużych tekstur zajmujących pamięć i zwiększających rozmiar bundla. + +Przy użyciu runtime fonts pliki .ttf są dołączane do bundla bez zmian, a rasteryzacja odbywa się na żądanie w czasie działania programu. Dzięki temu zmniejsza się zarówno zużycie pamięci w runtime, jak i rozmiar bundla. + +## Obsługa układu tekstu, np. right-to-left + +Runtime fonts mają też tę zaletę, że obsługują pełny układ tekstu, np. right-to-left. +Obecnie używamy bibliotek [HarfBuzz](https://github.com/harfbuzz/harfbuzz), [SheenBidi](https://github.com/Tehreer/SheenBidi), [libunibreak](https://github.com/adah1972/libunibreak) oraz [SkriBidi](https://github.com/memononen/Skribidi). + +Zobacz [Włączanie runtime fonts](/manuals/font#enabling-runtime-fonts) + +## Kolekcja fontów + +Format pliku `.fontc` jest też znany jako font collection, czyli kolekcja fontów. W trybie offline jest z nim powiązany tylko jeden font. +W przypadku runtime fonts możesz powiązać z kolekcją fontów więcej niż jeden plik fontu .ttf. + +Dzięki temu można używać kolekcji fontów podczas renderowania wielu tekstów w różnych językach, a jednocześnie utrzymać niski ślad pamięciowy. +Na przykład można załadować kolekcję z japońskim fontem, skojarzyć ten font z bieżącym głównym fontem, a następnie zwolnić japońską kolekcję fontów. + +## Tworzenie fontu + +Aby utworzyć font do użycia w Defold, wybierz z menu File ▸ New..., a następnie Font. Możesz też right click w wybranym miejscu panelu *Assets* i wybrać New... ▸ Font. ![New font name](images/font/new_font_name.png) -Nadaj nowemu plikowi fontu nazwę i kliknij OK. Nowy plik fontu otworzy się teraz w edytorze. +Nadaj nowemu plikowi nazwę i kliknij Ok. Nowy plik otworzy się teraz w edytorze. ![New font](images/font/new_font.png) -Przeciągnij font, który chcesz użyć do panelu *Assets* i upuść ją we właściwym miejscu. +Przeciągnij font, którego chcesz użyć, do panelu *Assets* i upuść go w odpowiednim miejscu. -Ustaw właściwość *Font* na plik fontu i dostosuj właściwości czcionki, jak to konieczne. +Ustaw właściwość *Font* na plik fontu i skonfiguruj pozostałe właściwości według potrzeb. -## Właściwości (Properties) +## Właściwości *Font* -: Plik TTF, OTF lub *.fnt*, który ma zostać użyty do generowania danych czcionki. +: Plik TTF, OTF albo *`.fnt`* używany do wygenerowania danych fontu. *Material* -: Materiał, który ma zostać użyty podczas renderowania fontu. Upewnij się, że zmieniasz to dla czcionek Distance Field i BMFonts (patrz poniżej, aby uzyskać szczegóły). +: Materiał używany do renderowania tego fontu. Pamiętaj, aby zmienić go dla Distance field i BMFonts. Szczegóły znajdziesz poniżej. *Output Format* -: Rodzaj danych czcionki, który jest generowany. +: Typ generowanych danych fontu. - - `TYPE_BITMAP` konwertuje importowany plik OTF lub TTF na teksturę arkusza fontu, gdzie dane bitmapy są używane do renderowania tekstu. Kanały koloru służą do kodowania kształtu twarzy (face shape), obrysu (outline) i cienia (shadow). Dla plików *.fnt* używana jest oryginalna bitmapa źródłowa. - - `TYPE_DISTANCE_FIELD` importowany font jest konwertowana na teksturę arkusza fontu, gdzie dane pikseli reprezentują nie piksele ekranu, ale odległości do krawędzi czcionki. Patrz poniżej po szczegóły. + - `TYPE_BITMAP` konwertuje zaimportowany plik OTF albo TTF do tekstury arkusza fontu, w której dane bitmapowe służą do renderowania tekstu. Kanały kolorów służą do zakodowania kształtu znaku, obrysu i cienia. W przypadku plików *`.fnt`* źródłowa tekstura bitmapowa jest używana bez zmian. + - `TYPE_DISTANCE_FIELD` konwertuje zaimportowany font do tekstury arkusza fontu, w której dane pikseli nie reprezentują pikseli ekranu, lecz odległości do krawędzi fontu. Szczegóły znajdziesz poniżej. *Render Mode* -: Tryb renderowania dla glifów. +: Tryb renderowania używany do renderowania glifów. - - `MODE_SINGLE_LAYER` generuje pojedynczy kwadrat (quad) dla każdego znaku. - - `MODE_MULTI_LAYER` generuje osobne kwadraty (quady) dla kształtu glifu, obrysu i cieni, odpowiednio. Warstwy są renderowane od tyłu do przodu, co zapobiega zasłanianiu wcześniej renderowanych znaków, jeśli obrys jest szerszy niż odległość między glifami. Ten tryb renderowania umożliwia również prawidłowe przesunięcie cienia, zgodnie z właściwościami cienia X/Y w zasobie fontu. + - `MODE_SINGLE_LAYER` tworzy pojedynczy quad dla każdego znaku. + - `MODE_MULTI_LAYER` tworzy oddzielne quady odpowiednio dla kształtu glifu, obrysu i cieni. Warstwy są renderowane od tyłu do przodu, co zapobiega zasłanianiu wcześniej wyrenderowanych znaków, jeśli obrys jest szerszy niż odstęp między glifami. Ten tryb renderowania umożliwia też poprawne przesuwanie cienia, zgodnie z właściwościami Shadow X/Y w zasobie fontu. *Size* : Docelowy rozmiar glifów w pikselach. *Antialias* -: Określa, czy czcionka ma być wygładzana (antyaliasing), gdy jest wypalana na docelowej bitmapie. Ustaw na 0, jeśli chcesz uzyskać dokładne renderowanie czcionki piksel po pikselu. +: Określa, czy font ma być wygładzany podczas wypalania do docelowej bitmapy. Ustaw 0, jeśli chcesz uzyskać pikselowo idealne renderowanie fontu. *Alpha* -: Przezroczystość glifu. Od 0,0 do 1,0, gdzie 0,0 oznacza przezroczystość, a 1,0 nieprzezroczystość. +: Przezroczystość glifu. Zakres 0.0-1.0, gdzie 0.0 oznacza pełną przezroczystość, a 1.0 pełną nieprzezroczystość. *Outline Alpha* -: Przezroczystość generowanego obrysu. Od 0,0 do 1,0. +: Przezroczystość wygenerowanego obrysu. Zakres 0.0-1.0. *Outline Width* -: Szerokość generowanego obrysu w pikselach. Ustaw na 0, jeśli nie chcesz obrysu. +: Szerokość wygenerowanego obrysu w pikselach. Ustaw 0, jeśli obrys nie jest potrzebny. *Shadow Alpha* -: Przezroczystość generowanego cienia. Od 0,0 do 1,0. +: Przezroczystość wygenerowanego cienia. Zakres 0.0-1.0. ::: sidenote -Wsparcie dla cieni jest aktywowane przez wbudowane shadery materiałów czcionek i obsługuje zarówno tryb renderowania warstwowego, jak i jednowarstwowego. Jeśli nie potrzebujesz warstwowego renderowania czcionek ani obsługi cieni, lepiej jest użyć prostszego shadera, takiego jak wbudowany shader `builtins/font-singlelayer.fp`. +Obsługę cienia zapewniają wbudowane shadery materiałów fontów i działa ona zarówno w trybie renderowania jedno-, jak i wielowarstwowego. Jeśli nie potrzebujesz warstwowego renderowania fontów ani obsługi cienia, najlepiej użyć prostszego shadera, takiego jak *`builtins/font-singlelayer.fp`*. ::: *Shadow Blur* -: Dla czcionek bitmapowych to ustawienie określa liczbę razy, jaka ma być zastosowane małe jądro rozmazywania do każdego glifu czcionki. Dla czcionek pola odległości (distance field) to ustawienie odpowiada rzeczywistej szerokości w pikselach rozmycia. +: W przypadku fontów bitmapowych to ustawienie określa, ile razy ma zostać zastosowane małe jądro rozmycia do każdego glifu fontu. W przypadku fontów typu distance field odpowiada ono rzeczywistej szerokości rozmycia w pikselach. *Shadow X/Y* -: Poziome i pionowe przesunięcie w pikselach generowanego cienia. To ustawienie wpłynie tylko na cień glifu, gdy tryb renderowania jest ustawiony na `MODE_MULTI_LAYER`. +: Poziome i pionowe przesunięcie wygenerowanego cienia w pikselach. To ustawienie wpływa na cień glifu tylko wtedy, gdy Render Mode ma wartość `MODE_MULTI_LAYER`. -*Extra Characters* -: Domyślnie font będzie zawierać drukowalne znaki ASCII (kody znaków 32-126). Aby ręcznie dodać dodatkowe znaki, wymień je w polu właściwości. +*Characters* +: Określa, które znaki mają zostać uwzględnione w foncie. Domyślnie pole to zawiera drukowalne znaki ASCII o kodach 32-126. Możesz dodawać lub usuwać znaki, aby uwzględnić ich więcej albo mniej. + + W przypadku runtime fonts ten tekst działa też jako wstępne podgrzewanie cache odpowiednimi glifami. Dzieje się to podczas ładowania. Zobacz `font.prewarm_text()`. ::: sidenote -Znaki ASCII do druku: +Drukowalne znaki ASCII to: space ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ \` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ ::: @@ -90,75 +113,157 @@ space ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E : Jeśli zaznaczysz tę właściwość, wszystkie glify dostępne w pliku źródłowym zostaną uwzględnione w wyniku. *Cache Width/Height* -: Ogranicza rozmiar mapy bitowej pamięci podręcznej glifów. Kiedy silnik renderuje tekst, przeszukuje mapę bitową, aby znaleźć glif z pamięci podręcznej. Jeśli glifu tam nie ma, zostanie on dodany do pamięci podręcznej przed renderowaniem. Jeśli mapa bitowa pamięci podręcznej jest zbyt mała, aby pomieścić wszystkie glify, które silnik ma zrenderować, zostanie wygenerowany błąd (`ERROR:RENDER: Out of available cache cells! Consider increasing cache_width or cache_height for the font.`), czyli "Brak dostępnych komórek w pamięci podręcznej! Rozważ zwiększenie `cache_width` lub `cache_height` dla fontu". +: Ogranicza rozmiar bitmapy cache glifów. Gdy silnik renderuje tekst, wyszukuje glif w bitmapie cache. Jeśli go tam nie ma, zostanie on dodany do cache przed renderowaniem. Jeśli bitmapa cache jest zbyt mała, aby pomieścić wszystkie glify, które silnik ma wyrenderować, zostanie zgłoszony błąd (`ERROR:RENDER: Out of available cache cells! Consider increasing cache_width or cache_height for the font.`). - Jeśli ustawisz to na 0, rozmiar pamięci podręcznej będzie ustawiany automatycznie. + Jeśli ustawisz tę właściwość na 0, rozmiar cache zostanie dobrany automatycznie i może wzrosnąć maksymalnie do 2048x4096. -## Fonty pola odległości (Distance field) +## Fonty typu Distance field -Fonty pola odległości przechowują odległość od krawędzi glifu w teksturze zamiast danych w postaci mapy bitowej. Gdy silnik renderuje font, wymagany jest specjalny shader do interpretowania danych odległości i ich wykorzystania do rysowania glifu. Fonty pola odległości są bardziej wymagające pod względem zasobów niż fonty bitmapowe, ale pozwalają na większą elastyczność skalowania. +Fonty typu Distance field przechowują w teksturze odległość do krawędzi glifu zamiast danych bitmapowych. Gdy silnik renderuje taki font, potrzebny jest specjalny shader interpretujący dane odległości i używający ich do rysowania glifu. Fonty typu Distance field są bardziej zasobożerne niż fonty bitmapowe, ale zapewniają większą elastyczność skalowania. ![Distance field font](images/font/df_font.png) -Upewnij się, że zmieniasz właściwość *Material* czcionki na *builtins/fonts/font-df.material* (lub inny materiał, który może obsługiwać dane pola odległości) podczas tworzenia fontu, w przeciwnym razie czcionka nie będzie używać odpowiedniego shadera podczas renderowania na ekranie. +Pamiętaj, aby podczas tworzenia fontu zmienić właściwość *Material* na *`builtins/fonts/font-df.material`* albo inny materiał obsługujący dane distance field, bo w przeciwnym razie font nie będzie używał właściwego shadera podczas renderowania na ekranie. -## Fonty bitmapowe BMFonts +## Bitmap BMFonts -Oprócz generowanych map bitowych, Defold obsługuje fonty w formacie bitmapowym "BMFont". Te fonty składają się z arkusza fontu PNG z glifami. Ponadto plik *.fnt* zawiera informacje o tym, gdzie na arkuszu znajduje się każdy glif, a także informacje o rozmiarze i kerningu. (Należy pamiętać, że Defold nie obsługuje wersji XML pliku *.fnt*, która jest używana przez Phaser i niektóre inne narzędzia). +Oprócz generowanych bitmap Defold obsługuje także wstępnie przygotowane fonty bitmapowe w formacie BMFont. Taki font składa się z arkusza fontu PNG zawierającego wszystkie glify. Dodatkowo plik *`.fnt`* zawiera informacje o położeniu każdego glifu na arkuszu, a także o jego rozmiarze i kerningu. Pamiętaj, że Defold nie obsługuje wersji XML formatu *`.fnt`*, używanej przez Phaser i niektóre inne narzędzia. -Te rodzaje fontów nie przynoszą żadnej poprawy wydajności w porównaniu do fontów bitmapowych generowanych z plików czcionek TrueType lub OpenType, ale pozwalają na dowolne grafiki, kolorowanie i cienie bezpośrednio w obrazie. +Tego typu fonty nie dają poprawy wydajności względem fontów bitmapowych generowanych z plików TrueType albo OpenType, ale mogą zawierać dowolną grafikę, kolorowanie i cienie bezpośrednio w obrazie. -Dodaj wygenerowane pliki *.fnt* i *.png* do swojego projektu Defold. Te pliki powinny znajdować się w tym samym folderze. Utwórz nowy plik fontu i ustaw właściwość *font* na plik *.fnt*. Upewnij się, że *output_format* jest ustawiony na `TYPE_BITMAP`. Defold nie wygeneruje mapy bitowej, ale użyje tej dostarczonej w formacie PNG. +Dodaj wygenerowane pliki *`.fnt`* i *`.png`* do projektu Defold. Pliki te powinny znajdować się w tym samym folderze. Utwórz nowy plik fontu i ustaw właściwość *Font* na plik *`.fnt`*. Upewnij się, że *Output Format* ma wartość `TYPE_BITMAP`. Defold nie wygeneruje wtedy bitmapy, tylko użyje tej dostarczonej w pliku PNG. ::: sidenote -Aby stworzyć font BMFont, musisz użyć narzędzia, które może generować odpowiednie pliki. Istnieje kilka opcji: +Aby utworzyć BMFont, potrzebujesz narzędzia, które potrafi wygenerować odpowiednie pliki. Dostępnych jest kilka opcji: -* [Bitmap Font Generator](http://www.angelcode.com/products/bmfont/), narzędzie dostępne tylko na platformę Windows, dostarczone przez AngelCode. -* [Shoebox](http://renderhjs.net/shoebox/), darmowa aplikacja oparta na Adobe Air dla platformy Windows i macOS. -* [Hiero](https://github.com/libgdx/libgdx/wiki/Hiero), narzędzie typu open source oparte na Java. -* [Glyph Designer](https://71squared.com/glyphdesigner), komercyjne narzędzie dla platformy macOS od 71 Squared. -* [bmGlyph](https://www.bmglyph.com), komercyjne narzędzie dla platformy macOS od Sovapps. +* [Bitmap Font Generator](http://www.angelcode.com/products/bmfont/), narzędzie tylko dla Windows od AngelCode. +* [Shoebox](http://renderhjs.net/shoebox/), darmowa aplikacja oparta na Adobe Air dla Windows i macOS. +* [Hiero](https://libgdx.com/wiki/tools/hiero), narzędzie open source oparte na Javie. +* [Glyph Designer](https://71squared.com/glyphdesigner), komercyjne narzędzie dla macOS od 71 Squared. +* [bmGlyph](https://www.bmglyph.com), komercyjne narzędzie dla macOS od Sovapps. ::: ![BMfont](images/font/bm_font.png) -Aby font renderował się poprawnie, nie zapomnij ustawić właściwości materiału na *builtins/fonts/font-fnt.material* podczas tworzenia czcionki. +Aby font renderował się poprawnie, nie zapomnij ustawić właściwości materiału na *`builtins/fonts/font-fnt.material`* podczas tworzenia fontu. -## Artefakty i najlepsze praktyki +## Artefakty i dobre praktyki -Ogólnie rzecz biorąc, fonty bitmapowe są najlepsze, gdy font jest renderowany bez skalowania. Są szybsze do renderowania na ekranie niż fonty pola odległości (Distance Field). +Zasadniczo fonty bitmapowe sprawdzają się najlepiej wtedy, gdy font nie jest skalowany. Są też szybsze w renderowaniu na ekranie niż fonty typu distance field. -Fonty pola odległości bardzo dobrze reagują na skalowanie w górę. Z kolei fonty bitmapowe, będąc jedynie pikselowymi obrazami, zwiększają swoją wielkość wraz ze skalowaniem czcionki, co prowadzi do efektów blokowych artefaktów. Oto przykład fontu o rozmiarze 48 pikseli, powiększonej 4-krotnie. +Fonty typu Distance field bardzo dobrze znoszą powiększanie. Fonty bitmapowe natomiast są po prostu obrazami pikselowymi, więc przy skalowaniu ich piksele rosną razem z fontem, co powoduje blokowe artefakty. Poniżej znajduje się przykład fontu o rozmiarze 48 pikseli, powiększonego 4 razy. ![Fonts scaled up](images/font/scale_up.png) -Podczas zmniejszania rozmiaru, tekstury fontów bitmapowych mogą być ładnie i efektywnie zmniejszone i wygładzone przez GPU. Font bitmapowy lepiej utrzymuje swoją kolorystykę niż font pola odległości. Oto przybliżenie tej samej próbki fontu o rozmiarze 48 pikseli, zmniejszonego do 1/5 rozmiaru: +Podczas zmniejszania tekstury bitmapowe można ładnie i wydajnie skalować w dół oraz wygładzać przez GPU. Font bitmapowy lepiej zachowuje też kolor niż font typu distance field. Oto zbliżenie tego samego przykładowego fontu o rozmiarze 48 pikseli, zmniejszonego do 1/5 oryginalnego rozmiaru: ![Fonts scaled down](images/font/scale_down.png) -Fonty pola odległości muszą być renderowane w celu uzyskania docelowego rozmiaru, który jest wystarczająco duży, aby pomieścić informacje o odległości, które mogą wyrazić krzywizny glifów fontu. To ta sama czcionka, co powyżej, ale o rozmiarze 18 pikseli i powiększona 10-krotnie. Wyraźnie widać, że jest to zbyt małe, aby zakodować kształty tego fontu: +Fonty typu Distance field muszą być renderowane do docelowego rozmiaru wystarczająco dużego, aby pomieścić informacje o odległości opisujące krzywizny glifów. Poniżej pokazano ten sam font co wyżej, ale w rozmiarze 18 pikseli i powiększony 10 razy. Widać wyraźnie, że to za mały rozmiar, aby poprawnie zakodować kształty tego kroju pisma: ![Distance field artifacts](images/font/df_artifacts.png) -Jeśli nie potrzebujesz obsługi cieni lub konturów, ustaw ich odpowiednie wartości alfa na zero. W przeciwnym razie dane cienia i konturu nadal zostaną generowane, zajmując zbędną pamięć. +Jeśli nie chcesz obsługi cienia ani obrysu, ustaw ich odpowiednie wartości alfa na zero. W przeciwnym razie dane cienia i obrysu nadal będą generowane i zajmą niepotrzebnie pamięć. ## Pamięć podręczna fontu -Zasób fontu w Defoldzie składa się z dwóch elementów w czasie rzeczywistym: tekstury i danych fontu. -* Dane fontu składają się z listy wpisów glifów, z których każdy zawiera podstawowe informacje o kerningu oraz dane mapy bitowej glifu. -* Tekstura jest wewnętrznie nazywana "teksturą pamięci podręcznej glifów" i jest używana podczas renderowania tekstu dla konkretnego fontu. +Zasób fontu w Defold daje w runtime dwie rzeczy: teksturę i dane fontu. + +* Dane fontu składają się z listy wpisów glifów, z których każdy zawiera podstawowe informacje o kerningu oraz dane bitmapowe tego glifu. +* Tekstura jest wewnętrznie nazywana "glyph cache texture" i jest używana podczas renderowania tekstu dla konkretnego fontu. -Podczas renderowania tekstu w czasie rzeczywistym, silnik najpierw przeszukuje glify do renderowania, aby sprawdzić, które glify są dostępne w pamięci podręcznej (cache) tekstury. Każdy glif, którego brakuje w pamięci podręcznej tekstury glifów, spowoduje przekazanie tekstury z bitmapowymi danymi zapisanymi w danych fontu. +Podczas renderowania tekstu w runtime silnik najpierw przechodzi po glifach, które mają zostać wyrenderowane, i sprawdza, które z nich są dostępne w pamięci podręcznej tekstury. Każdy brakujący glif powoduje przesłanie do tekstury danych bitmapowych przechowywanych w danych fontu. -Każdy glif jest umieszczany wewnętrznie w pamięci podręcznej zgodnie z bazą fontu, co pozwala na obliczanie lokalnych współrzędnych tekstury glifu w odpowiedniej komórce pamięci podręcznej w shaderze. Oznacza to, że można osiągnąć pewne efekty tekstowe, takie jak gradienty lub nakładki tekstury dynamicznie. Silnik udostępnia metryki dotyczące pamięci podręcznej tekstury dla shadera za pośrednictwem specjalnej stałej shadera o nazwie `texture_size_recip`, która zawiera następujące informacje w komponentach wektora: +Każdy glif jest wewnętrznie umieszczany w cache zgodnie z linią bazową fontu, co umożliwia obliczanie lokalnych współrzędnych tekstury glifu wewnątrz odpowiadającej mu komórki cache bezpośrednio w shaderze. Dzięki temu można dynamicznie uzyskiwać pewne efekty tekstowe, takie jak gradienty albo nakładki tekstur. Silnik udostępnia metryki cache shaderowi przez specjalną stałą shadera `texture_size_recip`, która zawiera następujące informacje w komponentach wektora: -* `texture_size_recip.x` to odwrotność szerokości pamięci podręcznej -* `texture_size_recip.y` to odwrotność wysokości pamięci podręcznej -* `texture_size_recip.z` to stosunek szerokości komórki pamięci podręcznej do szerokości pamięci podręcznej -* `texture_size_recip.w` to stosunek wysokości komórki pamięci podręcznej do wysokości pamięci podręcznej +* `texture_size_recip.x` to odwrotność szerokości cache +* `texture_size_recip.y` to odwrotność wysokości cache +* `texture_size_recip.z` to stosunek szerokości komórki cache do szerokości całego cache +* `texture_size_recip.w` to stosunek wysokości komórki cache do wysokości całego cache -Na przykład, aby wygenerować gradient w fragmencie shadera, wystarczy napisać: +Na przykład, aby wygenerować gradient w shaderze fragmentu, wystarczy napisać: `float horizontal_gradient = fract(var_texcoord0.y / texture_size_recip.w);` -Aby uzyskać więcej informacji na temat jednolitych shaderów, zobacz [instrukcje do shaderów](/manuals/shader). +Więcej informacji o uniformach shaderów znajdziesz w [Shader manual](/manuals/shader). + +## Włączanie runtime fonts + +Można używać generowania w czasie działania dla fontów typu SDF, gdy korzystasz z fontów TrueType (.ttf). +Takie podejście może znacznie zmniejszyć rozmiar pobieranych danych i zużycie pamięci w runtime gry Defold. +Niewielką wadą jest asynchroniczny charakter generowania każdego glifu. + +* Włącz tę funkcję, ustawiając `font.runtime_generation` w `game.project`. + +* Dodaj [App Manifest](/manuals/app-manifest) i włącz opcję `Use full text layout system`. + Spowoduje to zbudowanie niestandardowego silnika z włączoną obsługą tej funkcji. + +::: sidenote +Ta funkcja jest obecnie eksperymentalna, ale docelowo ma stać się domyślnym sposobem pracy. +::: + +::: important +Ustawienie `font.runtime_generation` wpływa na wszystkie fonty .ttf w projekcie. +::: + + +### Skryptowanie fontów + +#### Wstępne podgrzewanie cache glifów + +Aby ułatwić korzystanie z runtime fonts, obsługują one wstępne podgrzewanie cache glifów. +Oznacza to, że font wygeneruje glify wypisane w polu *Characters*. + +::: sidenote +Jeśli zaznaczono `All Chars`, wstępne podgrzewanie nie zostanie wykonane, ponieważ przeczyłoby to idei niewymuszania generowania wszystkich glifów naraz. +::: + +Jeśli pole `Characters` w pliku `.fontc` jest ustawione, jest ono używane jako tekst do ustalenia, które glify trzeba zaktualizować w cache glifów. + +Można też ręcznie zaktualizować cache glifów, wywołując `font.prewarm_text(font_collection, text, callback)`. Funkcja przyjmuje callback, który informuje, kiedy wszystkie brakujące glify zostały dodane do cache i można bezpiecznie wyświetlić tekst na ekranie. + +### Dodawanie i usuwanie fontów z kolekcji fontów + +W przypadku runtime fonts można dodawać lub usuwać fonty (.ttf) z font collection. +Jest to przydatne, gdy duży font został podzielony na kilka plików dla różnych zestawów znaków, np. CJK. + +::: important +Dodanie fontu do font collection nie powoduje automatycznego załadowania ani wyrenderowania wszystkich glifów. +::: + +```lua +-- pobierz główny font +local font_collection = go.get("#label", "font") +font.add_font(font_collection, self.language_ttf_hash) + +-- pobierz font wybranego języka +local font_collection_language = go.get("localization_japanese#label", "font") +local font_info = font.get_info(font_collection_language) +self.language_ttf_hash = font_info.fonts[1].path_hash -- pobierz pierwszy font (ten wskazany w edytorze) +font.add_font(self.font_collection, self.language_ttf_hash) -- zwiększa licznik referencji do fontu +``` + +```lua +-- usuń referencję do fontu +font.add_font(self.font_collection, self.language_ttf_hash) +``` + +### Wstępne podgrzewanie glifów + +Aby poprawnie wyświetlić tekst przy użyciu runtime font, glify muszą zostać rozwiązane. `font.prewarm_text()` robi to za ciebie. +Jest to operacja asynchroniczna. Gdy się zakończy i otrzymasz callback, możesz bezpiecznie przejść do wyświetlenia dowolnej wiadomości zawierającej te glify. + +::: important +Jeśli cache glifów się zapełni, najstarszy glif zostanie z niego usunięty. +::: + +```lua +font.prewarm_text(self.font_collection, info.text, function (self, request_id, result, err) + if result then + print("PREWARMING OK!") + label.set_text(self.label, info.text) + else + print("Error prewarming text:", err) + end + end) +``` diff --git a/docs/pl/manuals/getting-help.md b/docs/pl/manuals/getting-help.md index 7279e77a..7d964c77 100644 --- a/docs/pl/manuals/getting-help.md +++ b/docs/pl/manuals/getting-help.md @@ -1,66 +1,68 @@ --- title: Jak uzyskać pomoc -brief: Ta instrukcja opisuje, jak uzyskać pomoc, gdy napotkasz problem podczas korzystania z silnika Defold. +brief: Ta instrukcja opisuje, jak uzyskać pomoc, jeśli napotkasz problem podczas korzystania z Defold. --- # Jak uzyskać pomoc -Jeśli napotkasz problem podczas korzystania z silnika Defold, chcemy o tym wiedzieć, żeby móc go naprawić lub pomóc Ci znaleźć obejście. Istnieje kilka sposobów, aby omówić lub zgłosić problem. Wybierz ten, który najbardziej Ci odpowiada: +Jeśli napotkasz problem podczas korzystania z Defold, chcemy o tym wiedzieć, żeby móc naprawić błąd lub pomóc Ci obejść problem. Istnieje kilka sposobów, by omówić problem i zgłosić go dalej. Wybierz opcję, która najlepiej Ci odpowiada: ## Zgłoś problem na forum -Dobrym sposobem na omówienie problemu i uzyskanie pomocy jest zadanie pytania na naszym [forum](https://forum.defold.com). Zamieść post w [Questions](https://forum.defold.com/c/questions) albo w [Bugs](https://forum.defold.com/c/bugs), w zależności od rodzaju problemu. Pamiętaj, żeby [wyszukać](https://forum.defold.com/search) swoje pytanie/zgłoszenie zanim zapytasz – być może ktoś już znalazł rozwiązanie. +Dobrym sposobem na omówienie problemu i uzyskanie pomocy jest zadanie pytania na naszym [forum](https://forum.defold.com). Opublikuj wpis w kategorii [Questions](https://forum.defold.com/c/questions) albo [Bugs](https://forum.defold.com/c/bugs), zależnie od rodzaju problemu. Pamiętaj, aby [wyszukać](https://forum.defold.com/search) swoje pytanie lub zgłoszenie, zanim je opublikujesz, bo możliwe, że rozwiązanie już istnieje. -Jeśli masz kilka pytań, utwórz oddzielne posty. Nie zadawaj niezwiązanych pytań w tym samym wątku. +Jeśli masz kilka pytań, utwórz osobne wpisy. Nie zadawaj niezwiązanych pytań w jednym wpisie. ### Wymagane informacje -Nie będziemy mogli udzielić pomocy, jeśli nie przekażesz potrzebnych informacji: +Nie będziemy w stanie udzielić pomocy, jeśli nie podasz potrzebnych informacji: **Tytuł** -Użyj krótkiego i konkretnie opisującego problem tytułu. Dobry tytuł to np. „How do I move a game object in the direction it is rotated?” albo „How do I fade out a sprite?”. Zły tytuł to „I need some help using Defold!” albo „My game is not working!”. +Użyj krótkiego i jasno opisującego problem tytułu. Dobry tytuł to na przykład „How do I move a game object in the direction it is rotated?” albo „How do I fade out a sprite?”. Zły tytuł to „I need some help using Defold!” albo „My game is not working!”. **Opisz błąd (WYMAGANE)** -Jasny i zwięzły opis tego, co jest nie tak. +Jasny i zwięzły opis tego, na czym polega błąd. **Odtworzenie problemu (WYMAGANE)** -Kroki prowadzące do odtworzenia zachowania (raportuj najlepiej w języku angielskim): +Kroki prowadzące do odtworzenia zachowania: 1. Go to '...' -2. Click '....' +2. Click on '....' 3. Scroll down to '....' 4. See error **Oczekiwane zachowanie (WYMAGANE)** -Jasny opis tego, co powinno się wydarzyć. +Jasny i zwięzły opis tego, czego się spodziewałeś. **Wersja Defold (WYMAGANE):** - Version [e.g. 1.2.155] -**Sprzęt i system operacyjny (WYMAGANE):** +**Platformy (WYMAGANE):** - Platforms: [e.g. iOS, Android, Windows, macOS, Linux, HTML5] - OS: [e.g. iOS8.1, Windows 10, High Sierra] - Device: [e.g. iPhone6] **Minimal reproduction case project (OPCJONALNIE):** -Dołącz minimalny projekt, który odtwarza błąd. Ułatwia to diagnozę i naprawę. +Dołącz minimalny projekt, w którym da się odtworzyć błąd. Bardzo to pomaga osobie, która będzie badać i naprawiać problem. **Logi (OPCJONALNIE):** -Dodaj istotne logi z silnika, edytora lub serwera budowania. Dowiedz się, gdzie się znajdują, [tutaj](#log-files). +Dodaj odpowiednie logi z silnika, edytora lub serwera budowania. Informacje o tym, gdzie są przechowywane, znajdziesz [tutaj](#log-files). **Workaround (OPCJONALNIE):** -Jeśli znasz tymczasowe obejście, opisz je w poście. +Jeśli istnieje obejście problemu, opisz je tutaj. **Screenshots (OPCJONALNIE):** -Jeśli obrazy pomagają wyjaśnić problem, dołącz je. +Jeśli to pomoże wyjaśnić problem, dołącz zrzuty ekranu. **Additional context (OPCJONALNIE):** -Dodaj dowolny inny kontekst dotyczący problemu. +Dodaj tutaj każdy dodatkowy kontekst związany z problemem. ### Udostępnianie kodu -Kiedy dzielisz się kodem, lepiej zamieścić go jako tekst zamiast zrzutu ekranu. Dzięki temu można go przeszukać, łatwiej wskazać błędy i zaproponować poprawki. Umieść kod wewnątrz potrójnych backticków (```) albo wcięciu o 4 spacje. +Kiedy udostępniasz kod, zalecamy umieszczenie go jako tekstu, a nie jako zrzutu ekranu. Dzięki temu łatwiej go wyszukać, wskazać błędy i zaproponować poprawki. Wstaw kod między trzy backticki (\`\`\`) albo wcięty o 4 spacje. Przykład: +\`\`\` print("Hello code!") +\`\`\` Efekt: @@ -68,27 +70,27 @@ Efekt: print("Hello code!") ``` -## Zgłoś problem z poziomu Edytora +## Zgłoś problem z poziomu edytora -Edytor umożliwia wygodne zgłoszenie problemu. Wybierz Help->Report Issue z poziomu edytora, aby zgłosić błąd. +Edytor udostępnia wygodny sposób zgłaszania problemów. Wybierz z poziomu edytora Help->Report Issue, aby zgłosić błąd. ![](images/getting_help/report_issue.png) -Wybranie tej opcji przeniesie Cię do strony zgłoszeń na GitHubie. Dołącz [pliki z logami](#log-files), informacje o systemie operacyjnym, kroki odtwarzające problem, możliwe obejście itd. +Wybranie tej opcji przeniesie Cię do systemu zgłoszeń na GitHubie. Dołącz [pliki z logami](#log-files), informacje o systemie operacyjnym, kroki odtworzenia problemu, możliwe obejścia i tym podobne szczegóły. ::: sidenote -Musisz mieć konto na GitHubie, żeby zgłosić problem w ten sposób. +Do przesłania zgłoszenia w ten sposób potrzebujesz konta GitHub. ::: ## Przedyskutuj problem na Discord -Jeśli napotkasz problem podczas korzystania z silnika Defold, możesz spróbować zadać pytanie na [Discord](https://www.defold.com/discord/). Zalecamy jednak, żeby złożone pytania i głębsze dyskusje prowadzić na forum. Nie przyjmujemy zgłoszeń błędów przesyłanych przez Discord. +Jeśli napotkasz problem podczas korzystania z Defold, możesz spróbować zadać pytanie na [Discord](https://www.defold.com/discord/). Zalecamy jednak, aby złożone pytania i bardziej szczegółowe dyskusje prowadzić na forum. Nie przyjmujemy zgłoszeń błędów przesyłanych przez Discord. -# Log files +# Pliki z logami -Silnik, edytor i serwer budowania generują logi, które bardzo pomagają przy zgłaszaniu i rozwiązywaniu problemów. Zawsze dołącz pliki z logami, gdy zgłaszasz problem: +Silnik, edytor i serwer budowania generują informacje do logów, które mogą być bardzo pomocne podczas proszenia o pomoc i diagnozowania problemu. Zawsze dołączaj pliki z logami, gdy zgłaszasz problem: * [Engine logs](/manuals/debugging-game-and-system-logs) * [Editor logs](/manuals/editor#editor-logs) diff --git a/docs/pl/manuals/glossary.md b/docs/pl/manuals/glossary.md index b6f3da56..254d20a4 100644 --- a/docs/pl/manuals/glossary.md +++ b/docs/pl/manuals/glossary.md @@ -1,172 +1,172 @@ --- title: Słowniczek Defold -brief: Ten słowniczek zawiera terminy Defold z krótkimi objaśnieniami. +brief: Ten słowniczek zawiera krótkie opisy wszystkiego, co możesz napotkać podczas pracy w Defold. --- # Słowniczek Defold -Ten słowniczek udziela krótkich wyjaśnień dla terminów, które napotkasz podczas pracy z silnikiem Defold. W większości przypadków zamieszczamy też odnośniki do obszerniejszych opisów. +Ten słowniczek daje krótkie opisy wszystkich rzeczy, z którymi możesz się spotkać podczas pracy w Defold. W większości przypadków znajdziesz też odnośnik do bardziej szczegółowej dokumentacji. -## Animation set (Zestaw do animowania) +## Animation set (Zestaw animacji) -![Animation set](images/icons/animationset.png){.left} Zestaw do animowania zawiera listę plików `.dae` lub innych plików `.animationset`, z których odczytywane są animacje. Dodawanie jednego pliku `.animationset` do drugiego jest przydatne, gdy chcesz udostępnić fragmenty animacji kilku modelom. Szczegóły znajdziesz w [instrukcji do animacji modeli 3D](/manuals/model-animation/). +![Animation set](images/icons/animationset.png){.left} Zasób Animation set zawiera listę plików .dae lub innych plików .animationset, z których odczytywane są animacje. Dodawanie jednego pliku .animationset do drugiego jest wygodne, jeśli chcesz współdzielić częściowe zestawy animacji między kilkoma modelami. Szczegóły znajdziesz w [instrukcji animacji modeli](/manuals/model-animation/). -## Atlas (Galeria obrazów) +## Atlas (Atlas) -![Atlas](images/icons/atlas.png){.left} Atlas to zbiór osobnych obrazów skompilowanych w większy arkusz, co poprawia wydajność i oszczędza pamięć. Atlasy mogą zawierać statyczne grafiki lub zestawy klatek animacji poklatkowej. Różne komponenty korzystają z atlasów, aby współdzielić zasoby graficzne. Więcej w [dokumentacji do Atlasów](/manuals/atlas). +![Atlas](images/icons/atlas.png){.left} Atlas to zbiór osobnych obrazów skompilowanych w większy arkusz ze względów wydajnościowych i pamięciowych. Może zawierać nieruchome obrazy albo sekwencje obrazów tworzące animację poklatkową. Atlasy są używane przez różne komponenty do współdzielenia zasobów graficznych. Więcej w [dokumentacji Atlasa](/manuals/atlas). -## Builtins (Wbudowane elementy) +## Builtins (Wbudowane zasoby) -![Builtins](images/icons/builtins.png){.left} Folder `builtins` w projekcie zawiera domyślne, tylko do odczytu zasoby. Znajdziesz tam domyślny renderer, skrypt renderujący, materiały i inne elementy. Jeśli potrzebujesz zmodyfikować któryś z tych zasobów, skopiuj go do projektu i edytuj według potrzeb. +![Builtins](images/icons/builtins.png){.left} Folder projektu builtins jest tylko do odczytu i zawiera przydatne domyślne zasoby. Znajdziesz w nim domyślny renderer, render script, materiały i inne elementy. Jeśli potrzebujesz własnych modyfikacji któregoś z tych zasobów, po prostu skopiuj go do projektu i edytuj według potrzeb. ## Camera (Kamera) -![Camera](images/icons/camera.png){.left} Komponent kamery decyduje, która część świata gry ma być widoczna i jak ma być rzutowana. Powszechną praktyką jest przypinać kamerę do obiektu gracza albo tworzyć osobny obiekt, który podąża za graczem z dodatkowym wygładzaniem. Więcej w [dokumentacji do Kamery](/manuals/camera). +![Camera](images/icons/camera.png){.left} Komponent kamery pomaga określić, która część świata gry ma być widoczna i jak ma być rzutowana. Często przypina się kamerę do obiektu gry gracza albo tworzy osobny obiekt gry z kamerą, która podąża za graczem z użyciem wygładzania. Więcej w [dokumentacji kamery](/manuals/camera). ## Collision object (Obiekt kolizji) -![Collision object](images/icons/collision-object.png){.left} Obiekty kolizji rozszerzają obiekty gry o właściwości fizyczne, takie jak kształt przestrzenny, masa, tarcie i tłumienie. To one decydują, jak dany obiekt reaguje na kontakt z innymi. Najczęściej spotykane typy to obiekty kinematyczne, dynamiczne i wyzwalacze. Kinematyczny obiekt dostarcza szczegółowe informacje o kolizji, które możesz obsłużyć ręcznie, dynamiczny obiekt jest symulowany przez silnik fizyki zgodnie z prawami Newtona, a wyzwalacze wykrywają tylko wejście lub wyjście innych kształtów. Szczegóły w [dokumentacji do Fizyki](/manuals/physics). +![Collision object](images/icons/collision-object.png){.left} Obiekty kolizji rozszerzają obiekty gry o właściwości fizyczne, takie jak kształt przestrzenny, masa, tarcie i odbicie. Te właściwości decydują o tym, jak obiekt kolizji ma zderzać się z innymi obiektami kolizji. Najczęściej spotykane typy obiektów kolizji to obiekty kinematyczne, dynamiczne i wyzwalacze. Obiekt kinematyczny daje szczegółowe informacje o kolizji, na które musisz zareagować ręcznie, a obiekt dynamiczny jest automatycznie symulowany przez silnik fizyki zgodnie z prawami Newtona. Wyzwalacze to proste kształty wykrywające wejście lub wyjście innych kształtów. Szczegóły znajdziesz w [dokumentacji Fizyki](/manuals/physics). ## Component (Komponent) -Komponenty nadają obiektom gry konkretną ekspresję lub funkcjonalność, na przykład grafikę, animację, zachowanie zdefiniowane skryptem czy dźwięk. Nie żyją osobno — muszą należeć do obiektów gry. W silniku Defold dostępnych jest wiele rodzajów komponentów, opisanych w [instrukcji o blokach budujących](/manuals/building-blocks). +Komponenty służą do nadawania obiektom gry konkretnej formy lub funkcjonalności, takiej jak grafika, animacja, zachowanie opisane skryptem czy dźwięk. Nie istnieją samodzielnie, tylko muszą być częścią obiektów gry. W Defold dostępnych jest wiele rodzajów komponentów. Opis znajdziesz w [instrukcji o blokach budujących](/manuals/building-blocks). ## Collection (Kolekcja) -![Collection](images/icons/collection.png){.left} Kolekcje to mechanizm pozwalający tworzyć szablony (prefaby) zawierające hierarchie obiektów gry. Są strukturami drzewa przechowującymi obiekty gry i inne kolekcje. Kolekcje przechowywane są jako pliki i wprowadza się je do gry statycznie przez edytor lub dynamicznie przez generowanie. Więcej w [instrukcji o blokach budujących](/manuals/building-blocks). +![Collection](images/icons/collection.png){.left} Kolekcje są mechanizmem Defold do tworzenia szablonów, czyli tego, co w innych silnikach nazywa się prefabami, w których można wielokrotnie używać hierarchii obiektów gry. Są to struktury drzewiaste zawierające obiekty gry i inne kolekcje. Kolekcja jest zawsze zapisana w pliku i trafia do gry albo statycznie, gdy umieścisz ją ręcznie w edytorze, albo dynamicznie, gdy ją utworzysz w locie. Więcej w [instrukcji o blokach budujących](/manuals/building-blocks). ## Collection factory (Fabryka kolekcji) -![Collection factory](images/icons/collection-factory.png){.left} Fabryka kolekcji pozwala dynamicznie tworzyć hierarchie obiektów gry zgodne z opisem w kolekcji. Szczegóły w [instrukcji do Fabryki kolekcji](/manuals/collection-factory). +![Collection factory](images/icons/collection-factory.png){.left} Komponent Collection factory służy do dynamicznego tworzenia hierarchii obiektów gry w uruchomionej grze. Szczegóły znajdziesz w [instrukcji fabryki kolekcji](/manuals/collection-factory). ## Collection proxy (Pełnomocnik kolekcji) -![Collection](images/icons/collection.png){.left} Pełnomocnik kolekcji służy do ładowania i aktywowania kolekcji w trakcie działania aplikacji. Najczęściej używa się go do wczytywania kolejnych poziomów. Zobacz [dokumentację do Pełnomocników kolekcji](/manuals/collection-proxy). +![Collection](images/icons/collection.png){.left} Collection proxy służy do wczytywania i aktywowania kolekcji w locie, gdy aplikacja lub gra działa. Najczęściej używa się go do wczytywania poziomów przed ich uruchomieniem. Szczegóły znajdziesz w [dokumentacji pełnomocnika kolekcji](/manuals/collection-proxy). -## Cubemap (Tekstura sześcienna) +## Cubemap (Cubemap) -![Cubemap](images/icons/cubemap.png){.left} Tekstura sześcienna (cubemap) to specjalny typ tekstury złożony z sześciu osobnych obrazów mapowanych na ściany sześcianu. Przydatna do renderowania skyboxów oraz map odbić i oświetlenia. +![Cubemap](images/icons/cubemap.png){.left} Cubemap to specjalny typ tekstury złożony z 6 różnych tekstur mapowanych na ściany sześcianu. Jest to przydatne przy renderowaniu skyboxów oraz różnych map odbić i oświetlenia. ## Debugging (Debugowanie) -Kiedy gra zaczyna zachowywać się nieoczekiwanie, musisz odnaleźć przyczynę. Nauka debugowania jest sztuką, a Defold oferuje wbudowany debugger, który ułatwia to zadanie. Więcej w [instrukcji do Debugowania](/manuals/debugging). +W pewnym momencie gra zacznie zachowywać się w nieoczekiwany sposób i trzeba będzie ustalić, co jest nie tak. Nauka debugowania to sztuka, a na szczęście Defold ma wbudowany debugger, który pomaga w tej pracy. Więcej w [instrukcji debugowania](/manuals/debugging). ## Display profiles (Profile wyświetlania) -![Display profiles](images/icons/display-profiles.png){.left} Plik profilu wyświetlania pozwala określić układy GUI zależne od orientacji, proporcji obrazu lub modelu urządzenia. Dzięki temu można dostosować interfejs do różnorodnych ekranów. Więcej w [instrukcji do Układów](/manuals/gui-layouts). +![Display profiles](images/icons/display-profiles.png){.left} Plik zasobu display profiles służy do określania układów GUI zależnych od orientacji, proporcji obrazu lub modelu urządzenia. Pomaga to dostosować UI do różnych urządzeń. Więcej w [instrukcji układów GUI](/manuals/gui-layouts). ## Factory (Fabryka) -![Factory](images/icons/factory.png){.left} Czasem nie chcesz tworzyć wszystkich obiektów gry ręcznie w kolekcji — potrzebujesz ich w czasie działania gry. Fabryka umożliwia dynamiczne tworzenie takich obiektów z wcześniej przygotowanej puli. Zobacz [instrukcję do Fabryki](/manuals/factory). +![Factory](images/icons/factory.png){.left} W niektórych sytuacjach nie da się ręcznie umieścić wszystkich potrzebnych obiektów gry w kolekcji, więc trzeba tworzyć je dynamicznie, w locie. Na przykład gracz może wystrzeliwać pociski i każdy strzał powinien być tworzony oraz wysyłany dalej, gdy gracz naciska spust. Do tworzenia obiektów gry dynamicznie, z wcześniej przygotowanej puli obiektów, służy komponent factory. Szczegóły znajdziesz w [instrukcji factory](/manuals/factory). ## Font (Czcionka) -![Font file](images/icons/font.png){.left} Zasób typu Font powstaje na podstawie pliku TrueType lub OpenType i określa rozmiar oraz dekoracje (np. obrys, cień) renderowanej czcionki. Fonty wykorzystują komponenty GUI i Label. Więcej w [instrukcji do Fontów](/manuals/font/). +![Font file](images/icons/font.png){.left} Zasób Font powstaje z pliku czcionki TrueType lub OpenType. Określa rozmiar renderowanej czcionki oraz rodzaj dekoracji, takich jak obrys i cień. Fonty są używane przez komponenty GUI i Label. Szczegóły znajdziesz w [instrukcji fontu](/manuals/font/). -## Fragment shader (Shader fragmentu) +## Fragment shader (Fragment shader) -![Fragment shader](images/icons/fragment-shader.png){.left} Shader fragmentu to program uruchamiany na procesorze graficznym dla każdego piksela (fragmentu) rysowanego wielokąta. Określa kolor wynikowego fragmentu, wykonując obliczenia, odczyty tekstur lub ich kombinacje. Szczegóły w [instrukcji do Shaderów](/manuals/shader). +![Fragment shader](images/icons/fragment-shader.png){.left} To program uruchamiany na procesorze graficznym dla każdego piksela, czyli fragmentu, wielokąta podczas jego rysowania na ekranie. Zadaniem fragment shader jest określenie koloru każdego wynikowego fragmentu. Można to zrobić przez obliczenia, odczyty z tekstur, albo połączenie obu metod. Więcej w [instrukcji shaderów](/manuals/shader). -## Gamepads (Kontrolery) +## Gamepads (Gamepads) -![Gamepads](images/icons/gamepad.png){.left} Plik Gamepads definiuje sposób mapowania wejść ze konkretnych kontrolerów na wyzwalacze wejścia dostępne dla danej platformy. Więcej w [instrukcji do Wejść](/manuals/input). +![Gamepads](images/icons/gamepad.png){.left} Plik zasobu gamepads określa, jak wejścia z konkretnych urządzeń gamepad są mapowane na wyzwalacze wejścia dla danej platformy. Szczegóły znajdziesz w [instrukcji wejścia](/manuals/input). ## Game object (Obiekt gry) -![Game object](images/icons/game-object.png){.left} Obiekty gry to kontenery ze swoim cyklem życia podczas działania gry. Zazwyczaj zawierają komponenty wizualne albo dźwiękowe oraz mogą mieć zachowanie opisane skryptem. Tworzy się je w edytorze, umieszczając w kolekcjach, albo dynamicznie przez fabryki. Szczegóły w [instrukcji o blokach budujących](/manuals/building-blocks). +![Game object](images/icons/game-object.png){.left} Obiekty gry to proste obiekty mające własny cykl życia podczas działania gry. Są kontenerami i zwykle zawierają komponenty wizualne albo dźwiękowe, takie jak sound lub sprite. Mogą też mieć zachowanie dodane przez komponenty skryptowe. Tworzysz je i umieszczasz w kolekcjach w edytorze albo generujesz dynamicznie w czasie działania za pomocą factory. Więcej w [instrukcji o blokach budujących](/manuals/building-blocks). -## GUI (Interfejs graficzny użytkownika) +## GUI (GUI) -![GUI component](images/icons/gui.png){.left} Komponent GUI zawiera elementy interfejsu: tekst, kolorowe lub teksturowane bloki. Elementy można organizować hierarchicznie, skryptować i animować. GUI służy do HUD, menu i powiadomień. Steruje nim skrypt GUI, który opisuje zachowanie i interakcje użytkownika. Więcej w [dokumentacji do GUI](/manuals/gui). +![GUI component](images/icons/gui.png){.left} Komponent GUI zawiera elementy służące do budowy interfejsów użytkownika: tekst oraz kolorowe lub teksturowane bloki. Elementy można organizować hierarchicznie, skryptować i animować. Komponenty GUI zwykle służą do tworzenia HUD-ów, systemów menu i powiadomień na ekranie. Sterują nimi skrypty GUI, które definiują zachowanie GUI i obsługę interakcji użytkownika. Więcej w [dokumentacji GUI](/manuals/gui). ## GUI script (Skrypt GUI) -![GUI script](images/icons/script.png){.left} Skrypty GUI kontrolują zachowanie komponentów GUI — animacje, reakcje na wejścia i inne interakcje. Zobacz [instrukcję o Lua w silniku Defold](/manuals/lua), aby dowiedzieć się, jak są wykorzystywane. +![GUI script](images/icons/script.png){.left} Skrypty GUI służą do sterowania zachowaniem komponentów GUI. Kontrolują animacje GUI i sposób, w jaki użytkownik wchodzi z nimi w interakcję. Szczegóły znajdziesz w [instrukcji Lua w Defold](/manuals/lua). ## Hot reload (Szybkie przeładowanie) -Edytor Defold pozwala aktualizować zawartość w uruchomionym programie na desktopie i urządzeniach mobilnych. Ta funkcja przyspiesza pracę przy rozwoju gry. Więcej w [instrukcji do Hot reload](/manuals/hot-reload). +Edytor Defold pozwala aktualizować zawartość już uruchomionej gry na desktopie i urządzeniach. Ta funkcja jest bardzo potężna i może znacząco usprawnić proces tworzenia. Więcej w [instrukcji hot reload](/manuals/hot-reload). ## Input binding (Wiązania wejść) -![Input binding](images/icons/input-binding.png){.left} Pliki wiązań wejść określają, jak interpretować sygnały z myszy, klawiatury, ekranu dotykowego czy gamepada. Wiążą sprzętowe wejścia z wysokopoziomowymi akcjami, takimi jak `jump` czy `move_forward`. Skrypty nasłuchujące wejść reagują na te akcje w sposób określony przez twórcę. Więcej w [instrukcji do Wejść](/manuals/input). +![Input binding](images/icons/input-binding.png){.left} Pliki Input binding określają, jak gra ma interpretować wejścia sprzętowe, takie jak mysz, klawiatura, ekran dotykowy i gamepad. Plik mapuje wejścia sprzętowe na wysokopoziomowe akcje wejściowe, takie jak jump i move_forward. W komponentach skryptowych nasłuchujących wejścia możesz opisać, jakie działania ma wykonać gra lub aplikacja po otrzymaniu określonego wejścia. Szczegóły znajdziesz w [instrukcji wejścia](/manuals/input). ## Label (Etykieta) -![Label](images/icons/label.png){.left} Komponent Label umożliwia przypisanie tekstu do obiektu gry. Renderuje go przy użyciu wybranego fontu, w przestrzeni gry (nie GUI). Więcej w [instrukcji do Etykiet](/manuals/label). +![Label](images/icons/label.png){.left} Komponent Label pozwala dołączyć tekst do dowolnego obiektu gry. Renderuje fragment tekstu przy użyciu określonego fontu, w przestrzeni gry. Więcej w [instrukcji etykiety](/manuals/label). ## Library (Biblioteka) -![Game object](images/icons/builtins.png){.left} Defold pozwala współdzielić dane między projektami za pomocą bibliotek. Możesz z nich korzystać w wielu projektach, dla siebie lub zespołu. Szczegóły w [dokumentacji do Bibliotek](/manuals/libraries). +![Game object](images/icons/builtins.png){.left} Defold pozwala współdzielić dane między projektami za pomocą mechanizmu bibliotek. Możesz z niego korzystać, aby tworzyć współdzielone biblioteki dostępne we wszystkich projektach, dla siebie albo dla całego zespołu. Więcej w [dokumentacji bibliotek](/manuals/libraries). ## Lua language (Język Lua) -Lua to język skryptowy wykorzystywany do tworzenia logiki gry w silniku Defold. Jest mały, wydajny i wspiera programowanie proceduralne, obiektowe, funkcyjne oraz data-driven. Więcej na oficjalnej stronie https://www.lua.org/ oraz w [instrukcji do Lua](/manuals/lua). +Język programowania Lua jest używany w Defold do tworzenia logiki gry. Lua to mały, wydajny i bardzo elastyczny język skryptowy. Obsługuje programowanie proceduralne, obiektowe, funkcyjne, oparte na danych oraz opis danych. Więcej o języku znajdziesz na oficjalnej stronie Lua: https://www.lua.org/ oraz w [instrukcji Lua w Defold](/manuals/lua). ## Lua module (Moduł Lua) -![Lua module](images/icons/lua-module.png){.left} Moduły Lua pozwalają tworzyć struktury wielokrotnego użytku i czytelnie organizować kod. Więcej w [instrukcji do modułów Lua](/manuals/modules/). +![Lua module](images/icons/lua-module.png){.left} Moduły Lua pozwalają strukturyzować projekt i tworzyć wielokrotnego użytku kod biblioteczny. Więcej w [instrukcji modułów Lua](/manuals/modules/). ## Material (Materiał) -![Material](images/icons/material.png){.left} Materiały opisują sposób renderowania obiektów przez przypisanie shaderów i ich właściwości. Więcej w [instrukcji do Materiałów](/manuals/material). +![Material](images/icons/material.png){.left} Materiały definiują sposób renderowania różnych obiektów przez określenie shaderów i ich właściwości. Więcej w [instrukcji materiałów](/manuals/material). ## Message (Wiadomość) -Komponenty komunikują się poprzez przesyłanie wiadomości silnika Defold. Mogą też automatycznie reagować na określone wiadomości, np. włączać/wyłączać grafikę, kolizje, animacje, efekty cząsteczkowe lub dźwięk. Silnik używa wiadomości do informowania o zdarzeniach, jak kolizje. System wiadomości potrzebuje odbiorcy, więc wszystko w grze ma unikalny adres. Aby ułatwić komunikację, Defold rozszerza Lua o mechanizm przechwytywania i wysyłania wiadomości oraz dostarcza przydatne funkcje. +Komponenty komunikują się ze sobą i z innymi systemami za pomocą przekazywania wiadomości. Reagują też na zestaw predefiniowanych wiadomości, które zmieniają ich stan albo wyzwalają konkretne działania. Możesz wysyłać wiadomości, aby ukrywać grafikę lub poruszać obiektami fizycznymi. Silnik używa też wiadomości do powiadamiania komponentów o zdarzeniach, na przykład gdy kształty fizyczne zderzają się ze sobą. Mechanizm przekazywania wiadomości wymaga odbiorcy dla każdej wysłanej wiadomości. Dlatego wszystko w grze ma unikalny adres. Aby ułatwić komunikację między obiektami, Defold rozszerza Lua o przekazywanie wiadomości. Defold udostępnia też bibliotekę przydatnych funkcji. -Przykładowo, aby ukryć sprite `weapon`, wystarczy: +Na przykład kod Lua potrzebny do ukrycia komponentu sprite na obiekcie gry wygląda tak: ```lua msg.post("#weapon", "disable") ``` -`"#weapon"` to adres komponentu, z którego wysyłana jest wiadomość, a `"disable"` to nazwa wiadomości, na którą reaguje sprite. Więcej w [dokumentacji do przesyłania wiadomości](/manuals/message-passing). +Tutaj `"#weapon"` jest adresem komponentu sprite bieżącego obiektu. `"disable"` to wiadomość, na którą reagują komponenty sprite. Dokładniejsze wyjaśnienie działania tego mechanizmu znajdziesz w [dokumentacji przekazywania wiadomości](/manuals/message-passing). ## Model (Model) -![Model](images/icons/model.png){.left} Komponent Model umożliwia import siatek, szkielety i animacje z formatu glTF do gry. Więcej w [instrukcji do Modeli](/manuals/model/). +![Model](images/icons/model.png){.left} Komponent modelu 3D może importować zasoby siatki, szkieletu i animacji glTF do gry. Więcej w [instrukcji modelu](/manuals/model/). -## ParticleFX (Efekt cząsteczkowy) +## ParticleFX (ParticleFX) -![ParticleFX](images/icons/particlefx.png){.left} Efekty cząsteczkowe pomagają tworzyć wizualne efekty, takie jak mgła, ogień, deszcz czy spadające liście. Defold wyposażono w edytor ParticleFX, który pozwala budować i dopasowywać efekty w czasie rzeczywistym. Więcej w [dokumentacji do ParticleFX](/manuals/particlefx). +![ParticleFX](images/icons/particlefx.png){.left} Cząstki są bardzo przydatne do tworzenia efektownych wizualnie efektów, szczególnie w grach. Możesz ich użyć do mgły, dymu, ognia, deszczu albo opadających liści. Defold zawiera rozbudowany edytor ParticleFX, który pozwala budować i dostrajać efekty podczas ich działania w czasie rzeczywistym. Szczegóły znajdziesz w [dokumentacji ParticleFX](/manuals/particlefx). ## Profiling (Profilowanie) -Dobra wydajność jest kluczowa, dlatego warto mierzyć wydajność i pamięć gry, aby wykryć wąskie gardła. Defold udostępnia narzędzia do profilowania. Szczegóły w [instrukcji do Profilowania](/manuals/profiling). +Dobra wydajność jest kluczowa w grach, dlatego ważne jest, aby móc profilować wydajność i pamięć, mierzyć grę oraz znajdować wąskie gardła i problemy z pamięcią wymagające naprawy. Więcej o dostępnych w Defold narzędziach profilujących znajdziesz w [instrukcji profilowania](/manuals/profiling). ## Render (Render) -![Render](images/icons/render.png){.left} Pliki Render zawierają ustawienia używane podczas renderowania gry — określają, który render script i materiały mają być użyte. Więcej w [instrukcji do Renderowania](/manuals/render/). +![Render](images/icons/render.png){.left} Pliki Render zawierają ustawienia używane podczas renderowania gry na ekranie. Określają, którego render script użyć do renderowania oraz jakich materiałów użyć. Więcej w [instrukcji renderowania](/manuals/render/). ## Render script (Skrypt do renderowania) -![Render script](images/icons/script.png){.left} Skrypt do renderowania to skrypt Lua sterujący tym, jak gra jest renderowana na ekranie. Domyślny skrypt pokrywa większość scenariuszy, ale możesz napisać własny, jeśli potrzebujesz niestandardowych efektów lub oświetlenia. Więcej w [instrukcji do Renderowania](/manuals/render/) oraz w [instrukcji do Lua](/manuals/lua). +![Render script](images/icons/script.png){.left} Render script to skrypt Lua sterujący tym, jak gra lub aplikacja ma być renderowana na ekranie. Istnieje domyślny render script, który pokrywa większość typowych przypadków, ale możesz napisać własny, jeśli potrzebujesz niestandardowych modeli oświetlenia i innych efektów. Szczegóły działania pipeline renderowania i wykorzystania skryptów Lua w Defold znajdziesz w [instrukcji renderowania](/manuals/render/) oraz w [instrukcji Lua w Defold](/manuals/lua). ## Script (Skrypt) -![Script](images/icons/script.png){.left} Skrypt to komponent zawierający kod, który definiuje zachowanie obiektu gry. Dzięki skryptom ustalasz reguły gry, reagujesz na interakcje i aktualizujesz stan świata. Wszystkie skrypty pisze się w Lua — aby pracować z silnikiem Defold, ty lub ktoś z zespołu musi poznać ten język. Więcej w [instrukcji do Lua](/manuals/lua). +![Script](images/icons/script.png){.left} Skrypt to komponent zawierający program definiujący zachowanie obiektu gry. Dzięki skryptom możesz określić zasady gry i sposób, w jaki obiekty mają reagować na różne interakcje, zarówno z graczem, jak i z innymi obiektami. Wszystkie skrypty są pisane w Lua. Aby pracować z Defold, ty lub ktoś z twojego zespołu musi nauczyć się programować w Lua. Omówienie Lua i szczegóły użycia skryptów Lua w Defold znajdziesz w [instrukcji Lua w Defold](/manuals/lua). ## Sound (Dźwięk) -![Sound](images/icons/sound.png){.left} Komponent dźwiękowy odtwarza określony plik audio. Defold wspiera formaty WAV i Ogg Vorbis. Więcej w [instrukcji do Dźwięków](/manuals/sound). +![Sound](images/icons/sound.png){.left} Komponent sound odpowiada za odtwarzanie określonego dźwięku. Obecnie Defold obsługuje pliki WAV i Ogg Vorbis. Więcej w [instrukcji dźwięku](/manuals/sound). -## Sprite (Obraz) +## Sprite (Sprite) -![Sprite](images/icons/sprite.png){.left} Sprite to komponent graficzny, który wyświetla obraz z Tile source lub Atlasu. Obsługuje animacje poklatkowe i oparte na kościach. Sprite’y najczęściej reprezentują postacie i przedmioty w grach 2D. +![Sprite](images/icons/sprite.png){.left} Sprite to komponent, który rozszerza obiekty gry o grafikę. Wyświetla obraz z Tile source albo Atlasu. Sprite ma wbudowaną obsługę animacji poklatkowych i animacji opartych na kościach. Sprite’y są zwykle używane do postaci i przedmiotów. ## Texture profiles (Profile teksturowania) -![Texture profiles](images/icons/texture-profiles.png){.left} Profile teksturowania używane są podczas bundlingu, aby automatycznie przetwarzać i kompresować dane obrazowe (w atlasach, Tile sources, cubemapach i osobnych teksturach używanych w modelach czy GUI). Więcej w [instrukcji do Profili teksturowania](/manuals/texture-profiles). +![Texture profiles](images/icons/texture-profiles.png){.left} Plik zasobu texture profiles jest używany w procesie bundlowania do automatycznego przetwarzania i kompresowania danych obrazowych w atlasach, Tile source, Cubemapach oraz osobnych teksturach używanych w modelach, GUI i innych elementach. Więcej w [instrukcji profili teksturowania](/manuals/texture-profiles). ## Tile map (Mapa kafelków) -![Tile map](images/icons/tilemap.png){.left} Mapa kafelków wyświetla obrazy z Tile source na jednej lub kilku warstwach siatki. Można używać jej do tworzenia poziomów, ścian, budynków, przeszkód czy jaskiń. Obsługuje wiele warstw w różnych trybach mieszania i pozwala na dynamiczną podmianę pojedynczych kafelków (np. żeby zniszczyć most i zmienić kolizje). Więcej w [dokumentacji do Tile map](/manuals/tilemap). +![Tile map](images/icons/tilemap.png){.left} Komponent tile map wyświetla obrazy z tile source w jednej lub kilku nakładających się siatkach. Najczęściej służy do tworzenia otoczenia gry: podłoża, ścian, budynków i przeszkód. Tile map może wyświetlać kilka warstw wyrównanych jedna nad drugą z określonym trybem mieszania. Przydaje się to na przykład do umieszczania roślinności nad kafelkami trawy. Można też dynamicznie zmieniać obraz wyświetlany w kafelku. Pozwala to na przykład zniszczyć most i uczynić go nieprzejezdnym, po prostu zastępując kafelki obrazami zniszczonego mostu i odpowiednimi kształtami fizyki. Więcej w [dokumentacji tile map](/manuals/tilemap). ## Tile source (Źródło kafelków) -![Tile source](images/icons/tilesource.png){.left} Tile source to tekstura składająca się z wielu mniejszych obrazów tej samej wielkości, czyli kafelków. Można z niej tworzyć animacje poklatkowe, a także automatycznie generować kształty kolizji. Tile source używa się w Tile mapach, ale też jako teksturę do sprite’ów i efektów cząsteczkowych. Więcej w [dokumentacji do Tile map](/manuals/tilemap). +![Tile source](images/icons/tilesource.png){.left} Tile source opisuje teksturę złożoną z wielu mniejszych obrazów o tym samym rozmiarze. Można z niej definiować animacje poklatkowe na podstawie sekwencji obrazów. Tile source może też automatycznie obliczać kształty kolizji z danych obrazu. Jest to bardzo przydatne przy tworzeniu kafelkowych poziomów, z którymi obiekty mogą się zderzać i wchodzić w interakcje. Tile source są używane przez komponenty tile map, a także Sprite i ParticleFX, do współdzielenia zasobów graficznych. Zwróć uwagę, że atlasy często lepiej się sprawdzają niż tile source. Więcej w [dokumentacji tile map](/manuals/tilemap). -## Vertex shader (Shader wierzchołków) +## Vertex shader (Vertex shader) -![Vertex shader](images/icons/vertex-shader.png){.left} Shader wierzchołków to program uruchamiany na GPU, który przetwarza geometrię siatek (wielokąty) i oblicza końcowe pozycje wierzchołków na ekranie. Więcej w [instrukcji do Shaderów](/manuals/shader). +![Vertex shader](images/icons/vertex-shader.png){.left} Vertex shader oblicza geometrię ekranu dla prymitywnych kształtów wielokąta danego komponentu. Dla każdego typu komponentu wizualnego, czy to sprite, tile map czy model, kształt jest reprezentowany przez zbiór pozycji wierzchołków wielokąta. Program vertex shader przetwarza każdy wierzchołek w przestrzeni świata i oblicza końcowe współrzędne, jakie powinien mieć każdy wierzchołek prymitywu. Więcej w [instrukcji shaderów](/manuals/shader). diff --git a/docs/pl/manuals/gpgs.md b/docs/pl/manuals/gpgs.md new file mode 100644 index 00000000..ac5af8c9 --- /dev/null +++ b/docs/pl/manuals/gpgs.md @@ -0,0 +1,6 @@ +--- +title: Google Play Game Services w silniku Defold +brief: Ten dokument opisuje, jak skonfigurować i używać Google Play Game Services. +--- + +[Ten podręcznik został przeniesiony tutaj](/extension-gpgs). diff --git a/docs/pl/manuals/graphics.md b/docs/pl/manuals/graphics.md new file mode 100644 index 00000000..08334227 --- /dev/null +++ b/docs/pl/manuals/graphics.md @@ -0,0 +1,10 @@ +--- +title: Podręcznik grafiki w silniku Defold +brief: Ten podręcznik opisuje obsługę elementów graficznych w Defold. +--- + +Przestarzały podręcznik! + +* Przeczytaj więcej o [tym, jak importować i używać grafiki 2D](/manuals/importing-graphics) +* Przeczytaj więcej o [filtrowaniu tekstur](/manuals/texture-filtering) +* Przeczytaj więcej o [materiałach](/manuals/material) diff --git a/docs/pl/manuals/gui-box.md b/docs/pl/manuals/gui-box.md index 28a62292..4f1b05c3 100644 --- a/docs/pl/manuals/gui-box.md +++ b/docs/pl/manuals/gui-box.md @@ -1,28 +1,28 @@ --- -title: Węzły prostokątne - box w Defoldzie -brief: Ta instrukcja wyjaśnia jak używać węzłów typu box. +title: Węzły GUI typu box w Defold +brief: Ta instrukcja wyjaśnia, jak używać węzłów GUI typu box. --- -# Węzeł GUI typu box +# Węzły GUI typu box -Węzeł prostokątny box to prostokąt wypełniony kolorem, teksturą lub animacją. +Węzeł GUI typu box to prostokąt wypełniony kolorem, teksturą lub animacją. ## Dodawanie węzłów box -Dodaj nowe węzły box, klikając prawym przyciskiem myszy w widoku "Outline" i wybierając Add ▸ Box, lub naciśnij klawisz A i wybierz Box. +Dodaj nowe węzły box, klikając prawym przyciskiem myszy w *Outline* i wybierając Add ▸ Box, albo naciśnij A i wybierz Box. -Możesz używać obrazów i animacji z atlasów lub źródeł kafelków, które zostały dodane do GUI. Dodaj tekstury, klikając prawym przyciskiem myszy na ikonę folderu "Textures" w widoku "Outline" i wybierając Add ▸ Textures.... Następnie ustaw właściwość *Texture* węzłu box na daną teksturę: +Możesz używać obrazów i animacji z atlasów lub źródeł kafelków dodanych do GUI. Aby dodać tekstury, kliknij prawym przyciskiem myszy ikonę folderu *Textures* w *Outline* i wybierz Add ▸ Textures.... Następnie ustaw właściwość *Texture* węzła box: -![Textures](images/gui-box/create.png) +![Tekstury](images/gui-box/create.png) -Należy zauważyć, że kolor węzła box będzie barwił (ang. tint) grafikę. Kolor barwienia jest mnożony przez dane obrazu, co oznacza, że jeśli ustawisz kolor na biały (domyślny), w praktyce nie zostanie zastosowane barwienie. +Zwróć uwagę, że kolor węzła box zabarwia grafikę. Kolor zabarwienia jest mnożony przez dane obrazu, więc jeśli ustawisz kolor na biały (domyślny), nie zostanie zastosowane zabarwienie. -![Tinted texture](images/gui-box/tinted.png) +![Teksturowany obraz](images/gui-box/tinted.png) -Węzły box są zawsze renderowane, nawet jeśli nie mają przypisanej tekstury, mają ustawioną wartość alfa na `0` lub mają rozmiar `0, 0, 0`. Węzły box powinny zawsze mieć przypisaną do nich teksturę, aby renderer mógł je właściwie grupować i zmniejszać liczbę wywołań rysowania (ang. draw calls). +Węzły box są zawsze renderowane, nawet jeśli nie mają przypisanej tekstury, mają ustawioną alfę na `0` albo mają rozmiar `0, 0, 0`. Węzły box powinny zawsze mieć przypisaną teksturę, aby renderer mógł je poprawnie grupować i zmniejszać liczbę wywołań rysowania. ## Odtwarzanie animacji -Węzły pudełkowe mogą odtwarzać animacje z atlasów lub źródeł kafelków. Aby dowiedzieć się więcej, zajrzyj do [instrukcji do animacji flipbook](/manuals/flipbook-animation). +Węzły box mogą odtwarzać animacje z atlasów lub źródeł kafelków. Więcej informacji znajdziesz w [instrukcji animacji flipbook](/manuals/flipbook-animation). :[Slice-9](../shared/slice-9-texturing.md) diff --git a/docs/pl/manuals/gui-clipping.md b/docs/pl/manuals/gui-clipping.md index 55e3f5a5..8b2cabb1 100644 --- a/docs/pl/manuals/gui-clipping.md +++ b/docs/pl/manuals/gui-clipping.md @@ -1,75 +1,75 @@ --- -title: Wycinanie GUI w Defoldzie -brief: Ta instrukcja wyjaśnia jak działa przycinanie i maskowanie GUI w Defoldzie +title: Instrukcja wycinania GUI +brief: Ta instrukcja opisuje, jak tworzyć węzły GUI maskujące inne węzły za pomocą wycinania stencil. --- -# Wycinanie GUI +# Wycinanie -Węzły GUI można wykorzystać jako węzły wycinające (*clipping* nodes) - maski kontrolujące, jak renderowane są inne węzły. Ta instrukcja wyjaśnia, jak działa ta funkcjonalność. +Węzły GUI można wykorzystać jako węzły *clipping* - maski kontrolujące sposób renderowania innych węzłów. Ta instrukcja wyjaśnia, jak działa ta funkcjonalność. ## Tworzenie węzła wycinającego -Węzły typu Box, Text i Pie można wykorzystać jako węzły wycinające. Aby utworzyć węzeł wycinający, dodaj węzeł do swojego GUI, a następnie ustaw jego właściwości odpowiednio: +Węzły Box, Text i Pie można wykorzystać do wycinania. Aby utworzyć węzeł wycinający, dodaj węzeł w GUI, a następnie ustaw jego właściwości: Clipping Mode : Tryb używany do wycinania. - - `None` renderuje węzeł bez jakiegokolwiek wycinania. - - `Stencil` - maska - sprawia, że węzeł zapisuje bieżącą maskę wycięcia. + - `None` renderuje węzeł bez wycinania. + - `Stencil` sprawia, że węzeł zapisuje do bieżącej maski stencil. Clipping Visible : Zaznacz, aby renderować zawartość węzła. Clipping Inverted -: Zaznacz, aby zapisać odwrócenie kształtu węzła w masce. +: Zaznacz, aby zapisać odwróconą wersję kształtu węzła w masce. -Następnie dodaj węzeł lub węzły, które chcesz wyciąć jako dzieci węzła wycinającego. +Następnie dodaj węzeł lub węzły, które chcesz wycinać, jako dzieci węzła wycinającego. -![Create clipping](images/gui-clipping/create.png) +![Utworzenie wycinania](images/gui-clipping/create.png) -## Maska wycinająca +## Maska stencil -Wycinanie działa poprzez zapisywanie węzłów do bufora wycinania (*stencil buffer*). Ten bufor zawiera maski wycinania: informacje, które mówią karcie graficznej, czy dany piksel powinien być renderowany, czy nie. +Wycinanie działa przez zapisywanie przez węzły do *stencil buffer*. Ten bufor zawiera maski wycinania, czyli informacje mówiące karcie graficznej, czy dany piksel ma zostać wyrenderowany. -- Węzeł bez rodzica wycinającego, ale z ustawionym trybem wycinania `Stencil`, zapisuje swój kształt (lub odwrotny kształt) do nowej maski wycinania przechowywanej w buforze wycinania. -- Jeśli węzeł wycinający ma rodzica wycinającego, zamiast tego przycinany jest kształt maski wycinania rodzica. Węzeł dziecka wycinającego nie może _rozszerzać_ bieżącej maski wycinania, tylko ją dalej przycina. -- Węzły, które nie są węzłami wycinającymi i są dziećmi węzłów wycinających, zostaną wyrenderowane z maską wycinania stworzoną przez hierarchię rodzica. +- Węzeł bez rodzica wycinającego, ale z ustawionym trybem wycinania `Stencil`, zapisuje swój kształt (lub jego odwróconą wersję) do nowej maski wycinania przechowywanej w buforze stencil. +- Jeśli węzeł wycinający ma rodzica wycinającego, zamiast tego przycinana jest maska wycinania rodzica. Węzeł podrzędny wycinający nie może _rozszerzyć_ bieżącej maski wycinania, może ją tylko dalej przycinać. +- Węzły, które nie są węzłami wycinającymi i są dziećmi węzłów wycinających, zostaną wyrenderowane z maską wycinania utworzoną przez hierarchię rodziców. -![Clipping hierarchy](images/gui-clipping/setup.png) +![Hierarchia wycinania](images/gui-clipping/setup.png) -W tym przykładzie utworzono trzy węzły w hierarchii: +W tej hierarchii skonfigurowano trzy węzły: -- Kształty szesciokąta i kwadratu to węzły przycinające stencil. -- Sześciokąt tworzy nową maskę wycinania, a kwadrat ją dodatkowo przycina. -- Węzeł koła to zwykły węzeł typu pie, więc zostanie wyrenderowany z maską wycinania utworzoną przez węzły nadrzędne. +- Kształty sześciokąta i kwadratu są węzłami wycinającymi stencil. +- Sześciokąt tworzy nową maskę wycinania, a kwadrat przycina ją dalej. +- Węzeł koła jest zwykłym węzłem Pie, więc zostanie wyrenderowany z maską wycinania utworzoną przez nadrzędne węzły wycinające. -Dla tej hierarchii możliwe są cztery kombinacje normalnych i odwróconych wycinaczy. Obszar zielony oznacza część koła, która jest renderowana. Reszta jest przycinana: +W tej hierarchii możliwe są cztery kombinacje zwykłych i odwróconych węzłów wycinających. Zielony obszar oznacza część koła, która jest renderowana. Reszta jest maskowana: -![Stencil masks](images/gui-clipping/modes.png) +![Maski stencil](images/gui-clipping/modes.png) -## Ograniczenia maski wycinania +## Ograniczenia stencil -- Całkowita liczba wycinaczy maski nie może przekroczyć 256. -- Maksymalna głębokość zagnieżdżenia węzłów dzieci o typie _stencil_ wynosi 8 poziomów (tylko węzły z wycinaniem typu stencil się w to wliczają). -- Maksymalna liczba rodzeństwa węzłów maski wynosi 127. Dla każdego poziomu w dół hierarchii maski wycinania maksymalne ograniczenie jest dzielone na pół. -- Węzły odwrócone są droższe. Istnieje limit 8 węzłów wycinania z odwróceniem, a każdy z nich zmniejszy maksymalną liczbę węzłów wycinania bez odwracania na pół. -- Wycinacze renderują maskę wycinania z _geometrii_ węzła (nie tekstury). Możliwe jest odwrócenie maski, ustawiając właściwość *Inverted clipper*. +- Całkowita liczba węzłów wycinających stencil nie może przekroczyć 256. +- Maksymalna głębokość zagnieżdżenia węzłów podrzędnych typu _stencil_ wynosi 8 poziomów. (Liczą się tylko węzły z wycinaniem stencil.) +- Maksymalna liczba węzłów rodzeństwa typu stencil wynosi 127. Na każdym kolejnym poziomie hierarchii stencil limit jest dzielony na pół. +- Węzły odwrócone są droższe. Istnieje limit 8 odwróconych węzłów wycinających, a każdy z nich zmniejsza o połowę maksymalną liczbę niewywróconych węzłów wycinających. +- Węzły stencil renderują maskę stencil z _geometrii_ węzła, a nie z tekstury. Maskę można odwrócić, ustawiając właściwość *Inverted clipper*. ## Warstwy -Warstwy można wykorzystać do kontrolowania kolejności renderowania (i grupowania) węzłów. Podczas korzystania z warstw i węzłów wycinających standardowa kolejność warstw jest nadpisywana. Kolejność warstw zawsze ma pierwszeństwo przed kolejnością wycinania - jeśli przypisanie warstw jest łączone z węzłami wycinającymi, wycinanie może odbywać się poza kolejnością, jeśli węzeł nadrzędny z wycinaniem jest przypisany do wyższej warstwy niż jego dzieci. Dzieci bez przypisanej warstwy nadal będą przestrzegać hierarchii i zostaną narysowane i przycięte po rodzicu. +Warstwy można wykorzystać do kontrolowania kolejności renderowania i grupowania węzłów. Podczas używania warstw i węzłów wycinających zwykła kolejność warstw zostaje nadpisana. Kolejność warstw zawsze ma pierwszeństwo przed kolejnością wycinania - jeśli przypisanie warstw zostanie połączone z węzłami wycinającymi, wycinanie może nastąpić poza kolejnością, gdy węzeł nadrzędny z włączonym wycinaniem należy do wyższej warstwy niż jego dzieci. Dzieci bez przypisanej warstwy nadal będą respektować hierarchię i zostaną narysowane oraz przycięte po rodzicu. ::: sidenote -Węzeł wycinania i jego hierarchia zostaną narysowane jako pierwsze, jeśli mają przypisaną warstwę, a w zwykłej kolejności, jeśli nie mają przypisanej warstwy. +Węzeł wycinający i jego hierarchia zostaną narysowane jako pierwsze, jeśli mają przypisaną warstwę, a w zwykłej kolejności, jeśli warstwa nie jest przypisana. ::: -![Layers and clipping](images/gui-clipping/layers.png) +![Warstwy i wycinanie](images/gui-clipping/layers.png) -W tym przykładzie zarówno węzły wycinające "Donut BG" i "BG" korzystają z tej samej warstwy 1. Kolejność renderowania między nimi będzie zgodna z kolejnością w hierarchii, gdzie "Donut BG" zostanie narysowane przed "BG". Jednak węzeł dziecka "Donut Shadow" jest przypisany do warstwy 2, która ma wyższy porządek warstw i zostanie narysowany po obu węzłach wycinających. W tym przypadku kolejność renderowania będzie następująca: +W tym przykładzie oba węzły wycinające "`Donut BG`" i "`BG`" korzystają z tej samej warstwy 1. Kolejność renderowania między nimi będzie zgodna z kolejnością w hierarchii, w której "`Donut BG`" jest renderowany przed "`BG`". Jednak węzeł podrzędny "`Donut Shadow`" ma przypisaną warstwę 2, która ma wyższy priorytet, więc zostanie wyrenderowany po obu węzłach wycinających. W takim przypadku kolejność renderowania będzie następująca: -- Donut BG -- BG -- BG Frame -- Donut Shadow +- `Donut BG` +- `BG` +- `BG Frame` +- `Donut Shadow` -Widzisz, że obiekt "Donut Shadow" zostanie przycięty przez oba węzły wycinające ze względu na warstwę, chociaż jest tylko dzieckiem jednego z nich. +Widać tu, że obiekt `Donut Shadow` zostanie przycięty przez oba węzły wycinające z powodu warstw, mimo że jest dzieckiem tylko jednego z nich. diff --git a/docs/pl/manuals/gui-layouts.md b/docs/pl/manuals/gui-layouts.md index 87da2cbc..ec36a48b 100644 --- a/docs/pl/manuals/gui-layouts.md +++ b/docs/pl/manuals/gui-layouts.md @@ -1,21 +1,19 @@ --- -title: Układy interfejsu w Defoldzie -brief: Defold supports GUIs that automatically adapt to screen orientation changes on mobile devices. This document explains how the feature works. +title: Układy GUI w Defold +brief: Defold obsługuje GUI, które automatycznie dostosowuje się do zmian orientacji ekranu na urządzeniach mobilnych. Ten dokument wyjaśnia, jak działa ta funkcja. --- -# Układy interfejsu +# Układy -Układy interfejsu (ang. layouts) to wspierana przez Defold opcja automatycznego dostosowywania się do zmian orientacji ekranu na urządzeniach mobilnych. W tym dokumencie wyjaśniono, jak działa ta funkcjonalność. - -Defold supports GUIs that automatically adapt to screen orientation changes on mobile devices. By using this feature you can design GUIs that adapt to the orientation and aspect ratio of a range of screen sizes. It is also possible to create layouts that match particular device models. +Defold obsługuje GUI, które automatycznie dostosowuje się do zmian orientacji ekranu na urządzeniach mobilnych. Dzięki tej funkcji możesz projektować GUI dopasowujące się do orientacji i proporcji obrazu na ekranach o różnych rozmiarach. Możliwe jest też tworzenie układów dopasowanych do konkretnych modeli urządzeń. ## Tworzenie profili wyświetlania -Domyślnie, w ustawieniach *game.project*, używa się wbudowanego pliku z ustawieniami profili wyświetlania (ang. display profiles) ("builtins/render/default.display_profiles"). Domyślne profile to `"Landscape"` (1280 pikseli szerokości i 720 pikseli wysokości) i `"Portrait"` (720 pikseli szerokości i 1280 pikseli wysokości). W profilach tych nie ustawiono modeli urządzeń, dlatego pasują one do dowolnego urządzenia. +Domyślnie ustawienia w pliku *game.project* wskazują wbudowany plik ustawień profili wyświetlania ("builtins/render/default.display_profiles"). Domyślne profile to "Landscape" (1280 pikseli szerokości i 720 pikseli wysokości) oraz "Portrait" (720 pikseli szerokości i 1280 pikseli wysokości). W tych profilach nie ustawiono modeli urządzeń, więc będą pasować do dowolnego urządzenia. -Aby utworzyć nowy plik z ustawieniami profili, skopiuj istniejący z folderu "builtins" lub kliknij prawym przyciskiem myszy w odpowiednim miejscu w widoku *Assets* i wybierz New... -> Display Profiles". Nadaj nowemu plikowi odpowiednią nazwę i kliknij OK. +Aby utworzyć nowy plik profili, skopiuj istniejący z folderu builtins albo użyj right click na odpowiednim miejscu w widoku *Assets* i wybierz New... ▸ Display Profiles. Nadaj nowemu plikowi odpowiednią nazwę i kliknij Ok. -Edytor otworzy teraz nowy plik do edycji. Dodaj nowe profile, klikając + na liście *Profiles*. Dla każdego profilu dodaj zestaw "kwalifikatorów" (*qualifiers*) dla profilu: +Edytor otworzy teraz nowy plik do edycji. Dodaj nowe profile, klikając + na liście *Profiles*. Dla każdego profilu dodaj zestaw *qualifiers*: Width : Szerokość kwalifikatora w pikselach. @@ -24,77 +22,118 @@ Height : Wysokość kwalifikatora w pikselach. Device Models -: Lista modeli urządzeń oddzielonych przecinkami. Nazwa modelu urządzenia pasuje do początku nazwy modelu urządzenia. Przykład: `iPhone10` pasuje do modeli "iPhone10,\*". Nazwy modeli z przecinkami powinny być umieszczone w cudzysłowie, np. `"iPhone10,3", "iPhone10,6"` pasuje do modeli iPhone X (https://www.theiphonewiki.com/wiki/Models). Należy zauważyć, że tylko platformy Android i iOS raportują nazwę modelu urządzenia podczas wywoływania funkcji `sys.get_sys_info`. Inne platformy zwracają pusty ciąg znaków i dlatego nigdy nie wybiorą profilu wyświetlania z kwalifikatorem modelu urządzenia. +: Lista modeli urządzeń oddzielonych przecinkami. Nazwa modelu dopasowuje początek nazwy modelu urządzenia, na przykład `iPhone10` dopasuje modele "iPhone10,*". Nazwy modeli zawierające przecinki powinny być ujęte w cudzysłów, czyli `"iPhone10,3", "iPhone10,6"` dopasuje modele iPhone X (zobacz [iPhone wiki](https://www.theiphonewiki.com/wiki/Models)). Pamiętaj, że tylko platformy Android i iOS zwracają model urządzenia przy wywołaniu `sys.get_sys_info()`. Inne platformy zwracają pusty ciąg znaków, więc nigdy nie wybiorą profilu wyświetlania, który ma kwalifikator Device Models. ![New display profiles](images/gui-layouts/new_profiles.png) -Należy również określić, że silnik powinien używać nowych profili. Otwórz *game.project* i wybierz plik z profilami wyświetlania w ustawieniach *Display Profiles* w sekcji *display*. - +Musisz też wskazać, że silnik ma używać nowego pliku profili. Otwórz *game.project* i ustaw plik profili wyświetlania w opcji *Display Profiles* w sekcji *display*: ![Settings](images/gui-layouts/settings.png) -Jeśli chcesz, aby silnik automatycznie przełączał się między układami w orientacji pionowej i poziomej po obróceniu urządzenia, zaznacz opcję *Dynamic Orientation*. Silnik będzie dynamicznie wybierać pasujący układ i zmieniać wybór w razie zmiany orientacji urządzenia. +Jeśli chcesz, aby silnik automatycznie przełączał się między układami pionowymi i poziomymi po obróceniu urządzenia, zaznacz pole *Dynamic Orientation*. Silnik będzie wtedy dynamicznie wybierał pasujący układ i zmieniał go przy zmianie orientacji urządzenia. + +### Auto Layout Selection (Display Profiles) -## Układy interfejsu +W zasobie Display Profiles dostępna jest opcja "Auto Layout Selection" (domyślnie włączona). Gdy jest włączona, silnik automatycznie wybiera najlepiej pasujący układ GUI zarówno podczas tworzenia sceny, jak i przy zmianie rozmiaru okna lub ekranu. Gdy jest wyłączona, silnik nie zmienia układów automatycznie. Wtedy do ręcznego przełączania układów z poziomu skryptu GUI używa się `gui.set_layout()`. To ustawienie jest zapisane w pliku Display Profiles i wpływa na wszystkie sceny GUI. -Obecny zestaw profili wyświetlania można wykorzystać do tworzenia wariantów układów (layouts) węzłów interfejsu. Aby dodać nowy układ do sceny interfejsu, kliknij prawym przyciskiem myszy na ikonie *Layouts* w widoku *Outline* i wybierz Add ▸ Layout ▸ .... +## Układy GUI -![Add layout to scene](images/gui-layouts/add_layout.png) +Aktualny zestaw profili wyświetlania można wykorzystać do tworzenia wariantów układów dla węzłów GUI. Aby dodać nowy układ do sceny GUI, użyj right click na ikonie *Layouts* w widoku *Outline* i wybierz Add ▸ Layout ▸ ...: -Podczas edycji sceny interfejsu wszystkie węzły są edytowane w określonym układzie. Obecnie wybrany układ jest widoczny w rozwijanym menu układu sceny interfejsu w pasku narzędziowym. Jeśli nie wybrano żadnego układu, węzły są edytowane w układzie *Default*. +![Dodawanie układu do sceny](images/gui-layouts/add_layout.png) -![Layouts toolbar](images/gui-layouts/toolbar.png) +Podczas edycji sceny GUI wszystkie węzły są edytowane w ramach konkretnego układu. Aktualnie wybrany układ jest widoczny na liście rozwijanej układów sceny GUI na pasku narzędzi. Jeśli nie wybierzesz żadnego układu, węzły są edytowane w układzie *Default*. -![portrait edit](images/gui-layouts/portrait.png) +![Pasek narzędzi układów](images/gui-layouts/toolbar.png) -Każda zmiana właściwości węzła dokonana z wybranym układem, nadpisuje właściwość w odniesieniu do układu *Default*. Właściwości, które zostały nadpisane, są oznaczone kolorem niebieskim. Węzły z nadpisanymi właściwościami również są oznaczone kolorem niebieskim. Możesz kliknąć przycisk resetowania obok dowolnej nadpisanej właściwości, aby przywrócić ją do pierwotnej wartości. +![Edycja układu pionowego](images/gui-layouts/portrait.png) -![landscape edit](images/gui-layouts/landscape.png) +Każda zmiana właściwości węzła, którą wykonasz przy wybranym układzie, nadpisuje tę właściwość względem układu *Default*. Nadpisane właściwości są oznaczane na niebiesko. Węzły z nadpisanymi właściwościami również są oznaczane na niebiesko. Możesz kliknąć przycisk resetowania obok dowolnej nadpisanej właściwości, aby przywrócić jej pierwotną wartość. -Układ nie może usuwać ani tworzyć nowych węzłów, może jedynie nadpisywać właściwości. Jeśli chcesz usunąć węzeł z układu, możesz albo przenieść węzeł poza obszar ekranu, albo usunąć go za pomocą logiki skryptu. Należy także zwrócić uwagę na obecnie wybrany układ. Jeśli dodasz układ do projektu, nowy układ będzie konfigurowany zgodnie z aktualnie wybranym układem. Kopiowanie i wklejanie węzłów uwzględnia obecnie wybrany układ zarówno podczas kopiowania, jak i podczas wklejania. +![Edycja układu poziomego](images/gui-layouts/landscape.png) + +Układ nie może usuwać ani tworzyć nowych węzłów, może jedynie nadpisywać właściwości. Jeśli chcesz usunąć węzeł z układu, możesz przenieść go poza ekran albo usunąć go w logice skryptu. Zwróć też uwagę na aktualnie wybrany układ. Jeśli dodasz nowy układ do projektu, zostanie skonfigurowany zgodnie z aktualnie wybranym układem. Kopiowanie i wklejanie węzłów również uwzględnia aktualnie wybrany układ, zarówno przy kopiowaniu, jak *i* przy wklejaniu. ## Dynamiczny wybór profilu -Dynamiczny dopasowywacz układu ocenia każdy kwalifikator profilu wyświetlania według następujących reguł: +Gdy "Auto Layout Selection" jest włączone, silnik automatycznie wybiera najlepiej pasujący układ. Mechanizm dynamicznego dopasowania ocenia każdy kwalifikator profilu wyświetlania według następujących reguł: -1. Jeśli nie jest ustawiony model urządzenia albo model urządzenia jest i pasuje do profilu, obliczana jest ocena (S) dla kwalifikatora. +1. Jeśli nie ustawiono modelu urządzenia albo model urządzenia pasuje, dla kwalifikatora obliczana jest ocena (S). -2. Ocena (S) jest obliczana na podstawie powierzchni ekranu (`A`), powierzchni z kwalifikatora (`A_Q`), proporcji obrazu ekranu (`R`) i proporcji obrazu z kwalifikatora (`R_Q`). +2. Ocena (S) jest obliczana na podstawie powierzchni ekranu (`A`), powierzchni z kwalifikatora (`A_Q`), proporcji obrazu ekranu (`R`) i proporcji obrazu kwalifikatora (`R_Q`): -3. Profil z najniższą oceną jest wybierany, jeśli orientacja (landscape lub portrait) kwalifikatora pasuje do orientacji ekranu. +3. Wybierany jest profil z kwalifikatorem o najniższej ocenie, jeśli orientacja kwalifikatora (landscape lub portrait) pasuje do orientacji ekranu. -4. Jeśli nie znaleziono profilu z kwalifikatorem o tej samej orientacji, wybierany jest profil z najlepszą oceną kwalifikatora o innej orientacji. +4. Jeśli nie znaleziono profilu z kwalifikatorem o tej samej orientacji, wybierany jest profil z najlepiej ocenionym kwalifikatorem o przeciwnej orientacji. -5. Jeśli nie można wybrać żadnego profilu, stosowany jest profil awaryjny *Default*. +5. Jeśli nie da się wybrać żadnego profilu, używany jest zapasowy profil *Default*. -Ponieważ układ *Default* jest stosowany jako profil awaryjny w czasie rzeczywistym, jeśli nie ma lepszego pasującego układu, oznacza to, że jeśli dodasz układ *Landscape*, będzie to najlepsze dopasowanie dla wszystkich orientacji, dopóki nie dodasz także układu *Portrait*. +Ponieważ układ *Default* jest używany jako zapasowy w czasie działania programu, gdy nie ma lepiej dopasowanego układu, oznacza to, że jeśli dodasz układ "Landscape", będzie on najlepszym dopasowaniem dla *wszystkich* orientacji, dopóki nie dodasz także układu "Portrait". ## Komunikaty o zmianie układu -Kiedy silnik zmienia układ w wyniku obracania urządzenia, wysyłana jest wiadomość `layout_changed` do skryptów komponentów GUI, które są dotknięte zmianą. Komunikat zawiera zahaszowany identyfikator (hashed id) układu, dzięki czemu skrypt może wykonywać logikę zależnie od wybranego układu. - -When the engine switches layout as a result of device rotation, a `layout_changed` message is posted to the GUI components' scripts that are affected by the change. The message contains the hashed id of the layout so the script can perform logic depending on which layout is selected: +Gdy układ się zmienia, do skryptu komponentu GUI wysyłana jest wiadomość `layout_changed`. Dzieje się tak, gdy silnik zmienia układ automatycznie ("Auto Layout Selection" jest włączone) albo gdy skrypt wywoła `gui.set_layout()` i układ rzeczywiście się zmieni. Wiadomość zawiera haszowany identyfikator układu, dzięki czemu skrypt może wykonać logikę zależnie od wybranego układu: ```lua function on_message(self, message_id, message, sender) if message_id == hash("layout_changed") and message.id == hash("My Landscape") then - --- zmieniono układ na landscape + -- zmiana układu na poziomy elseif message_id == hash("layout_changed") and message.id == hash("My Portrait") then - -- zmieniono układ na portrait + -- zmiana układu na pionowy end end ``` -Ponadto, bieżący skrypt renderowania otrzymuje komunikat za każdym razem, gdy zmienia się okno (widok gry), a to obejmuje zmiany orientacji. +Dodatkowo aktualny skrypt renderowania otrzymuje wiadomość za każdym razem, gdy zmienia się okno (widok gry), a obejmuje to także zmiany orientacji. ```lua function on_message(self, message_id, message) if message_id == hash("window_resized") then - -- Okno zostało zmienione. message.width i message.height zawierają nowe wymiary okna. + -- Rozmiar okna się zmienił. message.width i message.height zawierają + -- nowe wymiary okna. end end ``` -Przy zmianie orientacji menedżer układu interfejsu automatycznie przeskalowuje i przemieszcza węzły GUI zgodnie z układem i właściwościami węzłów. Jednak treść gry jest renderowana w osobnym przebiegu (domyślnie) z projekcją rozciągania do bieżącego okna. Aby zmienić to zachowanie, należy dostarczyć własny zmodyfikowany skrypt renderowania lub skorzystać z [biblioteki kamer](/assets/). +Po zmianie orientacji menedżer układów GUI automatycznie przeskaluje i przemieści węzły GUI zgodnie z układem oraz właściwościami węzłów. Zawartość gry jest jednak domyślnie renderowana w osobnym przebiegu z projekcją stretch-fit do bieżącego okna. Aby zmienić to zachowanie, dostarcz własny zmodyfikowany skrypt renderowania albo skorzystaj z [biblioteki kamer](/assets/). + +## Ręczny wybór układu (Lua) + +Gdy "Auto Layout Selection" jest wyłączone w używanych Display Profiles, silnik nie będzie przełączać układów automatycznie. W takim przypadku układami zarządza się ręcznie z poziomu skryptu GUI za pomocą następujących funkcji: + +### gui.set_layout(layout) + +- Przyjmuje `string` albo `hash` (id układu). +- Zwraca wartość logiczną: `true`, jeśli układ istnieje w scenie i został zastosowany; w przeciwnym razie `false`. +- Jeśli układ istnieje w Display Profiles, aktualizuje rozdzielczość sceny do szerokości i wysokości z profilu. +- Wysyła `layout_changed`, gdy układ rzeczywiście się zmieni. + +Przykład: + +```lua +function init(self) + -- Ręcznie zastosuj układ "Portrait" + local ok = gui.set_layout("Portrait") + if not ok then + print("Układ Portrait nie został znaleziony w tej scenie") + end +end +``` + +### gui.get_layouts() + +- Zwraca tabelę mapującą każdy haszowany identyfikator układu na `vmath.vector3(width, height, 0)`. +- Dla układu domyślnego zwraca bieżącą rozdzielczość sceny. + +Przykład: + +```lua +local layouts = gui.get_layouts() +for id, size in pairs(layouts) do + print(id, size.x, size.y) +end +``` + +Uwaga: jeśli układ GUI istnieje w scenie, ale nie występuje w Display Profiles, `gui.set_layout()` nadal zastosuje nadpisania właściwości węzłów dla danego układu, ale nie zmieni rozdzielczości sceny. diff --git a/docs/pl/manuals/gui-script.md b/docs/pl/manuals/gui-script.md index 8de6f563..e518e5cd 100644 --- a/docs/pl/manuals/gui-script.md +++ b/docs/pl/manuals/gui-script.md @@ -1,59 +1,59 @@ --- -title: Skrypty GUI w Defoldzie -brief: Ta instrukcja wyjaśnia jak działają skrypty GUI w Defoldzie +title: Skrypty GUI w Defold +brief: Ta instrukcja wyjaśnia skryptowanie GUI. --- # Skrypty GUI -Aby kontrolować logikę swojego interfejsu GUI i animować węzły, używa się skryptów Lua. Skrypty GUI działają tak samo jak zwykłe skrypty obiektów gry, ale są zapisywane jako inny rodzaj pliku i mają dostęp do innej grupy funkcji: funkcji modułu `gui`. +Aby sterować logiką GUI i animować węzły, używa się skryptów Lua. Skrypty GUI działają tak samo jak zwykłe skrypty obiektów gry, ale są zapisywane jako inny typ pliku i mają dostęp do innego zestawu funkcji: funkcji modułu `gui`. ## Dodawanie skryptu do GUI -Aby dodać skrypt do GUI, najpierw stwórz plik skryptu GUI, klikając prawym przyciskiem myszy w odpowiednie miejsce w przeglądarce Zasobów i wybierając New ▸ Gui Script z menu kontekstowego. +Aby dodać skrypt do GUI, najpierw utwórz plik skryptu GUI, klikając prawym przyciskiem myszy w dowolnym miejscu w panelu *Assets* i wybierając New ▸ Gui Script z menu kontekstowego. -Edytor automatycznie otwiera nowy plik skryptu. Bazuje on na szablonie i jest wyposażony w puste funkcje cyklu życia, takie same jak skrypty obiektów gry: +Edytor automatycznie otworzy nowy plik skryptu. Powstaje on na podstawie szablonu i zawiera puste funkcje cyklu życia, tak samo jak skrypty obiektów gry: ```lua function init(self) - -- Add initialization code here - -- Remove this function if not needed + -- Dodaj tutaj kod inicjalizacji + -- Usuń tę funkcję, jeśli nie jest potrzebna end function final(self) - -- Add finalization code here - -- Remove this function if not needed + -- Dodaj tutaj kod finalizacji + -- Usuń tę funkcję, jeśli nie jest potrzebna end function update(self, dt) - -- Add update code here - -- Remove this function if not needed + -- Dodaj tutaj kod aktualizacji + -- Usuń tę funkcję, jeśli nie jest potrzebna end function on_message(self, message_id, message, sender) - -- Add message-handling code here - -- Remove this function if not needed + -- Dodaj tutaj kod obsługi wiadomości + -- Usuń tę funkcję, jeśli nie jest potrzebna end function on_input(self, action_id, action) - -- Add input-handling code here - -- Remove this function if not needed + -- Dodaj tutaj kod obsługi wejścia + -- Usuń tę funkcję, jeśli nie jest potrzebna end function on_reload(self) - -- Add input-handling code here - -- Remove this function if not needed + -- Dodaj tutaj kod obsługi ponownego wczytania + -- Usuń tę funkcję, jeśli nie jest potrzebna end ``` -Aby przypiąć skrypt do komponentu GUI, otwórz prototyp komponentu GUI (inaczej nazywane "prefabami" lub "szablonami" w innych silnikach) i wybierz korzeń (root) w *Outline*, aby wywołać Właściwości (*Properties*) GUI. Ustaw właściwość *Script* na plik skryptu. +Aby dołączyć skrypt do komponentu GUI, otwórz plik prototypu komponentu GUI, a następnie wybierz korzeń w *Outline*, aby wyświetlić *Properties* GUI. Ustaw właściwość *Script* na plik skryptu. ![Script](images/gui-script/set_script.png) -Jeśli komponent GUI został dodany do obiektu gry w dowolnym miejscu gry, skrypt zostanie teraz uruchomiony. +Jeśli komponent GUI został dodany do obiektu gry w dowolnym miejscu projektu, skrypt zacznie teraz działać. ## Przestrzeń nazw "gui" -Skrypty GUI mają dostęp do przestrzeni nazw (ang. namespace) `gui` i [wszystkich funkcji gui](/ref/gui). Przestrzeń nazw `go` dla obiektów gry nie jest dostępna dla GUI, dlatego konieczne jest oddzielenie logiki obiektów gry poprzez skrypty komponentów i komunikację między skryptami GUI a skryptami komponentów obiektów gry. Próby użycia funkcji `go` w skrypcie GUI spowodują błąd: +Skrypty GUI mają dostęp do przestrzeni nazw `gui` i [wszystkich funkcji gui](/ref/gui). Przestrzeń nazw `go` nie jest dostępna, więc logikę obiektów gry trzeba wydzielić do skryptów komponentów i komunikować się między GUI a skryptami obiektów gry. Każda próba użycia funkcji `go` spowoduje błąd: ```lua function init(self) @@ -70,9 +70,9 @@ stack traceback: ## Przesyłanie wiadomości -Dowolny komponent GUI z przypisanym skryptem ma zdolność do komunikacji z innymi obiektami w środowisku uruchomieniowym gry poprzez przesyłanie wiadomości, zachowuje się tak samo jak dowolny inny komponent skryptu. +Każdy komponent GUI z przypisanym skryptem może komunikować się z innymi obiektami w środowisku uruchomieniowym gry za pomocą przesyłania wiadomości, tak samo jak każdy inny komponent skryptu. -Możesz adresować komponent GUI tak samo, jak dowolny inny komponent skryptu: +Komponent GUI adresuje się tak samo jak każdy inny komponent skryptu: ```lua local stats = { score = 4711, stars = 3, health = 6 } @@ -83,11 +83,11 @@ msg.post("hud#gui", "set_stats", stats) ## Adresowanie węzłów -Węzły GUI mogą być manipulowane przez skrypt GUI przypisany do komponentu. Każdy węzeł musi mieć unikalne *Id*, które jest ustawiane w edytorze: +Węzłami GUI może manipulować skrypt GUI dołączony do komponentu. Każdy węzeł musi mieć unikalne *Id*, ustawiane w edytorze: ![message passing](images/gui-script/node_id.png) -*Id* pozwala skryptowi uzyskać dostęp do węzła i manipulować nim za pomocą [funkcji przestrzeni nazw gui](/ref/gui): +*Id* pozwala skryptowi pobrać odwołanie do węzła i manipulować nim za pomocą [funkcji przestrzeni nazw gui](/ref/gui): ```lua -- rozszerz pasek zdrowia o 10 jednostek @@ -99,16 +99,16 @@ gui.set_size(healthbar_node, size) ## Dynamicznie tworzone węzły -Aby utworzyć nowy węzeł w czasie rzeczywistym, masz dwie opcje. Pierwsza opcja polega na tworzeniu węzłów od podstaw, wywołując funkcje `gui.new_[type]_node()`. Funkcje te zwracają referencję do nowego węzła, którą można używać do manipulowania węzłem: +Aby utworzyć nowy węzeł w czasie działania, masz dwie opcje. Pierwsza polega na tworzeniu węzłów od podstaw przez wywołanie funkcji `gui.new_[type]_node()`. Zwracają one odwołanie do nowego węzła, którego można użyć do dalszej manipulacji: ```lua --- Utwórz nowy węzeł typu "box" +-- Utwórz nowy węzeł typu box local new_position = vmath.vector3(400, 300, 0) local new_size = vmath.vector3(450, 400, 0) local new_boxnode = gui.new_box_node(new_position, new_size) gui.set_color(new_boxnode, vmath.vector4(0.2, 0.26, 0.32, 1)) --- Utwórz nowy węzeł typu "text" +-- Utwórz nowy węzeł tekstowy local new_textnode = gui.new_text_node(new_position, "Hello!") gui.set_font(new_textnode, "sourcesans") gui.set_color(new_textnode, vmath.vector4(0.69, 0.6, 0.8, 1.0)) @@ -116,7 +116,7 @@ gui.set_color(new_textnode, vmath.vector4(0.69, 0.6, 0.8, 1.0)) ![dynamic node](images/gui-script/dynamic_nodes.png) -Alternatywnym sposobem na tworzenie nowych węzłów jest klonowanie istniejącego węzła za pomocą funkcji `gui.clone()` lub drzewa węzłów za pomocą funkcji `gui.clone_tree()`: +Drugim sposobem tworzenia nowych węzłów jest sklonowanie istniejącego węzła za pomocą funkcji `gui.clone()` lub drzewa węzłów za pomocą funkcji `gui.clone_tree()`: ```lua -- sklonuj pasek zdrowia @@ -136,16 +136,14 @@ root_position.x = root_position.x + 300 gui.set_position(new_root, root_position) ``` -## Dynamiczne identyfikatory węzłów +## Id węzłów dynamicznych -Dynamicznie tworzone węzły nie posiadają przypisanego identyfikatora. Jest to celowe. Referencje zwracane przez funkcje `gui.new_[type]_node()`, `gui.clone()` i `gui.clone_tree()` są jedyną rzeczą, która jest potrzebna do dostępu do węzłów, i powinieneś śledzić tę referencję. - -Dynamically created nodes do not have an id assigned to them. This is by design. The references that are returned from `gui.new_[type]_node()`, `gui.clone()` and `gui.clone_tree()` are the only thing necessary to be able to access the nodes and you should keep track of that reference. +Dynamicznie tworzone węzły nie mają przypisanego id. Tak właśnie ma być. Odwołania zwracane przez funkcje `gui.new_[type]_node()`, `gui.clone()` i `gui.clone_tree()` są jedyną potrzebną rzeczą, aby uzyskać dostęp do węzłów, więc należy przechowywać to odwołanie. ```lua -- Dodaj węzeł tekstowy local new_textnode = gui.new_text_node(vmath.vector3(100, 100, 0), "Hello!") --- "new_textnode" zawiera referencję do węzła. --- Węzeł nie ma identyfikatora, i to jest w porządku. Nie ma powodu, by używać --- funkcji `gui.get_node()`, gdy mamy już referencję. +-- "new_textnode" zawiera odwołanie do węzła. +-- Węzeł nie ma id i to jest w porządku. Nie ma powodu, aby wywoływać +-- gui.get_node(), skoro odwołanie mamy już pod ręką. ``` diff --git a/docs/pl/manuals/gui-template.md b/docs/pl/manuals/gui-template.md index 674f7a3e..535eb129 100644 --- a/docs/pl/manuals/gui-template.md +++ b/docs/pl/manuals/gui-template.md @@ -1,56 +1,56 @@ --- -title: Szablony GUI w Defoldzie -brief: Ta instrukcja wyjaśnia, jak działają szablony GUI. +title: Podręcznik szablonów GUI +brief: Ta instrukcja wyjaśnia system szablonów GUI w Defold, który służy do tworzenia wielokrotnego użytku wizualnych komponentów GUI opartych na wspólnych szablonach lub "prefabach". --- # Węzły szablonów GUI -Węzły szablonów (ang. template nodes) GUI zapewniają potężny mechanizm tworzenia wielokrotnego użytku komponentów GUI na podstawie wspólnych "szablonów" lub "prefabrykatów". Ten podręcznik wyjaśnia tę funkcję i jej użycie. +Węzły szablonów GUI (ang. GUI template nodes) zapewniają wygodny mechanizm tworzenia wielokrotnego użytku komponentów GUI opartych na wspólnych szablonach lub "prefabach". Ta instrukcja wyjaśnia tę funkcję i pokazuje, jak z niej korzystać. -Szablon GUI to scena GUI, która jest tworzona, węzeł po węźle, w innej scenie GUI. Wartości właściwości węzłów oryginalnych szablonów można wówczas zastępować. +Szablon GUI to scena GUI, która jest instancjonowana, węzeł po węźle, w innej scenie GUI. Każdą wartość właściwości w oryginalnych węzłach szablonu można później nadpisać. ## Tworzenie szablonu -Szablon GUI to zwykła scena GUI, więc tworzy się go tak samo jak każdą inną scenę GUI. Kliknij prawym przyciskiem myszy w odpowiednim miejscu w panelu Assets i wybierz New... ▸ Gui. +Szablon GUI to zwykła scena GUI, więc tworzy się go tak samo jak każdą inną scenę GUI. Right click w wybranym miejscu w panelu *Assets* i wybierz New... ▸ Gui. ![Create template](images/gui-templates/create.png) -Utwórz szablon i zapisz go. Należy zauważyć, że węzły instancji tego szablonu zostaną umieszczone względem położenia początkowego, dlatego dobrym pomysłem jest utworzenie szablonu w pozycji 0, 0, 0. +Utwórz szablon i zapisz go. Pamiętaj, że węzły instancji zostaną umieszczone względem punktu początkowego, więc najlepiej utworzyć szablon w pozycji 0, 0, 0. ## Tworzenie instancji na podstawie szablonu -Możesz tworzyć dowolną liczbę instancji opartych na jednej instancji. Utwórz lub otwórz scenę GUI, w której chcesz umieścić szablon, a następnie kliknij prawym przyciskiem myszy sekcję *Nodes* w widoku *Outline* i wybierz Add ▸ Template. +Możesz utworzyć dowolną liczbę instancji na podstawie szablonu. Utwórz lub otwórz scenę GUI, w której chcesz umieścić szablon, a następnie right click sekcję *Nodes* w widoku *Outline* i wybierz Add ▸ Template. ![Create instance](images/gui-templates/create_instance.png) Ustaw właściwość *Template* na plik sceny GUI szablonu. -Możesz dodać dowolną liczbę instancji szablonów, a dla każdej instancji można zastępować właściwości każdego węzła i zmieniać pozycję węzła instancji, kolorowanie, rozmiar, teksturę itp. +Możesz dodać dowolną liczbę instancji szablonu, a dla każdej z nich nadpisywać właściwości poszczególnych węzłów oraz zmieniać pozycję węzła instancji, kolor, rozmiar, teksturę i tak dalej. ![Instances](images/gui-templates/instances.png) -Każda zmieniona właściwość jest oznaczona kolorem niebieskim w edytorze. Naciśnij przycisk resetowania przy właściwości, aby ustawić jej wartość na wartość z szablonu: +Każda zmieniona właściwość jest oznaczana na niebiesko w edytorze. Naciśnij przycisk resetowania obok właściwości, aby przywrócić wartość z szablonu: ![Properties](images/gui-templates/properties.png) -Każdy węzeł, który ma zmienione właściwości, jest również kolorowany na niebiesko w widoku *Outline*: +Każdy węzeł, który ma nadpisane właściwości, jest również oznaczony na niebiesko w widoku *Outline*: ![Outline](images/gui-templates/outline.png) -Instancja szablonu jest wylistowana jako składana pozycja w widoku *Outline*. Jednak należy zauważyć, że ten element w widoku *nie jest węzłem*. Instancja szablonu nie istnieje także w czasie wykonywania, ale wszystkie węzły, które są częścią instancji, istnieją. +Instancja szablonu jest widoczna jako zwijany element w widoku *Outline*. Warto jednak pamiętać, że ten element w *Outline* nie jest węzłem. Sama instancja szablonu nie istnieje też w czasie działania programu, ale istnieją wszystkie węzły należące do tej instancji. -Węzły, które są częścią instancji szablonu, są automatycznie nazwane przyrostkiem i ukośnikiem (`"/"`) do ich *Id*. Przyrostek ten to *Id* ustawione w instancji szablonu. +Węzły należące do instancji szablonu są automatycznie nazywane z prefiksem i ukośnikiem (`"/"`) dołączonym do ich *Id*. Prefiksem jest *Id* ustawione w instancji szablonu. ## Modyfikowanie szablonów w czasie działania programu -Skrypty, które manipulują lub sprawdzają węzły dodane za pomocą szablonów, muszą uwzględniać tylko nazwy węzłów instancji i uwzględniać *Id* instancji szablonu jako prefiks nazwy węzła: +Skrypty, które manipulują węzłami dodanymi za pomocą mechanizmu szablonów lub je odczytują, muszą uwzględniać nazewnictwo węzłów instancji i dodawać *Id* instancji szablonu jako prefiks nazwy węzła: ```lua if gui.pick_node(gui.get_node("button_1/button"), x, y) then - -- Do something... + -- Wykonaj jakieś działanie... end ``` -Nie ma węzła odpowiadającego samej instancji szablonu. Jeśli potrzebujesz węzła głównego dla instancji, dodaj go do szablonu. +Nie istnieje osobny węzeł odpowiadający samej instancji szablonu. Jeśli potrzebujesz węzła głównego dla instancji, dodaj go do szablonu. -Jeśli skrypt jest powiązany ze sceną GUI szablonu, skrypt ten nie jest częścią drzewa węzłów instancji. Możesz dołączyć jeden pojedynczy skrypt do każdej sceny GUI, więc twoja logika skryptu musi znajdować się na scenie GUI, na której instancjonujesz swoje szablony. +Jeśli skrypt jest powiązany ze sceną GUI szablonu, nie należy on do drzewa węzłów instancji. Do każdej sceny GUI możesz dołączyć tylko jeden skrypt, więc logika skryptu musi znajdować się w scenie GUI, w której instancjonujesz szablony. diff --git a/docs/pl/manuals/gui-text.md b/docs/pl/manuals/gui-text.md index 17f9b75d..86998b8c 100644 --- a/docs/pl/manuals/gui-text.md +++ b/docs/pl/manuals/gui-text.md @@ -1,51 +1,51 @@ --- -title: Węzły tekstowe - text w Defoldzie. -brief: Ta instrukcja wyjaśnia jak używać węzłów typu text. +title: Węzły tekstowe GUI Defold +brief: Ta instrukcja opisuje, jak dodawać tekst do scen GUI. --- -# Węzeł GUI typu text +# Węzły tekstowe GUI -Defold obsługuje konkretny rodzaj węzła GUI, który umożliwia renderowanie tekstu w scenach GUI. Każdy zasób fontu dodany do projektu może być używany do renderowania węzłów tekstu. +Defold obsługuje specjalny typ węzła GUI, który pozwala renderować tekst w scenie GUI. Każdy zasób fontu dodany do projektu może być użyty do renderowania węzłów tekstowych. ## Dodawanie węzłów tekstowych -Fonty, które chcesz używać w węzłach tekstowych GUI, muszą zostać dodane do komponentu GUI. Kliknij prawym przyciskiem myszy na folder *Fonts*, użyj górnego menu GUI lub naciśnij odpowiedni skrót klawiaturowy. +Fonty, których chcesz używać we węzłach tekstowych GUI, muszą zostać dodane do komponentu GUI. Kliknij prawym przyciskiem myszy folder *Fonts*, użyj górnego menu GUI albo naciśnij odpowiedni skrót klawiaturowy. ![Fonts](images/gui-text/fonts.png) -Węzły tekstowe posiadają zestaw specjalnych właściwości: +Węzły tekstowe mają zestaw specjalnych właściwości: *Font* -: Każdy węzeł tekstowy, który tworzysz, musi mieć ustawioną właściwość Font. +: Każdy tworzony przez ciebie węzeł tekstowy musi mieć ustawioną właściwość *Font*. *Text* : Ta właściwość zawiera wyświetlany tekst. *Line Break* -: Wyrównanie tekstu odpowiada ustawieniom punktu obrotu (ang. pivot setting), a ustawienie tej właściwości pozwala na przepływ tekstu na kilku liniach. Szerokość węzła określa, jak tekst się zawija. +: Wyrównanie tekstu zależy od ustawienia pivot, a włączenie tej właściwości pozwala tekstowi łamać się na kilka linii. Szerokość węzła określa miejsce zawijania tekstu. ## Wyrównanie -Ustawiając punkt obrotu węzła, możesz zmienić tryb wyrównywania tekstu (ang. alignment mode). +Ustawiając pivot węzła, możesz zmienić tryb wyrównania tekstu. *Center* -: Jeśli punkt obrotu jest ustawiony na `Center`, `North` lub `South`, tekst jest wyrównywany do środka. +: Jeśli pivot jest ustawiony na `Center`, `North` lub `South`, tekst jest wyrównany do środka. *Left* -: Jeśli punkt obrotu jest ustawiony na dowolny z trybów `West`, tekst jest wyrównywany do lewej. +: Jeśli pivot jest ustawiony na dowolny z trybów `West`, tekst jest wyrównany do lewej. *Right* -: Jeśli punkt obrotu jest ustawiony na dowolny z trybów `East`, tekst jest wyrównywany do prawej. +: Jeśli pivot jest ustawiony na dowolny z trybów `East`, tekst jest wyrównany do prawej. ![Text alignment](images/gui-text/align.png) -## Modyfikowanie węzłów tekstowych w czasie działania programu +## Modyfikowanie węzłów tekstowych w czasie działania -Węzły tekstowe reagują na ogólne funkcje manipulacji węzłami do ustawiania rozmiaru, punktu obrotu, koloru i innych. Istnieje kilka funkcji tylko dla węzłów tekstowych: +Węzły tekstowe reagują na ogólne funkcje manipulowania węzłami, które ustawiają rozmiar, pivot, kolor i inne właściwości. Istnieje też kilka funkcji przeznaczonych wyłącznie dla węzłów tekstowych: -* Aby zmienić czcionkę węzła tekstowego, użyj funkcji [`gui.set_font()`](/ref/gui/#gui.set_font). -* Aby zmienić zachowanie podziału linii węzła tekstowego, użyj funkcji [`gui.set_line_break()`](/ref/gui/#gui.set_line_break). -* Aby zmienić zawartość węzła tekstowego, użyj funkcji [`gui.set_text()`](/ref/gui/#gui.set_text). +* Aby zmienić font węzła tekstowego, użyj funkcji [`gui.set_font()`](/ref/gui/#gui.set_font). +* Aby zmienić zachowanie łamania linii węzła tekstowego, użyj funkcji [`gui.set_line_break()`](/ref/gui/#gui.set_line_break). +* Aby zmienić treść węzła tekstowego, użyj funkcji [`gui.set_text()`](/ref/gui/#gui.set_text). ```lua function on_message(self, message_id, message, sender) @@ -55,4 +55,3 @@ function on_message(self, message_id, message, sender) end end ``` - diff --git a/docs/pl/manuals/gui.md b/docs/pl/manuals/gui.md index 0cddc6bb..2d20127c 100644 --- a/docs/pl/manuals/gui.md +++ b/docs/pl/manuals/gui.md @@ -1,286 +1,364 @@ --- -title: Sceny GUI w Defoldzie -brief: Ta instrukcja omawia edytor GUI w Defold, różne typy węzłów GUI oraz skrypty GUI. +title: Sceny GUI w silniku Defold +brief: Ta instrukcja omawia edytor GUI w silniku Defold, różne typy węzłów GUI oraz skrypty GUI. --- # GUI -GUI - Graphical User Interface, czyli graficzny interfejs użytkownika dostarcza elementów, które są w grze wyświetlana zazwyczaj nad światem gry. Defold dostarcza niestandardowy edytor GUI i potężne możliwości skryptowe, które są specjalnie dostosowane do budowy i implementacji interfejsów użytkownika. +Silnik Defold udostępnia własny edytor GUI oraz rozbudowane możliwości skryptowe, które są specjalnie dopasowane do tworzenia i implementowania interfejsów użytkownika. -Graficzny interfejs użytkownika w Defoldzie to komponent, który tworzysz i przypisujesz do obiektu gry, umieszczając go w kolekcji. Ten komponent ma następujące właściwości: +Graficzny interfejs użytkownika w Defold to komponent, który tworzysz, dołączasz do obiektu gry i umieszczasz w kolekcji. Taki komponent ma następujące właściwości: -* Posiada proste, ale potężne funkcje układu (layout), które pozwalają na renderowanie interfejsu użytkownika niezależnie od rozdzielczości i proporcji obrazu. -* Może mieć dołączoną logikę za pomocą skryptu GUI. -* Jest (domyślnie) renderowany na wierzchu innych treści, niezależnie od widoku kamery, więc nawet jeśli masz ruchomą kamerę, twoje elementy interfejsu GUI pozostaną na ekranie. Zachowanie renderowania można zmienić. -* Komponenty GUI są renderowane niezależnie od widoku gry. Dlatego nie są umieszczane w określonym miejscu w edytorze kolekcji, ani nie mają reprezentacji wizualnej w edytorze kolekcji. Komponenty GUI muszą znajdować się w obiekcie gry, który ma swoje miejsce w kolekcji. Zmiana tego miejsca nie ma wpływu na GUI. +* Ma proste, ale potężne funkcje układu, które pozwalają renderować interfejs użytkownika niezależnie od rozdzielczości i proporcji obrazu. +* Można do niego dołączyć logikę za pomocą skryptu GUI. +* Domyślnie jest renderowany nad inną zawartością, niezależnie od widoku kamery, więc nawet przy ruchomej kamerze elementy GUI pozostaną na ekranie. To zachowanie renderowania można zmienić. + +Komponenty GUI są renderowane niezależnie od widoku gry. Z tego powodu nie są umieszczane w konkretnym miejscu w edytorze kolekcji ani nie mają tam reprezentacji wizualnej. Muszą jednak znajdować się w obiekcie gry, który ma swoje miejsce w kolekcji. Zmiana tego położenia nie ma wpływu na GUI. ## Tworzenie komponentu GUI -Komponenty GUI są tworzone na podstawie pliku prototypu sceny GUI (nazywanego również "prefabem", "szablonem" lub "blueprintem" w innych silnikach). Aby utworzyć nowy komponent GUI, kliknij prawym przyciskiem myszy w panelu *Assets* i wybierz New ▸ Gui. Wprowadź nazwę nowego pliku GUI i naciśnij OK. +Komponenty GUI tworzy się z pliku prototypu sceny GUI, znanego też jako "prefab" lub "blueprint" w innych silnikach. Aby utworzyć nowy komponent GUI, kliknij prawym przyciskiem myszy w panelu *Assets* i wybierz New ▸ Gui. Wpisz nazwę nowego pliku GUI i naciśnij OK. + +![Nowy plik GUI](images/gui/new_gui_file.png) -![New gui file](images/gui/new_gui_file.png) +Silnik Defold automatycznie otworzy teraz plik w edytorze sceny GUI. -Teraz Defold automatycznie otwiera plik w edytorze sceny GUI. +![Nowe GUI](images/gui/new_gui.png) -![New gui](images/gui/new_gui.png) +W panelu *Outline* widać całą zawartość GUI: listę węzłów oraz wszystkie zależności (patrz niżej). -W panelu *Outline* znajdziesz wszystkie elementy GUI: listę węzłów (nodes) i wszelkie zależności (patrz niżej). +Centralny obszar edycji pokazuje GUI. Pasek narzędzi w prawym górnym rogu obszaru edycji zawiera narzędzia *Move*, *Rotate* i *Scale* oraz selektor [layout](/manuals/gui-layouts). -Centralny obszar edycji pokazuje GUI. W pasku narzędziowym w prawym górnym rogu obszaru edycji znajdują się narzędzia *Move*, *Rotate* i *Scale* (odpowiednio Przesuń, Obróć i Skaluj), a także selektor układu [layout](/manuals/gui-layouts). +![pasek narzędzi](images/gui/toolbar.png) -![toolbar](images/gui/toolbar.png) +Biały prostokąt pokazuje granice aktualnie wybranego layoutu, o domyślnej szerokości i wysokości ekranu ustawionej w ustawieniach projektu. -Biały prostokąt pokazuje obszar wybranego layoutu, o domyślnej szerokości i wysokości ekranu ustawionej w ustawieniach projektu. +## Właściwości GUI -Wybierając węzeł "Gui" w panelu *Outline*, zostaną wyświetlone *Properties* komponentu GUI: +Wybranie głównego węzła "Gui" w panelu *Outline* pokazuje *Properties* komponentu GUI: -Script +*Script* : Skrypt GUI przypisany do tego komponentu GUI. -Material -: Materiał używany podczas renderowania tego GUI. +*Material* +: Materiał używany podczas renderowania tego GUI. Zwróć uwagę, że z panelu Outline można też dodać do Gui kilka materiałów i przypisać je do poszczególnych węzłów. + +*Adjust Reference* +: Określa, jak ma być obliczany *Adjust Mode* każdego węzła: -Adjust Reference -: Dostosowanie odniesienia - kontroluje, jak powinien być obliczany Tryb dostosowania (*Adjust Mode*) każdego węzła: + - `Per Node` dostosowuje każdy węzeł względem dostosowanego rozmiaru węzła nadrzędnego albo przeskalowanego ekranu. + - `Disable` wyłącza tryb dostosowania węzła. Wymusza to zachowanie przez wszystkie węzły ustawionego rozmiaru. - - `Per Node` - dostosowuje każdy węzeł do dostosowanego rozmiaru węzła nadrzędnego lub zmienionego rozmiaru ekranu. - - `Disable` - wyłącza tryb dostosowywania węzła. To wymusza, aby wszystkie węzły zachowały swój ustawiony rozmiar. +*Current Nodes* +: Liczba węzłów aktualnie używanych w tym GUI. -Max Nodes +*Max Nodes* : Maksymalna liczba węzłów dla tego GUI. +*Max Dynamic Textures* +: Maksymalna liczba tekstur, które można utworzyć za pomocą [`gui.new_texture()`](/ref/stable/gui/#gui.new_texture:texture_id-width-height-type-buffer-flip). + +## Manipulacja w czasie działania + +W czasie działania można manipulować właściwościami GUI ze skryptu komponentu, korzystając z `go.get()` i `go.set()`: + +Fonty +: Pobieranie lub ustawianie fontu używanego w GUI. + +![get_set_font](images/gui/get_set_font.png) + +```lua +go.property("mybigfont", resource.font("/assets/mybig.font")) + +function init(self) + -- pobierz plik fontu aktualnie przypisany do fontu o id 'default' + print(go.get("#gui", "fonts", { key = "default" })) -- /builtins/fonts/default.font + + -- ustaw font o id 'default' na plik fontu przypisany do właściwości zasobu 'mybigfont' + go.set("#gui", "fonts", self.mybigfont, { key = "default" }) + + -- pobierz nowy plik fontu przypisany do fontu o id 'default' + print(go.get("#gui", "fonts", { key = "default" })) -- /assets/mybig.font +end +``` + +Materiały +: Pobieranie lub ustawianie materiału używanego w GUI. + +![get_set_material](images/gui/get_set_material.png) + +```lua +go.property("myeffect", resource.material("/assets/myeffect.material")) + +function init(self) + -- pobierz plik materiału aktualnie przypisany do materiału o id 'effect' + print(go.get("#gui", "materials", { key = "effect" })) -- /effect.material + + -- ustaw materiał o id 'effect' na plik materiału przypisany do właściwości zasobu 'myeffect' + go.set("#gui", "materials", self.myeffect, { key = "effect" }) + + -- pobierz nowy plik materiału przypisany do materiału o id 'effect' + print(go.get("#gui", "materials", { key = "effect" })) -- /assets/myeffect.material +end +``` + +Tekstury +: Pobieranie lub ustawianie tekstury (atlasu) używanej w GUI. + +![get_set_texture](images/gui/get_set_texture.png) + +```lua +go.property("mytheme", resource.atlas("/assets/mytheme.atlas")) + +function init(self) + -- pobierz plik tekstury aktualnie przypisany do tekstury o id 'theme' + print(go.get("#gui", "textures", { key = "theme" })) -- /theme.atlas + + -- ustaw teksturę o id 'theme' na plik tekstury przypisany do właściwości zasobu 'mytheme' + go.set("#gui", "textures", self.mytheme, { key = "theme" }) + + -- pobierz nowy plik tekstury przypisany do tekstury o id 'theme' + print(go.get("#gui", "textures", { key = "theme" })) -- /assets/mytheme.atlas +end +``` + ## Zależności -Drzewo zasobów w grze Defold jest statyczne, więc wszelkie zależności, które potrzebujesz dla swoich węzłów GUI, muszą być dodane do komponentu. W panelu *Outline* grupuje się wszystkie zależności według typu w "folderach": +Drzewo zasobów w grze Defold jest statyczne, więc wszystkie zależności potrzebne węzłom GUI trzeba dodać do komponentu. *Outline* grupuje wszystkie zależności według typu w "folderach": ![dependencies](images/gui/dependencies.png) -Aby dodać nową zależność, kliknij prawym przyciskiem myszy root "Gui" w panelu *Outline*, a następnie wybierz Add ▸ [typ] z kontekstowego menu. +Aby dodać nową zależność, przeciągnij ją z panelu *Asset* do widoku edytora. + +Alternatywnie, kliknij prawym przyciskiem myszy główny węzeł "Gui" w panelu *Outline*, a następnie wybierz Add ▸ [type] z menu kontekstowego. -Możesz także kliknąć prawym przyciskiem myszy na ikonie folderu dla typu, który chcesz dodać, i wybrać Add ▸ [typ]. +Możesz też kliknąć prawym przyciskiem myszy ikonę folderu dla typu, który chcesz dodać, i wybrać Add ▸ [type]. ## Typy węzłów -Komponent GUI jest tworzony z zestawu węzłów (nodes). Węzły to proste elementy. Mogą być przesuwane (przesuwane, skalowane i obracane) oraz uporządkowane w hierarchi rodzic-dziecko zarówno w edytorze, jak i w trakcie działania skryptu. Istnieją następujące typy węzłów: +Komponent GUI składa się z zestawu węzłów. Węzły są prostymi elementami. Można je przemieszczać, skalować i obracać oraz układać w hierarchie rodzic-dziecko zarówno w edytorze, jak i w czasie działania, korzystając ze skryptów. Dostępne są następujące typy węzłów: Box node : ![box node](images/icons/gui-box-node.png){.left} - Węzeł prostokątny z jednym kolorem, teksturą lub animacją typu flip-book. Zobacz [dokumentację węzła prostokątnego](/manuals/gui-box). + Prostokątny węzeł z pojedynczym kolorem, teksturą albo animacją flip-book. Szczegóły znajdziesz w [dokumentacji węzła Box](/manuals/gui-box).
Text node : ![text node](images/icons/gui-text-node.png){.left} - Wyświetla tekst. Zobacz [dokumentację węzła tekstowego](/manuals/gui-text) for details. + Wyświetla tekst. Szczegóły znajdziesz w [dokumentacji węzła Text](/manuals/gui-text).
Pie node : ![pie node](images/icons/gui-pie-node.png){.left} - Węzeł okrągły lub eliptyczny, który może być częściowo wypełniony (jak pierścień) lub odwrócony. Zobacz [dokumentację węzła pierścienia](/manuals/gui-pie). + Okrągły lub eliptyczny węzeł, który można częściowo wypełnić albo odwrócić. Szczegóły znajdziesz w [dokumentacji węzła Pie](/manuals/gui-pie).
Template node : ![template node](images/icons/gui.png){.left} - Szablony służą do tworzenia instancji na podstawie innych plików sceny GUI. Zobacz [dokumentację węzła szablonu](/manuals/gui-template). + Szablony służą do tworzenia instancji na podstawie innych plików scen GUI. Szczegóły znajdziesz w [dokumentacji węzła Template](/manuals/gui-template).
ParticleFX node : ![particlefx node](images/icons/particlefx.png){.left} - Odtwarza efekt cząsteczkowy. Zobacz [dokumentację węzła ParticleFX](/manuals/gui-particlefx). + Odtwarza efekt cząsteczkowy. Szczegóły znajdziesz w [dokumentacji węzła ParticleFX](/manuals/gui-particlefx).
-Aby dodać węzły, kliknij prawym przyciskiem myszy na folderze *Nodes* i wybierz Add ▸, a następnie Box, Text, Pie, Template lub ParticleFx. +Węzły można dodawać, klikając prawym przyciskiem myszy folder *Nodes* i wybierając Add ▸, a potem Box, Text, Pie, Template lub ParticleFx. ![Add nodes](images/gui/add_node.png) -Możesz także nacisnąć A i wybrać typ, który chcesz dodać do GUI. +Możesz też nacisnąć A i wybrać typ, który chcesz dodać do GUI. ## Właściwości węzłów -Każdy węzeł ma szeroki zestaw właściwości (properties), które kontrolują jego wygląd: +Każdy węzeł ma rozbudowany zestaw właściwości, które kontrolują jego wygląd: Id -: Identyfikator węzła. Ta nazwa musi być unikalna w ramach sceny GUI. +: Identyfikator węzła. Ta nazwa musi być unikalna w obrębie sceny GUI. Position, Rotation and Scale -: Kontrolują położenie, orientację i skalę węzła. Możesz użyć narzędzi *Move*, *Rotate* i *Scale* (odpowiednio Przesuń, Obróć i Skaluj), aby zmienić te wartości. Wartości można animować za pomocą skryptu ([dowiedz się więcej](/manuals/property-animation)). +: Określają położenie, orientację i skalowanie węzła. Możesz użyć narzędzi *Move*, *Rotate* i *Scale*, aby zmienić te wartości. Wartości można animować ze skryptu ([dowiedz się więcej](/manuals/property-animation)). -Rozmiar (węzły box, text i pie) -: Rozmiar węzła jest domyślnie automatyczny, ale ustawiając *Size Mode* na `Manual`, możesz zmienić wartość. Rozmiar określa granice węzła i jest używany do wykrywania interakcji z myszą. Tę wartość można animować za pomocą skryptu ([dowiedz się więcej](/manuals/property-animation)). +Size (box, text and pie nodes) +: Rozmiar węzła jest domyślnie automatyczny, ale ustawiając *Size Mode* na `Manual`, możesz go zmienić. Rozmiar definiuje granice węzła i jest używany przy sprawdzaniu trafień wejścia. Tę wartość można animować ze skryptu ([dowiedz się więcej](/manuals/property-animation)). -Size Mode (węzły box i pie) -: Jeśli jest ustawiony na `Automatic`, edytor ustawia rozmiar węzła. Jeśli jest ustawiony na `Manual`, możesz samodzielnie ustawić rozmiar. +Size Mode (box and pie nodes) +: Jeśli ustawiono `Automatic`, edytor nada węzłowi rozmiar. Jeśli ustawiono `Manual`, możesz ustawić rozmiar samodzielnie. Enabled -: Jeśli nie jest zaznaczone, węzeł nie jest renderowany, nie jest animowany i nie można go zaznaczyć za pomocą `gui.pick_node()`. Użyj `gui.set_enabled()` i `gui.is_enabled()` do zmiany w kodzie i sprawdzenia tej właściwości. +: Jeśli pole jest odznaczone, węzeł nie jest renderowany, nie jest animowany i nie można go wskazać za pomocą `gui.pick_node()`. Użyj `gui.set_enabled()` i `gui.is_enabled()`, aby programowo zmieniać i sprawdzać tę właściwość. Visible -: Jeśli nie jest zaznaczone, węzeł nie jest renderowany, ale wciąż może być animowany i można go zaznaczyć za pomocą `gui.pick_node()`. Użyj `gui.set_visible()` i `gui.get_visible()` do zmiany w kodzie i sprawdzenia tej właściwości. +: Jeśli pole jest odznaczone, węzeł nie jest renderowany, ale nadal można go animować i wskazywać za pomocą `gui.pick_node()`. Użyj `gui.set_visible()` i `gui.get_visible()`, aby programowo zmieniać i sprawdzać tę właściwość. -Text (węzły text) -: Tekst do wyświetlenia na węźle. +Text (text nodes) +: Tekst wyświetlany na węźle. -Line Break (węzły text) -: Ustaw do zawijania tekstu zgodnie z szerokością węzła. +Line Break (text nodes) +: Ustaw, aby tekst zawijał się zgodnie z szerokością węzła. -Font (węzły text) -: Font do użycia podczas renderowania tekstu. +Font (text nodes) +: Font używany do renderowania tekstu. -Texture (węzły box i pie) -: Tekstura do narysowania na węźle. Jest to odniesienie do obrazu lub animacji w atlasie lub źródle kafelków. +Texture (box and pie nodes) +: Tekstura rysowana na węźle. To odwołanie do obrazu albo animacji w atlasie lub źródle kafelków. -Slice 9 (węzły box) -: Ustaw, aby zachować rozmiar pikseli tekstury węzła wokół krawędzi i na rogach, gdy węzeł ma zmieniany rozmiar. Zobacz szczegóły w [dokumentacji węzła prostokątnego](/manuals/gui-box). +Material (box, pie nodes, text and particlefx nodes) +: Materiał używany do rysowania węzła. Może to być materiał dodany do sekcji Materials w Outline albo pusty wybór, który użyje domyślnego materiału przypisanego do komponentu GUI. -Inner Radius (węzły pie) -: Wewnętrzny promień węzła, wyrażony wzdłuż osi X. Zobacz [dokumentację węzła pierścienia](/manuals/gui-pie). +Slice 9 (box nodes) +: Ustawia zachowanie tak, aby przy zmianie rozmiaru węzła zachować rozmiar pikseli tekstury wokół krawędzi. Szczegóły znajdziesz w [dokumentacji węzła Box](/manuals/gui-box). -Outer Bounds(węzły pie) -: Kontroluje zachowanie zewnętrznych granic. Zobacz [dokumentację węzła pierścienia](/manuals/gui-pie). +Inner Radius (pie nodes) +: Wewnętrzny promień węzła, wyrażony wzdłuż osi X. Szczegóły znajdziesz w [dokumentacji węzła Pie](/manuals/gui-pie). -Perimeter Vertices (węzły pie) -: Liczba segmentów, które zostaną użyte do zbudowania kształtu. Zobacz [dokumentację węzła pierścienia](/manuals/gui-pie). +Outer Bounds (pie nodes) +: Kontroluje zachowanie zewnętrznych granic. Szczegóły znajdziesz w [dokumentacji węzła Pie](/manuals/gui-pie). -Pie Fill Angle (węzły pie) -: Kąt wypełnienia - ile z pierścienia powinno być wypełnione. Zobacz[dokumentację węzła pierścienia](/manuals/gui-pie). +Perimeter Vertices (pie nodes) +: Liczba segmentów użytych do zbudowania kształtu. Szczegóły znajdziesz w [dokumentacji węzła Pie](/manuals/gui-pie). -Template (węzły template) -: Plik sceny GUI do użycia jako szablon na węźle. Zobacz [dokumentację węzła szablonu](/manuals/gui-template). +Pie Fill Angle (pie nodes) +: Określa, jak duża część pie ma być wypełniona. Szczegóły znajdziesz w [dokumentacji węzła Pie](/manuals/gui-pie). -ParticleFX (węzły ParticleFX) -: Efekt cząsteczkowy do użycia na węźle. Zobacz [dokumentację węzła ParticleFX](/manuals/gui-particlefx). +Template (template nodes) +: Plik sceny GUI używany jako szablon dla węzła. Szczegóły znajdziesz w [dokumentacji węzła Template](/manuals/gui-template). + +ParticleFX (particlefx nodes) +: Efekt cząsteczkowy używany w tym węźle. Szczegóły znajdziesz w [dokumentacji węzła ParticleFX](/manuals/gui-particlefx). Color -: Kolor węzła. Jeśli węzeł jest tekstury, kolor zmienia odcień tekstury. Kolor można animować za pomocą skryptu (dowiedz się więcej). +: Kolor węzła. Jeśli węzeł ma teksturę, kolor nadaje jej odcień. Kolor można animować ze skryptu ([dowiedz się więcej](/manuals/property-animation)). Alpha -: Przejrzystość węzła. Wartość alfa może być animowana za pomocą skryptu ([dowiedz się więcej](/manuals/property-animation)). +: Przezroczystość węzła. Wartość alfa może być animowana ze skryptu ([dowiedz się więcej](/manuals/property-animation)). Inherit Alpha -: Zaznaczenie tego pola sprawia, że węzeł dziedziczy wartość alfy węzła nadrzędnego. Wartość alfy węzła jest następnie mnożona przez wartość alfy nadrzędnego węzła. +: Zaznaczenie tego pola sprawia, że węzeł dziedziczy wartość alfa węzła nadrzędnego. Wartość alfa węzła jest wtedy mnożona przez wartość alfa rodzica. -Leading (węzły text) -: Skalująca liczba dla rozstawu międzywierszowego. Wartość `0` oznacza brak rozstawu międzywierszowego. `1` (domyślnie) to normalny rozstaw międzywierszowy. +Leading (text nodes) +: Skaluje odstęp między wierszami. Wartość `0` oznacza brak odstępu między wierszami. `1` (domyślna) oznacza normalny odstęp między wierszami. -Tracking (węzły text) -: Skalująca liczba dla odstępu między literami. Domyślnie wynosi `0`. +Tracking (text nodes) +: Skaluje odstęp między literami. Domyślnie wynosi 0. Layer -: Przypisanie warstwy węzłowi zastępuje normalny porządek rysowania i zamiast tego renderowanie podąża za porządkiem warstwy. Poniżej znajdziesz szczegóły. +: Przypisanie warstwy do węzła nadpisuje zwykłą kolejność rysowania i zamiast niej stosuje kolejność warstw. Szczegóły poniżej. Blend mode -: Tryb mieszania kontroluje sposób mieszania się grafiki węzła z grafiką tła: - - - `Alpha` - mieszają się wartości pikseli węzła z tłem. Odpowiada to trybowi "Normal" w oprogramowaniu graficznym. - - `Add` - dodaje wartości pikseli węzła do tła. Odpowiada to trybowi "Linear Dodge" w niektórym oprogramowaniu graficznym. - - `Multiply` - mnoży wartości pikseli węzła przez tło. +: Kontroluje sposób mieszania grafiki węzła z grafiką tła: + - `Alpha` miesza wartości pikseli węzła z tłem. Odpowiada to trybowi "Normal" w programach graficznych. + - `Add` dodaje wartości pikseli węzła do tła. Odpowiada to trybowi "Linear dodge" w niektórych programach graficznych. + - `Multiply` mnoży wartości pikseli węzła przez tło. + - `Screen` mnoży odwrotnie wartości pikseli węzła i tła. Odpowiada to trybowi "Screen" w programach graficznych. Pivot -: Oś obrotu - ustawia punkt obrotu węzła. Można to postrzegać jako "punkt centralny" węzła. Każda rotacja, skalowanie lub zmiana rozmiaru będzie zachodzić wokół tego punktu. +: Ustawia punkt obrotu węzła. Można go traktować jako "punkt środkowy" węzła. Każdy obrót, skalowanie albo zmiana rozmiaru zachodzą wokół tego punktu. -Możliwe wartości to `Center`, `North`, `South`, `East`, `West`, `North West`, `North East`, `South West` lub `South East`. + Dostępne wartości to `Center`, `North`, `South`, `East`, `West`, `North West`, `North East`, `South West` albo `South East`. ![pivot point](images/gui/pivot.png) -Jeśli zmienisz punkt obrotu węzła, węzeł zostanie przesunięty tak, że nowy punkt obrotu będzie znajdować się w pozycji węzła. Węzły tekstowe są ustawiane tak, że `Center` ustawia środek tekstu, `West` ustawia tekst wyrównany do lewej, a `East` ustawia tekst wyrównany do prawej. + Jeśli zmienisz pivot węzła, węzeł zostanie przesunięty tak, aby nowy pivot znalazł się w jego pozycji. Węzły tekstowe są wyrównywane tak, że `Center` centruje tekst, `West` wyrównuje go do lewej, a `East` wyrównuje go do prawej. X Anchor, Y Anchor -: Kotwiczenie kontroluje, w jaki sposób wertykalna i pozioma pozycja węzła jest zmieniana, gdy granice sceny lub granice węzła nadrzędnego są rozciągane, aby pasować do rzeczywistego rozmiaru ekranu. +: Kotwiczenie określa, jak zmienia się pionowa i pozioma pozycja węzła, gdy granice sceny albo granice węzła nadrzędnego są rozciągane tak, aby dopasować się do fizycznego rozmiaru ekranu. ![Anchor unadjusted](images/gui/anchoring_unadjusted.png) Dostępne są następujące tryby kotwiczenia: - - `None` (zarówno *X Anchor*, jak i *Y Anchor*) zachowuje pozycję węzła od centrum węzła nadrzędnego lub sceny, w odniesieniu do jego zmienionego rozmiaru. - - `Left` lub `Right` (*X Anchor*) skaluje poziomą pozycję węzła, aby zachować pozycję z lewego i prawego brzegu węzła nadrzędnego lub sceny w tej samej proporcji. - - `Top` lub `Bottom` skaluje pionową pozycję węzła, aby zachować pozycję z górnego i dolnego brzegu węzła nadrzędnego lub sceny w tej samej proporcji. + - `None` (zarówno dla *X Anchor*, jak i *Y Anchor*) zachowuje pozycję węzła względem środka węzła nadrzędnego albo sceny, w odniesieniu do jego dostosowanego rozmiaru. + - `Left` albo `Right` (*X Anchor*) skaluje poziomą pozycję węzła tak, aby zachować ją w tej samej proporcji względem lewego i prawego brzegu węzła nadrzędnego albo sceny. + - `Top` albo `Bottom` (*Y Anchor*) skaluje pionową pozycję węzła tak, aby zachować ją w tej samej proporcji względem górnego i dolnego brzegu węzła nadrzędnego albo sceny. ![Anchoring](images/gui/anchoring.png) Adjust Mode -: Ustala tryb dostosowania węzła. Ustawienie trybu dostosowania kontroluje, co się dzieje z węzłem, gdy granice sceny lub granice węzła nadrzędnego są dostosowywane, aby pasować do rzeczywistego rozmiaru ekranu. +: Ustawia tryb dostosowania dla węzła. To ustawienie kontroluje, co dzieje się z węzłem, gdy granice sceny albo granice węzła nadrzędnego są dostosowywane do fizycznego rozmiaru ekranu. - Węzeł utworzony w scenie, w której rozdzielczość logiczna jest typową rozdzielczością krajobrazu: + Węzeł utworzony w scenie, w której logiczna rozdzielczość odpowiada typowej rozdzielczości poziomej: ![Unadjusted](images/gui/unadjusted.png) - Dostępne są następujące tryby dostosowania: + Dopasowanie sceny do ekranu pionowego powoduje rozciągnięcie sceny. Podobnie rozciągana jest ramka ograniczająca każdego węzła. Ustawiając tryb dostosowania, można jednak zachować proporcje zawartości węzła. Dostępne są następujące tryby: - - `Fit` Dopasowanie sceny do ekranu pionowego powoduje rozciągnięcie sceny. Każdy obszar ograniczający węzła jest podobnie rozciągany. Jednak ustawiając tryb dostosowania, można zachować niezmieniony stosunek szerokości węzła. - - `Zoom` skaluje zawartość węzła tak, aby była równa rozciągniętej szerokości lub wysokości prostokątnego obszaru ograniczającego, w zależności od tego, która jest większa. Innymi słowy, zawartość w pełni pokryje rozciągnięty obszar ograniczający węzła. - - `Stretch` rozciąga zawartość węzła, tak aby wypełniła rozciągnięty obszar ograniczający węzła. + - `Fit` skaluje zawartość węzła tak, aby odpowiadała rozciągniętej szerokości albo wysokości ramki ograniczającej, zależnie od tego, która z nich jest mniejsza. Innymi słowy, zawartość zmieści się wewnątrz rozciągniętej ramki ograniczającej węzła. + - `Zoom` skaluje zawartość węzła tak, aby odpowiadała rozciągniętej szerokości albo wysokości ramki ograniczającej, zależnie od tego, która z nich jest większa. Innymi słowy, zawartość całkowicie pokryje rozciągniętą ramkę ograniczającą węzła. + - `Stretch` rozciąga zawartość węzła tak, aby wypełniła rozciągniętą ramkę ograniczającą węzła. ![Adjust modes](images/gui/adjusted.png) - Jeśli właściwość sceny GUI *Adjust Reference* jest ustawiona na `Disabled`, czyli wyłaczona, to ustawienie to będzie ignorowane. + Jeśli właściwość sceny GUI *Adjust Reference* ma wartość `Disabled`, to ustawienie to zostanie zignorowane. -Clipping Mode (węzły box i pie) -: Ustawia tryb przycinania na węźle: +Clipping Mode (box and pie nodes) +: Ustawia tryb przycinania dla węzła: - - `None` renderuje węzeł jak zwykle. - - `Stencil` powoduje, że obrzeża węzła definiują maskę szablonu, która jest używana do przycinania węzłów podrzędnych węzła. + - `None` renderuje węzeł normalnie. + - `Stencil` sprawia, że granice węzła definiują maskę szablonu używaną do przycinania jego węzłów potomnych. - Zobacz [instrukcję przycinania GUI](/manuals/gui-clipping). + Szczegóły znajdziesz w [instrukcji przycinania GUI](/manuals/gui-clipping). -Clipping Visible (węzły box i pie) -: Ustaw, aby renderować zawartość węzła na obszarze maski szablonu. Zobacz [instrukcję przycinania GUI](/manuals/gui-clipping). +Clipping Visible (box and pie nodes) +: Ustaw, aby renderować zawartość węzła w obszarze maski szablonu. Szczegóły znajdziesz w [instrukcji przycinania GUI](/manuals/gui-clipping). -Clipping Inverted (węzły box i pie) -: Odwróć maskę szablonu. Zobacz [instrukcję przycinania GUI](/manuals/gui-clipping). +Clipping Inverted (box and pie nodes) +: Odwraca maskę szablonu. Szczegóły znajdziesz w [instrukcji przycinania GUI](/manuals/gui-clipping). -## Punkt obrotu, Kotwice i Tryb Dostosowywania +## Pivot, Anchors i Adjust Mode -Kombinacja właściwości Pivot, Anchors i Adjust Mode umożliwia bardzo elastyczne projektowanie interfejsów GUI, ale może być to dość trudne do zrozumienia bez konkretnego przykładu. Przyjrzyjmy się temu projektowi interfejsu GUI utworzonemu dla ekranu o rozdzielczości 640x1136 pikseli: +Połączenie właściwości Pivot, Anchors i Adjust Mode pozwala bardzo elastycznie projektować GUI, ale bez konkretnego przykładu może być trudno zrozumieć, jak to działa. Weźmy jako przykład taki podgląd GUI utworzony dla ekranu 640x1136: ![](images/gui/adjustmode_example_original.png) -Interfejs użytkownika jest utworzony z kotwicami X i Y ustawionymi na None, a Tryb Dostosowywania Adjust Mode dla każdego węzła pozostawiony na domyślnym ustawieniu Fit. Pivot dla panelu górnego to North, pivot dla panelu dolnego to South, a pivot dla pasków w panelu górnym to West. Reszta węzłów ma punkty obrotu ustawione na Center. Jeśli zmienimy rozmiar okna, aby było szersze, to oto co się stanie: +Interfejs użytkownika został utworzony z X i Y Anchors ustawionymi na None, a Adjust Mode każdego węzła pozostawiono na domyślnym Fit. Pivot górnego panelu to North, pivot dolnego panelu to South, a pivot pasków w górnym panelu ustawiono na West. Pozostałe węzły mają pivot ustawiony na Center. Jeśli zmienimy rozmiar okna tak, aby było szersze, stanie się to: ![](images/gui/adjustmode_example_resized.png) -Teraz, co zrobić, jeśli chcemy, aby górne i dolne paski zawsze miały taką samą szerokość jak ekran? Możemy zmienić Adjust Mode dla paneli tła na kolor szary na Stretch: +A co, jeśli chcemy, aby górny i dolny pasek zawsze były tak szerokie jak ekran? Możemy zmienić Adjust Mode szarych paneli tła u góry i u dołu na Stretch: ![](images/gui/adjustmode_example_resized_stretch.png) -To jest lepsze. Panele tła w kolorze szarym będą teraz zawsze rozciągnięte do szerokości okna, ale paski w panelu górnym oraz dwie skrzynki na dole nie są właściwie umieszczone. Jeśli chcemy, aby paski na górze pozostały po lewej stronie, musimy zmienić X Anchor z None na Left: +To lepiej. Szare panele tła będą teraz zawsze rozciągane do szerokości okna, ale paski w górnym panelu oraz dwa pola na dole nie są poprawnie ustawione. Jeśli chcemy, aby paski u góry pozostały po lewej stronie, musimy zmienić X Anchor z None na Left: ![](images/gui/adjustmode_example_top_anchor_left.png) -To jest dokładnie tak, jak chcemy, żeby było w przypadku panelu górnego. Paski w panelu górnym miały już punkty obrotu ustawione na West, co oznacza, że będą się ładnie pozycjonować z lewym/zachodnim brzegiem pasków (Pivot) przywiązanych do lewego brzegu panelu nadrzędnego (X Anchor). +To dokładnie to, czego chcemy w przypadku górnego panelu. Paski w górnym panelu miały już ustawiony pivot West, co oznacza, że będą ładnie pozycjonowane tak, aby lewy/zachodni brzeg pasków był zakotwiczony do lewego brzegu panelu nadrzędnego (X Anchor). -Teraz, jeśli ustawimy X Anchor na Left dla lewej skrzynki i na Right dla prawej skrzynki, otrzymamy następujący wynik: +Jeśli teraz ustawimy X Anchor na Left dla lewego pola i na Right dla prawego pola, otrzymamy następujący wynik: ![](images/gui/adjustmode_example_bottom_anchor_left_right.png) -To nie jest dokładnie oczekiwany wynik. Obie skrzynki powinny być tak blisko lewego i prawego brzegu, jak paski w panelu górnym. Powodem tego jest błędne ustawienie punktu obrotu: +To nie jest do końca oczekiwany rezultat. Oba pola powinny pozostać tak blisko lewego i prawego brzegu, jak paski w górnym panelu. Powodem jest nieprawidłowo ustawiony pivot: ![](images/gui/adjustmode_example_bottom_pivot_center.png) -Obie skrzynki mają ustawiony punkt obrotu - Pivot na Center. Oznacza to, że gdy ekran staje się szerszy, środek skrzynki (punkt obrotu) pozostaje na tej samej względnej odległości od brzegów. W przypadku lewej skrzynki było to 17% od lewego brzegu w oryginalnym oknie o rozdzielczości 640x1136 pikseli: +Oba pola mają ustawiony pivot Center. Oznacza to, że gdy ekran staje się szerszy, środkowy punkt (pivot) pól pozostaje w tej samej względnej odległości od brzegów. W przypadku lewego pola wynosiło to 17% od lewego brzegu w oryginalnym oknie 640x1136: ![](images/gui/adjustmode_example_original_ratio.png) -Gdy rozmiar ekranu jest inny, środek lewej skrzynki pozostaje na tej samej odległości 17% od lewego brzegu: +Gdy ekran zostaje przeskalowany, środkowy punkt lewego pola pozostaje w tej samej odległości 17% od lewego brzegu: ![](images/gui/adjustmode_example_resized_stretch_ratio.png) -Jeśli zmienimy Pivot z Center na West dla lewej skrzynki i na East dla prawej skrzynki i przesuniemy skrzynki, otrzymamy oczekiwany wynik, nawet gdy ekran zostanie zmieniony w rozmiarze: +Jeśli zmienimy pivot z Center na West dla lewego pola i na East dla prawego pola, a następnie przestawimy pola, otrzymamy oczekiwany rezultat nawet po zmianie rozmiaru ekranu: ![](images/gui/adjustmode_example_bottom_pivot_west_east.png) ## Kolejność rysowania -Wszystkie węzły są renderowane w kolejności, w jakiej są wymienione w folderze "Nodes". Węzeł na górze listy jest rysowany jako pierwszy i będzie więc wyglądać tak, jakby był za innymi węzłami. Ostatni węzeł na liście jest rysowany jako ostatni, co oznacza, że będzie wyglądać tak, jakby był z przodu względem wszystkich innych węzłów. Zmiana wartości Z na węźle nie kontroluje kolejności rysowania; jednakże, jeśli ustawisz wartość Z poza zakresem renderowania swojego skryptu renderującego, węzeł nie będzie już renderowany na ekranie. Możesz również nadpisać kolejność indeksów węzłów warstwami (patrz poniżej). +Wszystkie węzły są renderowane w kolejności, w jakiej są wymienione w folderze "Nodes". Węzeł na górze listy jest rysowany jako pierwszy i dlatego będzie widoczny za wszystkimi pozostałymi węzłami. Ostatni węzeł na liście jest rysowany jako ostatni, co oznacza, że będzie widoczny przed wszystkimi innymi węzłami. Zmiana wartości Z węzła nie kontroluje jego kolejności rysowania; jeśli jednak ustawisz wartość Z poza zakresem renderowania skryptu do renderowania, węzeł nie będzie już renderowany na ekranie. Kolejność indeksów węzłów można nadpisać za pomocą warstw (patrz niżej). ![Draw order](images/gui/draw_order.png) -Wybierz węzeł i naciśnij Alt + W górę/W dół, aby przesunąć węzeł w górę lub w dół i zmienić kolejność indeksu. +Zaznacz węzeł i naciśnij Alt + Up/Down, aby przesunąć go w górę lub w dół i zmienić kolejność indeksów. -Kolejność rysowania można zmieniać w skrypcie: +Kolejność rysowania można też zmieniać w skrypcie: ```lua local bean_node = gui.get_node("bean") @@ -293,47 +371,47 @@ end ## Hierarchie rodzic-dziecko -Węzeł staje się dzieckiem (ang. child) innego węzła, przeciągając go na węzeł, który chcesz, aby był rodzicem (ang. parent) dziecka. Węzeł z rodzicem dziedziczy transformację (pozycję, obrót i skalę) stosowaną do rodzica i względem punktu obrotu rodzica. +Węzeł staje się dzieckiem innego węzła przez przeciągnięcie go na węzeł, który ma być jego rodzicem. Węzeł z rodzicem dziedziczy transformację (pozycję, obrót i skalę) zastosowaną do rodzica oraz względem jego pivota. ![Parent child](images/gui/parent_child.png) -Rodzice są rysowani przed swoimi dziećmi. Wykorzystaj warstwy, aby zmienić kolejność rysowania węzłów rodzica i dziecka oraz zoptymalizować renderowanie węzłów (patrz poniżej). +Rodzice są rysowani przed swoimi dziećmi. Używaj warstw, aby zmieniać kolejność rysowania węzłów rodzica i dziecka oraz optymalizować renderowanie węzłów (patrz niżej). -## Warstwy i wywołania rysowania +## Warstwy i draw calls -Warstwy (ang. layers) pozwalają na dokładną kontrolę nad tym, w jaki sposób węzły są rysowane i mogą być używane do zmniejszenia liczby wywołań rysowania (ang. draw calls), jakie silnik musi tworzyć, aby narysować scenę GUI. Gdy silnik ma rysować węzły sceny GUI, grupuje je we wskaźniki wywołań rysowania na podstawie następujących warunków: +Warstwy dają precyzyjną kontrolę nad tym, jak rysowane są węzły, i można ich użyć do zmniejszenia liczby wywołań rysowania, które silnik musi utworzyć, aby narysować scenę GUI. Gdy silnik ma narysować węzły sceny GUI, grupuje je w partie wywołań rysowania na podstawie następujących warunków: - Węzły muszą używać tego samego typu. -- Węzły muszą używać tego samego atlasu lub źródła kafelków. -- Węzły muszą być renderowane tym samym trybem mieszania (blend mode). +- Węzły muszą używać tego samego atlasu albo źródła kafelków. +- Węzły muszą być renderowane tym samym trybem mieszania. - Muszą używać tego samego fontu. -Jeśli węzeł różni się od poprzedniego pod względem któregoś z tych punktów, nastąpi przerwanie wskaźnika i zostanie utworzone inne wywołanie rysowania. Przycinanie węzłów (clipping nodes) zawsze przerywa wskaźnik, tak jak i każdy zakres szablonu (stencil scope). +Jeśli węzeł różni się od poprzedniego pod którymkolwiek z tych względów, przerwie partię i utworzy kolejne wywołanie rysowania. Węzły przycinające zawsze przerywają partię, a każdy zakres szablonu również przerywa partię. -Możliwość organizowania węzłów w hierarchie ułatwia grupowanie węzłów w jednostki łatwo zarządzalne. Jednak hierarchie mogą skutecznie przerywać renderowanie wskaźników, jeśli miesza się różne typy węzłów: +Możliwość układania węzłów w hierarchie ułatwia grupowanie ich w wygodne jednostki. Hierarchie mogą jednak skutecznie psuć renderowanie partiami, jeśli miesza się różne typy węzłów: ![Breaking batch hierarchy](images/gui/break_batch.png) -Kiedy potok renderowania (ang. rendering pipeline) przechodzi przez listę węzłów, zmuszony jest utworzyć oddzielny wskaźnik dla każdego oddzielnego węzła, ponieważ typy są różne. Ogólnie rzecz biorąc, te trzy przyciski będą wymagały sześciu wywołań rysowania. +Gdy potok renderowania przechodzi przez listę węzłów, musi utworzyć osobną partię dla każdego węzła, ponieważ typy są różne. W sumie te trzy przyciski będą wymagały sześciu wywołań rysowania. -Przypisując węzłom warstwy, można je uporządkować w inny sposób, co pozwala potokowi renderowania grupować węzły w mniej wywołań rysowania. Zacznij od dodania potrzebnych warstw do sceny. Kliknij prawym przyciskiem na ikonę folderu "Layers" w widoku "Outline" i wybierz "Add ▸ Layer". Zaznacz nową warstwę i przypisz jej właściwość "Name" w widoku "Properties". +Przypisując węzłom warstwy, można je uporządkować inaczej, co pozwala potokowi renderowania grupować węzły w mniejszą liczbę wywołań rysowania. Zacznij od dodania potrzebnych warstw do sceny. Kliknij prawym przyciskiem myszy ikonę folderu "Layers" w panelu *Outline* i wybierz Add ▸ Layer. Zaznacz nową warstwę i przypisz jej właściwość *Name* w widoku *Properties*. ![Layers](images/gui/layers.png) -Następnie ustaw właściwość "Layer" dla każdego węzła na odpowiadającą mu warstwę. Kolejność rysowania warstw ma pierwszeństwo nad zwykłym porządkiem indeksów węzłów, więc ustawienie węzłów graficznych przycisku na warstwę "graphics" i węzłów tekstowych przycisku na warstwę "text" spowoduje następującą kolejność rysowania: +Następnie ustaw właściwość *Layer* każdego węzła na odpowiednią warstwę. Kolejność rysowania warstw ma pierwszeństwo przed zwykłą kolejnością indeksów węzłów, więc ustawienie prostokątnych węzłów przycisków na warstwę "graphics" i tekstowych węzłów przycisków na warstwę "text" da następującą kolejność rysowania: -Najpierw wszystkie węzły w warstwie "text", od góry: +* Najpierw wszystkie węzły w warstwie "graphics", od góry: 1. "button-1" 2. "button-2" 3. "button-3" -Następnie wszystkie węzły w warstwie "tekst", od góry: +* Następnie wszystkie węzły w warstwie "text", od góry: 4. "button-text-1" 5. "button-text-2" 6. "button-text-3" -Węzły mogą teraz być grupowane w dwóch wywołaniach rysowania, zamiast sześciu. To znaczna wydajnościowa korzyść! +Węzły można teraz zgrupować w dwa wywołania rysowania zamiast sześciu. To duży zysk wydajnościowy. -Należy zauważyć, że węzeł potomny (child node) bez ustawionej warstwy dziedziczy domyślne ustawienia warstwy od węzła rodzica. Nieustawienie warstwy na węźle domyślnie dodaje go do warstwy "null", która jest rysowana przed innymi warstwami. +Zwróć uwagę, że węzeł potomny bez ustawionej warstwy dziedziczy niejawnie ustawienie warstwy swojego rodzica. Nieustawienie warstwy na węźle niejawnie dodaje go do warstwy "null", która jest rysowana przed wszystkimi innymi warstwami. diff --git a/docs/pl/manuals/hot-reload.md b/docs/pl/manuals/hot-reload.md new file mode 100644 index 00000000..0199c3aa --- /dev/null +++ b/docs/pl/manuals/hot-reload.md @@ -0,0 +1,122 @@ +--- +title: Szybkie przeładowanie zasobów +brief: Ta instrukcja wyjaśnia funkcję szybkiego przeładowywania w silniku Defold. +--- + +# Szybkie przeładowanie zasobów + +Defold umożliwia szybkie przeładowanie zasobów (hot reloading). Podczas tworzenia gry ta funkcja ogromnie przyspiesza niektóre zadania. Pozwala zmieniać kod i zawartość gry, gdy ta działa na żywo. Typowe zastosowania to: + +- dostrajanie parametrów rozgrywki w skryptach Lua +- edycja i strojenie elementów graficznych, takich jak efekty cząsteczkowe lub elementy GUI, oraz oglądanie wyników w odpowiednim kontekście +- edycja i strojenie kodu shaderów oraz oglądanie wyników w odpowiednim kontekście +- ułatwienie testowania gry przez ponowne uruchamianie poziomów, ustawianie stanu itd. bez zatrzymywania gry + +## Jak wykonać szybkie przeładowanie + +Uruchom grę z poziomu edytora (Project ▸ Build). + +Aby przeładować zaktualizowany zasób, po prostu wybierz pozycję menu File ▸ Hot Reload albo naciśnij odpowiedni skrót na klawiaturze: + +![Przeładowywanie zasobów](images/hot-reload/menu.png) + +## Szybkie przeładowanie na urządzeniu + +Funkcja szybkiego przeładowania działa zarówno na urządzeniu, jak i na komputerze. Aby używać jej na urządzeniu, uruchom debugową wersję gry albo [development app](/manuals/dev-app) na urządzeniu mobilnym, a następnie wybierz je jako cel w edytorze: + +![Urządzenie docelowe](images/hot-reload/target.png) + +Od tego momentu, gdy zbudujesz i uruchomisz grę, edytor wyśle wszystkie zasoby do uruchomionej aplikacji na urządzeniu i rozpocznie grę. Każdy plik, który przeładujesz, zostanie zaktualizowany na urządzeniu. + +Na przykład, jeśli chcesz dodać kilka przycisków do GUI wyświetlanego w działającej grze na telefonie, po prostu otwórz plik GUI: + +![Przeładowywanie GUI](images/hot-reload/gui.png) + +Dodaj nowe przyciski, zapisz plik GUI i przeładuj go. Nowe przyciski będą teraz widoczne na ekranie telefonu: + +![Przeładowane GUI](images/hot-reload/gui-reloaded.png) + +Gdy przeładujesz plik, silnik wypisze w konsoli każdy ponownie załadowany plik zasobu. + +## Przeładowanie skryptów + +Każdy przeładowany plik skryptu Lua zostanie ponownie wykonany w działającym środowisku Lua. + +```lua +local my_value = 10 + +function update(self, dt) + print(my_value) +end +``` + +Zmiana `my_value` na 11 i przeładowanie pliku zadziałają natychmiast: + +```text +... +DEBUG:SCRIPT: 10 +DEBUG:SCRIPT: 10 +DEBUG:SCRIPT: 10 +INFO:RESOURCE: /main/hunter.scriptc was successfully reloaded. +DEBUG:SCRIPT: 11 +DEBUG:SCRIPT: 11 +DEBUG:SCRIPT: 11 +... +``` + +Zwróć uwagę, że szybkie przeładowanie nie zmienia sposobu wykonywania funkcji cyklu życia. Na przykład przy szybkim przeładowaniu nie ma wywołania `init()`. Jeśli jednak ponownie zdefiniujesz funkcje cyklu życia, zostaną użyte ich nowe wersje. + +## Przeładowanie modułów Lua + +Jeśli w pliku modułu dodasz zmienne do zakresu globalnego, przeładowanie pliku zmieni te globalne zmienne: + +```lua +--- my_module.lua +my_module = {} +my_module.val = 10 +``` + +```lua +-- user.script +require "my_module" + +function update(self, dt) + print(my_module.val) -- po przeładowaniu "my_module.lua" zostanie wypisana nowa wartość +end +``` + +Częstym wzorcem w modułach Lua jest utworzenie lokalnej tabeli, wypełnienie jej, a następnie zwrócenie jej: + +```lua +--- my_module.lua +local M = {} -- tutaj tworzony jest nowy obiekt tabeli +M.val = 10 +return M +``` + +```lua +-- user.script +local mm = require "my_module" + +function update(self, dt) + print(mm.val) -- wypisze 10 nawet jeśli zmienisz i przeładujesz "my_module.lua" +end +``` + +Zmiana i przeładowanie pliku "my_module.lua" _nie_ zmienią zachowania "user.script". Zobacz [instrukcję o modułach](/manuals/modules), aby dowiedzieć się więcej o tym, dlaczego tak się dzieje i jak uniknąć tej pułapki. + +## Funkcja `on_reload()` + +Każdy komponent skryptu może zdefiniować funkcję `on_reload()`. Jeśli istnieje, zostanie wywołana za każdym razem, gdy skrypt zostanie przeładowany. Jest to przydatne do sprawdzania lub zmieniania danych, wysyłania wiadomości itd.: + +```lua +function on_reload(self) + print(self.velocity) + + msg.post("/level#controller", "setup") +end +``` + +## Przeładowanie kodu shaderów + +Podczas przeładowywania shaderów wierzchołków i fragmentów kod GLSL jest ponownie kompilowany przez sterownik graficzny i wysyłany do GPU. Jeśli kod shaderów spowoduje awarię, co łatwo się zdarza, ponieważ GLSL jest pisany na bardzo niskim poziomie, może to doprowadzić do awarii silnika. diff --git a/docs/pl/manuals/html5.md b/docs/pl/manuals/html5.md new file mode 100644 index 00000000..da0496c5 --- /dev/null +++ b/docs/pl/manuals/html5.md @@ -0,0 +1,333 @@ +--- +title: Tworzenie gier dla platformy HTML5 w Defold +brief: Ta instrukcja opisuje proces tworzenia gry HTML5 oraz znane problemy i ograniczenia. +--- + +# Tworzenie gier HTML5 + +Defold obsługuje budowanie gier dla platformy HTML5 przez zwykłe menu bundlowania, tak samo jak dla innych platform. Dodatkowo wynikowa gra jest osadzana na zwykłej stronie HTML, którą można stylować za pomocą prostego systemu szablonów. + +Plik *game.project* zawiera ustawienia specyficzne dla HTML5: + +![Ustawienia projektu](images/html5/html5_project_settings.png) + +## Rozmiar sterty + +Wsparcie dla HTML5 w Defold opiera się na Emscripten (zob. http://en.wikipedia.org/wiki/Emscripten). W skrócie tworzy on odizolowany obszar pamięci dla sterty, w którym działa aplikacja. Domyślnie silnik przydziela sporą ilość pamięci (256 MB). Powinno to być więcej niż wystarczające dla typowej gry. W ramach optymalizacji możesz zdecydować się na mniejszą wartość. Aby to zrobić, wykonaj następujące kroki: + +1. Ustaw *heap_size* na wybraną wartość. Powinna być wyrażona w megabajtach. +2. Utwórz pakiet HTML5 (zobacz poniżej). + +## Testowanie builda HTML5 + +Do testowania builda HTML5 potrzebny jest serwer HTTP. Defold utworzy taki serwer za ciebie, jeśli wybierzesz Project ▸ Build HTML5. + +![Build HTML5](images/html5/html5_build_launch.png) + +Jeśli chcesz przetestować swój pakiet, po prostu wgraj go na zdalny serwer HTTP albo utwórz lokalny serwer, na przykład używając Pythona w folderze pakietu. +Python 2: + +```sh +python -m SimpleHTTPServer +``` + +Python 3: + +```sh +python -m http.server +``` + +lub + +```sh +python3 -m http.server +``` + +::: important +Nie możesz przetestować pakietu HTML5, otwierając pliku `index.html` w przeglądarce. Wymaga to serwera HTTP. +::: + +::: important +Jeśli w konsoli zobaczysz błąd `"wasm streaming compile failed: TypeError: Failed to execute ‘compile’ on ‘WebAssembly’: Incorrect response MIME type. Expected ‘application/wasm’."`, upewnij się, że twój serwer używa typu MIME `application/wasm` dla plików `.wasm`. +::: + +## Tworzenie pakietu HTML5 + +Tworzenie zawartości HTML5 w Defold jest proste i odbywa się tak samo jak dla wszystkich innych obsługiwanych platform: wybierz z menu Project ▸ Bundle... ▸ HTML5 Application.... + +![Utwórz pakiet HTML5](images/html5/html5_bundle.png) + +Możesz zdecydować, czy chcesz dołączyć do pakietu HTML5 zarówno wersję silnika Defold `asm.js`, jak i WebAssembly (wasm). W większości przypadków wystarczy wybrać WebAssembly, ponieważ [wszystkie nowoczesne przeglądarki obsługują WebAssembly](https://caniuse.com/wasm). + +::: important +Nawet jeśli dołączysz do silnika zarówno wersję `asm.js`, jak i `wasm`, przeglądarka pobierze tylko jedną z nich podczas uruchamiania gry. Wersja WebAssembly zostanie pobrana, jeśli przeglądarka ją obsługuje, a wersja `asm.js` zostanie użyta jako alternatywa w rzadkim przypadku, gdy WebAssembly nie jest obsługiwane. +::: + +Po kliknięciu przycisku Create bundle zostaniesz poproszony o wybranie folderu, w którym ma zostać utworzona aplikacja. Po zakończeniu eksportu znajdziesz wszystkie pliki potrzebne do uruchomienia aplikacji. + +## Znane problemy i ograniczenia + +* Szybkie przeładowanie (Hot Reload) - szybkie przeładowanie nie działa w buildach HTML5. Aplikacje Defold muszą uruchamiać własny niewielki serwer WWW, aby odbierać aktualizacje z edytora, a nie jest to możliwe w buildzie HTML5. +* Internet Explorer 11 + * Audio - Defold odtwarza dźwięk za pomocą HTML5 _WebAudio_ (zob. http://www.w3.org/TR/webaudio), którego Internet Explorer 11 obecnie nie obsługuje. W tej przeglądarce aplikacje przejdą na implementację bez dźwięku. + * WebGL - Microsoft nie ukończył jeszcze pracy nad implementacją API _WebGL_ (zob. https://www.khronos.org/registry/webgl/specs/latest/). Z tego powodu działa ono gorzej niż w innych przeglądarkach. + * Tryb pełnoekranowy (Full screen) - tryb pełnoekranowy jest w przeglądarce zawodny. +* Chrome + * Powolne buildy debug (Slow debug builds) - w buildach debug HTML5 sprawdzamy wszystkie wywołania grafiki WebGL, aby wykrywać błędy. Niestety podczas testowania w Chrome jest to bardzo powolne. Można to wyłączyć, ustawiając pole *Engine Arguments* w *game.project* na `--verify-graphics-calls=false`. +* Obsługa gamepadów (Gamepad support) - [dokumentacja gamepadów](/manuals/input-gamepads/#gamepads-in-html5) zawiera szczególne uwagi i kroki, które mogą być potrzebne w HTML5. + +## Dostosowywanie pakietu HTML5 + +Podczas generowania wersji HTML5 swojej gry Defold udostępnia domyślną stronę WWW. Odwołuje się ona do zasobów stylów i skryptów, które określają sposób prezentacji gry. + +Za każdym razem, gdy aplikacja jest eksportowana, ta zawartość jest tworzona od nowa. Jeśli chcesz dostosować którykolwiek z tych elementów, musisz zmodyfikować ustawienia projektu. W tym celu otwórz *game.project* w edytorze Defold i przewiń do sekcji *html5*: + +![Sekcja HTML5](images/html5/html5_section.png) + +Więcej informacji o każdej opcji znajdziesz w [instrukcji ustawień projektu](/manuals/project-settings/#html5). + +::: important +Nie możesz modyfikować plików domyślnego szablonu html/css w folderze `builtins`. Aby wprowadzić swoje zmiany, skopiuj potrzebny plik z `builtins` i ustaw ten plik w *game.project*. +::: + +::: important +Canvas nie powinien mieć żadnej ramki ani odstępów wewnętrznych. Jeśli je dodasz, współrzędne wejścia myszy będą nieprawidłowe. +::: + +W *game.project* można wyłączyć przycisk `Fullscreen` i link `Made with Defold`. +Defold udostępnia ciemny i jasny motyw dla index.html. Jasny motyw jest ustawiony domyślnie, ale można go zmienić, modyfikując plik `Custom CSS`. W polu `Scale Mode` dostępne są także cztery predefiniowane tryby skalowania. + +::: important +Obliczenia dla wszystkich trybów skalowania uwzględniają bieżące DPI ekranu, jeśli włączysz opcję `High Dpi` w *game.project* (sekcja `Display`). +::: + +### Downscale Fit i Fit + +W trybie `Fit` rozmiar canvasu zostanie zmieniony tak, aby cały obszar gry był widoczny na ekranie przy zachowaniu oryginalnych proporcji. Jedyna różnica w `Downscale Fit` polega na tym, że rozmiar jest zmieniany tylko wtedy, gdy wewnętrzny rozmiar strony WWW jest mniejszy od oryginalnego canvasu gry, ale nie następuje powiększanie, gdy strona WWW jest większa od oryginalnego canvasu gry. + +![Sekcja HTML5](images/html5/html5_fit.png) + +### Stretch + +W trybie `Stretch` rozmiar canvasu zostanie zmieniony tak, aby całkowicie wypełnić wewnętrzny rozmiar strony WWW. + +![Sekcja HTML5](images/html5/html5_stretch.png) + +### No Scale +W trybie `No Scale` rozmiar canvasu jest dokładnie taki sam, jak zdefiniowany w pliku *game.project*, w sekcji `[display]`. + +![Sekcja HTML5](images/html5/html5_no_scale.png) + +## Tokeny + +Do tworzenia pliku `index.html` używamy języka szablonów [Mustache](https://mustache.github.io/mustache.5.html). Podczas budowania lub tworzenia pakietu pliki HTML i CSS są przepuszczane przez kompilator, który potrafi zastępować wybrane tokeny wartościami zależnymi od ustawień projektu. Tokeny te są zawsze ujęte w podwójne albo potrójne nawiasy klamrowe (`{{TOKEN}}` lub `{{{TOKEN}}}`), zależnie od tego, czy sekwencje znaków mają być escapowane. Ta funkcja może być przydatna, jeśli często zmieniasz ustawienia projektu albo chcesz ponownie używać materiałów w innych projektach. + +::: sidenote +Więcej informacji o języku szablonów Mustache znajdziesz w [instrukcji](https://mustache.github.io/mustache.5.html). +::: + +Każde ustawienie w *game.project* może być tokenem. Na przykład, jeśli chcesz użyć wartości `Width` z sekcji `Display`: + +![Sekcja Display](images/html5/html5_display.png) + +Otwórz *game.project* jako tekst i sprawdź `[section_name]` oraz nazwę pola, którego chcesz użyć. Następnie możesz użyć go jako tokenu: `{{section_name.field}}` albo `{{{section_name.field}}}`. + +![Sekcja Display](images/html5/html5_game_project.png) + +Na przykład w szablonie HTML w JavaScript: + +```javascript +function doSomething() { + var x = {{display.width}}; + // ... +} +``` + +Mamy też następujące własne tokeny: + +DEFOLD_SPLASH_IMAGE +: Zapisuje nazwę pliku obrazu startowego albo `false`, jeśli `html5.splash_image` w *game.project* jest puste. + + +```css +{{#DEFOLD_SPLASH_IMAGE}} + background-image: url("{{DEFOLD_SPLASH_IMAGE}}"); +{{/DEFOLD_SPLASH_IMAGE}} +``` + +exe-name +: Nazwa projektu bez niedozwolonych znaków. + +DEFOLD_CUSTOM_CSS_INLINE +: To miejsce, w którym wstawiana jest bezpośrednio zawartość pliku CSS określonego w ustawieniach *game.project*. + + +```html + +``` + +::: important +Ważne jest, aby ten blok wstawiany bezpośrednio pojawił się przed załadowaniem głównego skryptu aplikacji. Ponieważ zawiera znaczniki HTML, to makro powinno używać potrójnych nawiasów klamrowych `{{{TOKEN}}}`, aby sekwencje znaków nie zostały escapowane. +::: + +DEFOLD_SCALE_MODE_IS_DOWNSCALE_FIT +: Ten token ma wartość `true`, jeśli `html5.scale_mode` ma ustawienie `Downscale Fit`. + +DEFOLD_SCALE_MODE_IS_FIT +: Ten token ma wartość `true`, jeśli `html5.scale_mode` ma ustawienie `Fit`. + +DEFOLD_SCALE_MODE_IS_NO_SCALE +: Ten token ma wartość `true`, jeśli `html5.scale_mode` ma ustawienie `No Scale`. + +DEFOLD_SCALE_MODE_IS_STRETCH +: Ten token ma wartość `true`, jeśli `html5.scale_mode` ma ustawienie `Stretch`. + +DEFOLD_HEAP_SIZE +: Rozmiar sterty określony w *game.project* przez `html5.heap_size`, przeliczony na bajty. + +DEFOLD_ENGINE_ARGUMENTS +: Argumenty silnika określone w *game.project* w polu `html5.engine_arguments`, rozdzielone symbolem `,`. + +build-timestamp +: Bieżący znacznik czasu kompilacji w sekundach. + + +## Dodatkowe parametry + +Jeśli tworzysz własny szablon, możesz zdefiniować ponownie zestaw parametrów dla loadera silnika. Aby to zrobić, musisz dodać sekcję ` +``` + +`CUSTOM_PARAMETERS` może zawierać następujące pola: + +``` +'archive_location_filter': + Funkcja filtrująca, która będzie uruchamiana dla każdej ścieżki archiwum. + +'unsupported_webgl_callback': + Funkcja wywoływana, jeśli WebGL nie jest obsługiwany. + +'engine_arguments': + Lista argumentów (ciągów), które zostaną przekazane do silnika. + +'custom_heap_size': + Liczba bajtów określająca rozmiar sterty pamięci. + +'disable_context_menu': + Wyłącza menu kontekstowe po kliknięciu prawym przyciskiem myszy na elemencie canvas, jeśli ma wartość true. + +'retry_time': + Czas pauzy w sekundach przed ponowną próbą wczytania pliku po błędzie. + +'retry_count': + Liczba prób podejmowanych podczas pobierania pliku. + +'can_not_download_file_callback': + Funkcja wywoływana, jeśli nie uda się pobrać pliku po próbach określonych w 'retry_count'. + +'resize_window_callback': + Funkcja wywoływana, gdy wystąpią zdarzenia resize/orientationchanges/focus. + +'start_success': + Funkcja wywoływana tuż przed main, po pomyślnym wczytaniu. + +'update_progress': + Funkcja wywoływana w miarę aktualizacji postępu. Parametr progress jest aktualizowany w zakresie 0-100. +``` + +## Operacje na plikach w HTML5 + +Buildy HTML5 obsługują operacje na plikach, takie jak `sys.save()`, `sys.load()` i `io.open()`, ale sposób ich obsługi wewnętrznej różni się od innych platform. Gdy JavaScript działa w przeglądarce, nie istnieje prawdziwe pojęcie systemu plików, a lokalny dostęp do plików jest blokowany ze względów bezpieczeństwa. Zamiast tego Emscripten (a więc i Defold) używa [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB), przeglądarkowej bazy danych służącej do trwałego przechowywania danych, aby utworzyć w przeglądarce wirtualny system plików. Istotną różnicą względem dostępu do systemu plików na innych platformach jest to, że między zapisaniem pliku a rzeczywistym zapisaniem zmiany w bazie danych może wystąpić niewielkie opóźnienie. Zawartość IndexedDB zwykle można sprawdzić w konsoli deweloperskiej przeglądarki. + + +## Przekazywanie argumentów do gry HTML5 + +Czasami trzeba przekazać grze dodatkowe argumenty jeszcze przed jej uruchomieniem albo podczas uruchamiania. Może to być na przykład identyfikator użytkownika, token sesji albo informacja, który poziom wczytać przy starcie gry. Można to zrobić na kilka sposobów, z których niektóre opisano tutaj. + +### Argumenty silnika + +Można określić dodatkowe argumenty silnika podczas konfiguracji i wczytywania silnika. Te dodatkowe argumenty można w czasie działania odczytać za pomocą `sys.get_config()`. Aby dodać pary klucz-wartość, zmodyfikuj pole `engine_arguments` obiektu `extra_params`, które jest przekazywane do silnika podczas wczytywania w `index.html`: + + +``` +