From 8dc511e909f3b144b6d39758eae9de4a869f4347 Mon Sep 17 00:00:00 2001 From: AGulev Date: Fri, 13 Mar 2026 12:43:57 +0100 Subject: [PATCH 1/8] bunch two --- docs/pl/manuals/collection-factory.md | 119 ++++++----- docs/pl/manuals/editor-preferences.md | 96 +++++---- docs/pl/manuals/factory.md | 156 +++++++-------- docs/pl/manuals/lua.md | 68 +++---- docs/pl/manuals/mesh.md | 65 +++--- docs/pl/manuals/physics-joints.md | 46 +++-- docs/pl/manuals/property-animation.md | 138 ++++++------- docs/pl/manuals/resource.md | 70 ++++--- docs/pl/manuals/texture-profiles.md | 276 +++++++++++++++----------- docs/pl/manuals/writing-code.md | 69 ++++--- 10 files changed, 606 insertions(+), 497 deletions(-) diff --git a/docs/pl/manuals/collection-factory.md b/docs/pl/manuals/collection-factory.md index 259443cd..bc1f9cbd 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 Collection factory 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 Collection factory 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 budujących](/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 Collection factory możesz tworzyć w świecie gry zawartość pliku kolekcji. To odpowiednik utworzenia przez Factory 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* służy do tworzenia nowego świata gry, w tym osobnego świata fizyki, na podstawie kolekcji. Nowy świat jest dostępny przez nowe gniazdo adresowe. 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 małych elementów. 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 *Collection factory* do obiektu gry, który ma odpowiadać za tworzenie instancji, i ustawiamy `bean.collection` jako *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 Collection factory, 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 Collection factory. `[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 runtime id 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,94 @@ 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 Collection factory 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 Collection factory, 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 Collection factory. 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 + -- Collection factory 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 callback. ```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 Collection factory. 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 + -- Collection factory 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ć Collection factory, 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 Collection factory 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/editor-preferences.md b/docs/pl/manuals/editor-preferences.md index ff3bf4d9..20996d3f 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: Ustawienia edytora możesz zmieniać w oknie Preferences. --- -# Preferencje Edytora +# Preferencje edytora -Możesz dostosować ustawienia Edytora z poziomu okna Preferencji. Okno Preferencji otwiera się z menu File -> Preferences. +Ustawienia edytora możesz zmieniać w oknie Preferences. Okno otwiera się z menu File -> Preferences. ## General (Ogólne) ![](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. +: Włącza skanowanie 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. +: 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. +: Włącza [kompresję tekstur](/manuals/texture-profiles) dla wszystkich buildów wykonywanych z poziomu edytora. Escape Quits Game (Klawisz Escape zamyka grę) -: Zatrzymuje działającą kompilację twojej gry za pomocą klawisza Esc. +: 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*). +: Plik edytowany na aktualnie wybranej karcie w panelu *Editor* zostanie zaznaczony w Asset Browser, nazywanym też panelem *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 [linting kodu](/manuals/writing-code/#konfiguracja-lintingu) podczas budowania projektu. Ta opcja jest domyślnie włączona, ale można ją wyłączyć, jeśli linting 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`). +: Bezwzględna ścieżka do zewnętrznego edytora. W 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. -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. `{file}` zostanie zastąpione nazwą pliku, 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, używanej w edytorze 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 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 edytora Defold 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`. +: URL serwera buildów używanego podczas budowania projektu zawierającego [native extensions](/manuals/extensions). Do URL można dodać nazwę użytkownika i token dostępu, aby uwierzytelnić się przy dostępie do serwera buildów. Użyj notacji `username:token@build.defold.com`. Uwierzytelniony dostęp jest wymagany przy buildach na Nintendo Switch oraz przy korzystaniu z własnej instancji serwera buildów z włączonym uwierzytelnianiem ([zobacz dokumentację serwera buildów](https://github.com/defold/extender/blob/dev/README_SECURITY.md)). Nazwę użytkownika i hasło można też ustawić w zmiennych środowiskowych `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 serwera buildów podczas budowania rozszerzeń natywnych. 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 ADB) +: Ścieżka do narzędzia wiersza poleceń [ADB](https://developer.android.com/tools/adb) zainstalowanego w systemie. Jeśli ADB jest dostępne, edytor Defold użyje go do instalowania i uruchamiania zbudowanych plików APK na podłączonym urządzeniu z Androidem. Domyślnie edytor sprawdza kilka znanych lokalizacji, więc ścieżkę trzeba podawać tylko wtedy, gdy ADB jest zainstalowane niestandardowo. + +ios-deploy path (Ścieżka ios-deploy) +: Ścieżka do narzędzia wiersza poleceń [ios-deploy](https://github.com/ios-control/ios-deploy) zainstalowanego w systemie. Dotyczy to tylko macOS. Podobnie jak przy `ADB path`, edytor Defold użyje tego narzędzia do instalowania i uruchamiania zbundlowanych aplikacji iOS na podłączonym iPhonie. Domyślnie edytor sprawdza kilka znanych lokalizacji, 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 klawiszowe edytora, zarówno dodając własne, jak i usuwając wbudowane. Aby edytować skrót, użyj menu kontekstowego dla wybranego polecenia w tabeli skrótów albo kliknij 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ć szczegóły. 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/factory.md b/docs/pl/manuals/factory.md index 1a40dbf9..37e76e5e 100644 --- a/docs/pl/manuals/factory.md +++ b/docs/pl/manuals/factory.md @@ -1,22 +1,22 @@ --- -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 runtime. --- -# 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. W innych silnikach taki prototyp bywa nazywany również prefabem albo blueprintem. Na tej podstawie tworzone są wszystkie nowe obiekty gry. -![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 utworzyć obiekt gry, wywołaj `factory.create()`: ```lua --- factory.script +-- plik factory.script local p = go.get_position() p.y = vmath.lerp(math.random(), min_y, max_y) local component = "#star_factory" @@ -25,39 +25,38 @@ 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 zostanie utworzony 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. Informacje 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 jednakowe skalowanie we wszystkich osiach. Możesz też przekazać `vector3`, gdzie każdy składnik określa skalowanie w odpowiadającej osi. Na przykład: ```lua --- factory.script +-- plik factory.script 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 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 +-- plik star.script go.property("score", 1) -- <1> local speed = -240 @@ -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 do wartości przechowywanej w `self`. -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". - -![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życie id utworzonego obiektu, na przykład przy wysyłaniu 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,149 +117,150 @@ local function create_guard(unarmed) end ``` -## Śledzenie utworzonych obiektów i rodziców +## Śledzenie utworzonych obiektów i obiektów nadrzędnych -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. Często wykorzystuje się to do tworzenia obiektów i dodawania ich id do tabeli, aby później usunąć je wszystkie, na przykład przy resetowaniu układu poziomu: ```lua --- spawner.script +-- plik spawner.script 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 +-- plik spawner.script +-- 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ę: +Często chcesz też, 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 +-- plik spawner.script +-- Utwórz drona i ustaw jego rodzica 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: +A logika utworzonego obiektu wygląda tak: + ```lua --- drone.script +-- plik drone.script go.property("parent", msg.url()) ... function final(self) - -- I'm dead. + -- Koniec działania obiektu. 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ń obiekty 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 callback. ```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ć prototyp tworzony przez Factory przez zaznaczenie pola *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 -factory.set_prototype("#factory", "/main/levels/enemyA.goc") -local enemy_id = factory.create("#factory") +factory.set_prototype("#factory", "/main/levels/enemy.go") +local 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, liczba komponentów w kolekcji nie może zostać zoptymalizowana, a kolekcja właściciela będzie używać domyślnych limitó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 jednym świecie. Dotyczy to zarówno `main.collection` wczytywanej przy starcie, jak i dowolnego świata załadowanego przez Collection proxy. 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) -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 obiekty gry ręcznie umieszczone w głównej kolekcji, możesz dodatkowo utworzyć 1000 obiektów gry. Gdy tylko usuniesz jakiś obiekt gry, możesz utworzyć kolejną instancję. ## Pula 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 stosuje jednak pooling obiektów wewnętrznie, więc dodatkowa warstwa narzutu tylko spowolni działanie. Szybciej i czyściej jest usuwać obiekty gry i tworzyć nowe. diff --git a/docs/pl/manuals/lua.md b/docs/pl/manuals/lua.md index e91affa9..951e2b92 100644 --- a/docs/pl/manuals/lua.md +++ b/docs/pl/manuals/lua.md @@ -1,42 +1,33 @@ --- -title: Programowanie Lua w Defoldzie -brief: Ta instrukcja przedstawi krótkie wprowadzenie do podstaw programowania w języku Lua ogólnie oraz to, na co należy zwrócić uwagę podczas pracy z Lua w Defoldzie. +title: Programowanie w Lua w silniku Defold +brief: Ta instrukcja krótko wprowadza w podstawy programowania w języku Lua i wyjaśnia, na co zwracać uwagę podczas pracy z Lua w silniku Defold. --- -# Lua w Defoldzie +# Lua w silniku Defold -Silnik Defold ma wbudowany język Lua do skryptowania. Lua to lekki język dynamiczny, który jest potężny, szybki i łatwy do osadzenia. Jest powszechnie używany jako język skryptowy w grach wideo. Programy w Lua są napisane w prostym składni proceduralnym. Język jest dynamicznie typowany i uruchamiany przez interpreter kodu bajtowego. Posiada automatyczne zarządzanie pamięcią z inkrementalnym zbieraniem śmieci. +Silnik Defold ma wbudowany język Lua do skryptowania. Lua to lekki język dynamiczny, który jest wydajny, szybki i łatwy do osadzenia. Jest powszechnie używany jako język skryptowy w grach wideo. Programy w Lua zapisuje się prostą składnią proceduralną. Język jest dynamicznie typowany i wykonywany przez interpreter kodu bajtowego. Oferuje automatyczne zarządzanie pamięcią z inkrementalnym odśmiecaniem. -Ta instrukcja przedstawi krótkie wprowadzenie do podstaw programowania w Lua ogólnie oraz to, na co należy zwrócić uwagę podczas pracy z Lua w Defoldzie. Jeśli masz pewne doświadczenie z Pythonem, Perlem, Rubym, Javascriptem lub podobnym językiem dynamicznym, szybko się dostosujesz. Jeśli jesteś zupełnie nowy w programowaniu, możesz rozpocząć od książki o Lua skierowanej dla początkujących. Jest ich wiele do wyboru. +Ta instrukcja krótko wprowadza w podstawy programowania w Lua i wyjaśnia, na co zwracać uwagę podczas pracy z Lua w silniku Defold. Jeśli masz już doświadczenie z Pythonem, Perlem, Rubym, JavaScriptem lub podobnym językiem dynamicznym, szybko się odnajdziesz. Jeśli dopiero zaczynasz programować, warto sięgnąć po książkę o Lua dla początkujących. Do wyboru jest ich wiele. ## Wersje Lua -Staramy się, aby Defold był taki sam na wszystkich platformach, ale obecnie mamy kilka drobnych rozbieżności w wersji języka Lua między platformami: +[LuaJIT](https://luajit.org/) to mocno zoptymalizowana wersja Lua, dobrze nadająca się do gier i innego oprogramowania krytycznego pod względem wydajności. Jest w pełni kompatybilna w górę z Lua 5.1 i obsługuje wszystkie standardowe funkcje bibliotek Lua oraz pełny zestaw funkcji Lua/C API. -| Platforma | Wersja Lua | JIT Włączony | -|------------------|---------------------|--------------| -| Windows | LuaJIT 2.1.0-beta3 | Tak | -| macOS | LuaJIT 2.1.0-beta3 | Tak | -| Linux | LuaJIT 2.1.0-beta3 | Tak | -| Android | LuaJIT 2.1.0-beta3 | Tak | -| iOS | LuaJIT 2.1.0-beta3 | Nie* | -| Nintendo Switch | LuaJIT 2.1.0-beta3 | Nie* | -| HTML5 | Lua 5.1.4 | N/A | +LuaJIT dodaje też kilka [rozszerzeń języka](https://luajit.org/extensions.html) oraz część funkcji z Lua 5.2 i 5.3. -*=Kod kompilowany JIT nie jest dozwolony - -[LuaJIT](https://luajit.org/) to bardzo zoptymalizowana wersja Lua, odpowiednia do użycia w grach i innych krytycznych pod względem wydajności oprogramowaniu. LuaJIT jest w pełni kompatybilny w górę z Lua 5.1. Obsługuje wszystkie standardowe funkcje biblioteki Lua oraz pełen zestaw funkcji Lua/C API. - -LuaJIT dodaje również kilka [rozszerzeń języka](https://luajit.org/extensions.html) i niektóre funkcje z Lua 5.2. +Chcemy, aby Defold zachowywał się tak samo na wszystkich platformach, ale obecnie istnieje kilka drobnych różnic dotyczących wersji Lua: +* iOS nie pozwala na kompilację JIT. +* Nintendo Switch nie pozwala na kompilację JIT. +* HTML5 używa Lua 5.1.4 zamiast LuaJIT. ::: important Aby zagwarantować, że Twoja gra działa na wszystkich obsługiwanych platformach, gorąco zalecamy korzystanie TYLKO z funkcji języka z wersji Lua 5.1. ::: ### Biblioteki standardowe i rozszerzenia -Defold zawiera wszystkie [standardowe biblioteki Lua 5.1](http://www.lua.org/manual/5.1/manual.html#5), a także bibliotekę do operacji na gniazdach i operacji bitowych: +Defold zawiera wszystkie [standardowe biblioteki Lua 5.1](http://www.lua.org/manual/5.1/manual.html#5), a także bibliotekę socket i bibliotekę operacji bitowych: - - base (`assert()`, `error()`, `print()`, `ipairs()`, `require()`, itp.) + - base (`assert()`, `error()`, `print()`, `ipairs()`, `require()` itd.) - coroutine - package - string @@ -53,22 +44,23 @@ Wszystkie biblioteki są udokumentowane w [dokumentacji API](/ref/go). ## Książki i zasoby Lua ### Zasoby online -* [Programowanie w Lua (pierwsza edycja)](http://www.lua.org/pil/contents.html) Dostępne są późniejsze edycje w wersji drukowanej. -* [Podręcznik referencyjny Lua 5.1](http://www.lua.org/manual/5.1/) -* [Naucz się Lua w 15 minut](http://tylerneylon.com/a/learn-lua/) -* [Niesamowita Lua - sekcja z tutorialami](https://github.com/LewisJEllis/awesome-lua#tutorials) +* [Programming in Lua (first edition)](http://www.lua.org/pil/contents.html) Późniejsze wydania są dostępne w druku. +* [Lua 5.1 reference manual](http://www.lua.org/manual/5.1/) +* [Learn Lua in 15 Minutes](http://tylerneylon.com/a/learn-lua/) +* [Awesome Lua - tutorial section](https://github.com/LewisJEllis/awesome-lua#tutorials) ### Książki -* [Programowanie w Lua](https://www.amazon.com/gp/product/8590379868/ref=dbs_a_def_rwt_hsch_vapi_taft_p1_i0) - Programowanie w Lua to oficjalna książka o języku, stanowiąca solidną podstawę dla każdego programisty, który chce używać Lua. Autorstwa Roberto Ierusalimschy, głównego architekta języka. -* [Lua programming gems](https://www.amazon.com/gp/product/8590379868/ref=dbs_a_def_rwt_hsch_vapi_taft_p1_i0) - Lua Programming Gems to zbiór krótkich i zrozumiałych przepisów, stworzonych przez różnych doświadczonych programistów Lua. Książka ta oferuje wiele przydatnych porad i trików dotyczących programowania w Lua. -* [Beginning Lua Programming](https://www.amazon.com/gp/product/1484219602/ref=dbs_a_def_rwt_hsch_vapi_taft_p1_i0) - Ta książka zawiera wiele praktycznych przykładów i projektów, które pomogą Ci opanować język Lua. Jest odpowiednia dla początkujących programistów, ale oferuje także bardziej zaawansowane tematy dla tych, którzy chcą pogłębić swoją wiedzę. -* [Programming in Lua](https://www.amazon.com/gp/product/8590379868/ref=dbs_a_def_rwt_hsch_vapi_taft_p1_i0) - Kolejna dobra książka na temat Lua, napisana przez Roberto Ierusalimschy, jednego z autorów języka Lua. Obejmuje wiele aspektów języka Lua i dostarcza praktyczne wskazówki oraz porady dotyczące programowania w nim. +* [Programming in Lua](https://www.amazon.com/gp/product/8590379868/ref=dbs_a_def_rwt_hsch_vapi_taft_p1_i0) - To oficjalna książka o języku, dająca solidne podstawy każdemu programiście chcącemu używać Lua. Jej autorem jest Roberto Ierusalimschy, główny architekt języka. +* [Lua programming gems](https://www.amazon.com/Programming-Gems-Luiz-Henrique-Figueiredo/dp/8590379841) - Zbiór artykułów dokumentujących dobre praktyki i sprawdzone podejścia do programowania w Lua. +* [Lua 5.1 reference manual](https://www.amazon.com/gp/product/8590379833/ref=dbs_a_def_rwt_hsch_vapi_taft_p1_i4) - Ta pozycja jest dostępna również online. +* [Beginning Lua Programming](https://www.amazon.com/Beginning-Lua-Programming-Kurt-Jung/dp/0470069171) -Oczywiście, istnieje wiele innych dostępnych materiałów i samouczków do nauki Lua, więc możesz wybrać te, które najlepiej odpowiadają Twoim potrzebom i poziomowi umiejętności. +### Wideo +* [Learn Lua in one video](https://www.youtube.com/watch?v=iMacxZQMPXs) ## Składnia języka Lua -Programy w Lua mają prostą, czytelną składnię. Instrukcje zapisywane są jedna na każdej linii, i nie ma potrzeby oznaczania końca instrukcji. Opcjonalnie można używać średników `;` do oddzielania instrukcji. Bloki kodu są ograniczane słowem kluczowym `end`. Komentarze mogą być blokowe lub do końca linii: +Programy w Lua mają prostą, czytelną składnię. Instrukcje zapisuje się po jednej w każdej linii i nie ma potrzeby oznaczania końca instrukcji. Opcjonalnie można używać średników `;` do oddzielania instrukcji. Bloki kodu są ograniczane słowem kluczowym `end`. Komentarze mogą być blokowe lub jednolinijkowe: ```lua --[[ @@ -91,7 +83,7 @@ end Lua jest językiem dynamicznym, co oznacza, że zmienne nie mają określonych typów, ale wartości już mają. W odróżnieniu od języków o typach statycznych, możesz przypisać dowolną wartość do dowolnej zmiennej. W Lua istnieje osiem podstawowych typów wartości: `nil` -: Ten typ ma tylko jedna wartość, `nil`. Zazwyczaj reprezentuje brak przydatnej wartości, na przykład nieprzypisane zmienne. +: Ten typ ma tylko jedną wartość: `nil`. Zazwyczaj reprezentuje brak przydatnej wartości, na przykład nieprzypisane zmienne. ```lua print(my_var) -- wyświetli 'nil', ponieważ 'moja_zmienna' nie ma jeszcze przypisanej wartości @@ -251,7 +243,7 @@ function ``` `userdata` -: Userdata (dane użytkownika) pozwala na przechowywanie dowolnych danych C w zmiennych Lua. W Defoldzie, userdata Lua służy do przechowywania wartości Hash (`hash`), obiektów URL (`url`), obiektów Math (`vector3`, `vector4`, `matrix4`, `quaternion`), obiektów gry, węzłów GUI (`GUI node`), predykatów renderowania (`predicate`), celów renderowania (`render_target`) oraz buforów stałych renderowania (`constant_buffer`). +: Userdata (dane użytkownika) pozwala przechowywać dowolne dane C w zmiennych Lua. W silniku Defold userdata Lua służy do przechowywania wartości Hash (`hash`), obiektów URL (`url`), obiektów Math (`vector3`, `vector4`, `matrix4`, `quaternion`), obiektów gry, węzłów GUI (`GUI node`), predykatów renderowania (`predicate`), celów renderowania (`render_target`) oraz buforów stałych renderowania (`constant_buffer`). `thread` : Wątki reprezentują niezależne wątki wykonywania i są używane do implementacji korygujących. Zobacz poniżej dla szczegółów. @@ -360,7 +352,7 @@ while weekdays = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"} - -- Print each weekday + -- Wypisz każdy dzień tygodnia i = 1 while weekdays[i] do print(weekdays[i]) @@ -375,7 +367,7 @@ repeat---until weekdays = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"} - -- Print each weekday + -- Wypisz każdy dzień tygodnia i = 0 repeat i = i + 1 @@ -546,9 +538,9 @@ end ``` -## Konteksty Lua w Defoldzie +## Konteksty Lua w silniku Defold -Wszystkie zmienne, które deklarujesz, są domyślnie globalne, co oznacza, że są dostępne we wszystkich częściach kontekstu uruchomienia Lua (ang. Lua runtime context). W Defoldzie istnieje opcja *shared_state* w pliku *game.project*, która kontroluje ten kontekst. Jeśli opcja jest ustawiona, wszystkie skrypty, skrypty GUI i skrypt renderowania są oceniane w tym samym kontekście Lua, a zmienne globalne są widoczne wszędzie. Jeśli opcja nie jest ustawiona, silnik wykonuje skrypty, skrypty GUI i skrypt renderowania w osobnych kontekstach. +Wszystkie deklarowane zmienne są domyślnie globalne, co oznacza, że są dostępne we wszystkich częściach kontekstu uruchomieniowego Lua (ang. Lua runtime context). W pliku *game.project* znajduje się opcja *shared_state*, która steruje tym zachowaniem. Jeśli jest włączona, wszystkie skrypty, skrypty GUI i skrypt renderowania są wykonywane w tym samym kontekście Lua, a zmienne globalne są widoczne wszędzie. Jeśli jest wyłączona, silnik wykonuje skrypty, skrypty GUI i skrypt renderowania w osobnych kontekstach. ![Contexts](images/lua/lua_contexts.png) diff --git a/docs/pl/manuals/mesh.md b/docs/pl/manuals/mesh.md index 307205e1..33fa3f8f 100644 --- a/docs/pl/manuals/mesh.md +++ b/docs/pl/manuals/mesh.md @@ -1,56 +1,56 @@ --- -title: Komponent Mesh w Defoldzie -brief: Ta instrukcja opisuje jak działają komponenty typu Mesh służące do wyśweitlania obiektów 3D. +title: Siatki 3D w Defold +brief: Ta instrukcja opisuje, jak tworzyć siatki 3D w czasie działania gry. --- -# Komponent Mesh (Siatka) +# Komponent Mesh -Defold to od podstaw silnik 3D. Nawet w przypadku pracy tylko z materiałem 2D, całe renderowanie jest wykonywane w 3D, ale rzutowane ortograficznie na ekran. Defold pozwala na korzystanie z pełnej zawartości 3D poprzez dodawanie i tworzenie komponentów 3D w czasie wykonywania w kolekcjach. Możesz tworzyć gry w czystym 3D, korzystając tylko z aktywów 3D, lub mieszać zawartość 3D i 2D według własnych preferencji. Komponent typu Mesh - Siatka jest jednym z komponentów do obsługi elementów trójwymiarowych. +Defold jest w swojej istocie silnikiem 3D. Nawet gdy pracujesz wyłącznie z materiałami 2D, całe renderowanie odbywa się w 3D, a następnie jest rzutowane ortograficznie na ekran. Defold pozwala korzystać z pełnej zawartości 3D przez dodawanie i tworzenie siatek 3D w czasie działania w kolekcjach. Możesz tworzyć gry całkowicie trójwymiarowe albo dowolnie łączyć zawartość 3D i 2D. -## Tworzenie komponentu Siatki +## Tworzenie komponentu Mesh -Komponenty Siatki - mesh są tworzone tak samo jak każdy inny komponent obiektu gry. Możesz to zrobić na dwa sposoby: +Komponenty Mesh tworzy się tak samo jak inne komponenty obiektów gry. Można to zrobić na dwa sposoby: -- Utwórz plik Mesh klikając prawym przyciskiem myszy w lokalizacji w panelu *Assets* i wybierając New... ▸ Mesh. -- Utwórz komponent osadzony bezpośrednio w obiekcie gry klikając prawym przyciskiem myszy na obiekcie gry w panelu *Outline* i wybierając Add Component ▸ Mesh. +- Utwórz plik *Mesh* przez kliknięcie prawym przyciskiem myszy w wybranym miejscu panelu *Assets* i wybranie New... ▸ Mesh. +- Utwórz komponent osadzony bezpośrednio w obiekcie gry przez kliknięcie prawym przyciskiem myszy obiektu gry w widoku *Outline* i wybranie Add Component ▸ Mesh. -![Mesh w obiekcie gry](images/mesh/mesh.png) +![Mesh in game object](images/mesh/mesh.png) -Po utworzeniu Siatki musisz określić szereg właściwości (properties): +Po utworzeniu siatki musisz ustawić kilka właściwości: -### Właściwości Siatki +### Właściwości komponentu Mesh -Oprócz właściwości *Id*, *Position* i *Rotation* istnieją następujące właściwości specyficzne dla komponentu typu Mesh: +Poza właściwościami *Id*, *Position* i *Rotation* dostępne są następujące właściwości specyficzne dla tego komponentu: *Material* -: Materiał do użycia podczas renderowania Siatki trójwymiarowej. +: Materiał używany do renderowania siatki. *Vertices* -: Plik bufora opisujący dane Siatki dla strumienia. +: Plik bufora opisujący dane siatki dla poszczególnych strumieni. *Primitive Type* -: Typ prymitywu: Linie, Trójkąty lub Trójkąty Strip (Lines, Triangles or Triangle Strip). +: Linie, Triangles albo Triangle Strip. *Position Stream* -: Strumień pozycji - ta właściwość powinna zawierać nazwę strumienia *position*. Strumień jest automatycznie dostarczany jako wejście do vertex shadera (shadera wierzchołków). +: Nazwa strumienia *position*. Ten strumień jest automatycznie przekazywany do vertex shadera. *Normal Stream* -: Strumień normalnych - ta właściwość powinna zawierać nazwę strumienia *normal*. Strumień jest automatycznie dostarczany jako wejście do vertex shadera. +: Nazwa strumienia *normal*. Ten strumień jest automatycznie przekazywany do vertex shadera. *tex0* -: Ustaw to na teksturę do użycia na siatce. +: Tekstura używana przez siatkę. -## Manipulacja w Edytorze +## Edycja w edytorze -Dzięki komponentowi typu Mesh możesz swobodnie edytować i manipulować komponentem i/lub otaczającym obiektem gry za pomocą standardowych narzędzi Edytora sceny (*Scene Editor*), aby dostosować pozycję, obrót i skalowanie Siatki według swojego uznania. +Po dodaniu komponentu Mesh możesz edytować i przekształcać zarówno sam komponent, jak i obiekt gry, który go zawiera, za pomocą standardowych narzędzi *Scene Editor*, aby przesuwać, obracać i skalować siatkę według potrzeb. -## Manipulacja w czasie rzeczywistym +## Modyfikacja w czasie działania -Możesz manipulować meshami w czasie wykonania programu, korzystając z buforów Defolda. Oto przykład tworzenia sześcianu z pasów trójkątów: +Siatki można modyfikować w czasie działania przy użyciu buforów Defold. Przykład utworzenia sześcianu z pasów trójkątów: ```Lua --- definicja wierzchołków sześcianu +-- sześcian local vertices = { 0, 0, 0, 0, 1, 0, @@ -68,7 +68,7 @@ local vertices = { 0, 1, 0 } --- utwórz bufor z danymi pozycji +-- utwórz bufor ze strumieniem pozycji local buf = buffer.create(#vertices / 3, { { name = hash("position"), type=buffer.VALUE_TYPE_FLOAT32, count = 3 } }) @@ -79,29 +79,30 @@ for i, value in ipairs(vertices) do positions[i] = vertices[i] end --- ustaw bufor z wierzchołkami w siatce +-- ustaw bufor z wierzchołkami w komponencie Mesh local res = go.get("#mesh", "vertices") resource.set_buffer(res, buf) ``` -Aby uzyskać więcej informacji na temat korzystania z komponentu Mesh, w tym projektów przykładowych i fragmentów kodu, zapoznaj się z [postem ogłoszeniowym na forum](https://forum.defold.com/t/mesh-component-in-defold-1-2-169-beta/65137. +Więcej informacji o korzystaniu z komponentu Mesh, wraz z przykładowymi projektami i fragmentami kodu, znajdziesz w [poście ogłoszeniowym na forum](https://forum.defold.com/t/mesh-component-in-defold-1-2-169-beta/65137). ## Frustum culling -Frustum culling, czyli odrzucanie widoku spoza bryły widoku to funkcjonalność pozwalająca usuwać powierzchnie spoza widoku określonego przez specjalną bryłę (frustum) w celu zyskiwaniu na szybkości renderowania. Komponenty typu Mesh nie są automatycznie odrzucane ze względu na ich dynamiczną naturę i fakt, że niemożliwe jest dokładne ustalenie, w jaki sposób dane pozycyjne są kodowane. Aby odrzucić mesh, należy ustawić prostopadłościenne obramowanie otaczające mesh jako metadane w buforze za pomocą 6 liczb zmiennoprzecinkowych (AABB min/max): +Komponenty Mesh nie są automatycznie odrzucane, ponieważ mają dynamiczny charakter i nie da się jednoznacznie określić, jak zakodowano dane pozycyjne. Aby włączyć odrzucanie siatki, trzeba zapisać w metadanych bufora ograniczający ją axis-aligned bounding box za pomocą 6 liczb zmiennoprzecinkowych (AABB min/max): ```lua buffer.set_metadata(buf, hash("AABB"), { 0, 0, 0, 1, 1, 1 }, buffer.VALUE_TYPE_FLOAT32) ``` -## Stałe materiałowe +## Stałe materiału {% include shared/material-constants.md component='mesh' variable='tint' %} `tint` -: odcień/barwa Siatki (typu `vector4`). Wektor 4-składnikowy jest używany do reprezentowania odcienia z X, Y, Z i W odpowiadającymi kolorami czerwonym, zielonym, niebieskim i alfa (przezroczystości). +: Odcień koloru siatki (`vector4`). Wektor `vector4` reprezentuje odcień, gdzie `x`, `y`, `z` i `w` odpowiadają odpowiednio kanałom czerwieni, zieleni, błękitu i alfa. -## Przestrzeń wierzchołkowa lokalna a przestrzeń świata -Jeśli ustawienia Przestrzeni wierzchołka (Vertex Space setting) materiału Siatki są ustawione na Przestrzeń lokalną (vertex local space), dane zostaną dostarczone do shadera w postaci, w jakiej są, i będziesz musiał przekształcać wierzchołki/normalne na GPU, tak jak zwykle. +## Lokalna przestrzeń wierzchołków a przestrzeń świata -Jeśli ustawienia Przestrzeni wierzchołka materiału meshu są ustawione na Przestrzeń świata (world space), musisz albo dostarczyć domyślny strumień "position" i "normal", albo wybrać go z listy rozwijanej podczas edycji Siatki. Ma to na celu przekształcenie danych do przestrzeni świata w celu ich grupowania z innymi obiektami. +Jeśli ustawienie *Vertex Space* materiału siatki ma wartość *Local Space*, dane zostaną przekazane do shadera bez zmian i musisz samodzielnie przekształcać wierzchołki oraz normalne na GPU, tak jak zwykle. + +Jeśli ustawienie *Vertex Space* materiału siatki ma wartość *World Space*, musisz albo dostarczyć domyślny strumień `position` i `normal`, albo wybrać go z listy rozwijanej podczas edycji siatki. Dzięki temu silnik może przekształcić dane do przestrzeni świata i batchować je razem z innymi obiektami. diff --git a/docs/pl/manuals/physics-joints.md b/docs/pl/manuals/physics-joints.md index a5e81f46..ab1c5804 100644 --- a/docs/pl/manuals/physics-joints.md +++ b/docs/pl/manuals/physics-joints.md @@ -1,55 +1,57 @@ --- -title: Łączenia fizyczne w Defoldzie -brief: Defold supports joints for 2D physics. This manual explains how to create and work with joints. +title: Łączenia fizyczne w Defold +brief: Defold obsługuje łączenia dla fizyki 2D. Ta instrukcja wyjaśnia, jak je tworzyć i jak z nimi pracować. --- -# Łączenia fizyczne (Joints) +# Łączenia -Defold obsługuje łączenia (ang. joints) w fizyce 2D. Łączenie łączy ze sobą dwa obiekty kolizji za pomocą wybranego rodzaju ograniczenia. Obsługiwane rodzaje połączeń to: +Defold obsługuje łączenia w fizyce 2D. Łączenie łączy dwa obiekty kolizji za pomocą określonego ograniczenia. Obsługiwane typy łączeń to: -* **Fixed (physics.JOINT_TYPE_FIXED)** - łączenie stałe, które ogranicza maksymalną odległość między dwoma punktami. W Box2D jest to znane jako połączenie "lina" (ang. rope joint). -* **Hinge (physics.JOINT_TYPE_HINGE)** - łączenie zawiasowe/osi określa punkt kotwiczenia na dwóch obiektach kolizji i przesuwa je tak, aby obiekty były zawsze w tym samym miejscu, a względna rotacja obiektów kolizyjnych nie była ograniczona. Łączenie zawiasowe można łączyć ze specjalnym silnikiem (ang. motor) zdefiniowanym z maksymalnym momentem obrotowym i prędkością, co umożliwia przykładowo stworzenie koła pojazdu. W Box2D jest to znane jako połączenie obrotowe (ang. revolute joint). -* **Weld (physics.JOINT_TYPE_WELD)** - łączenie spawane stara się ograniczyć wszelkie względne ruchy między dwoma obiektami kolizyji. Łączenie spawane można zrobić miękkie jak sprężyna z częstotliwością i współczynnikiem tłumienia. W Box2D jest to znane również jako połączenie spawane (ang. weld joint). -* **Spring (physics.JOINT_TYPE_SPRING)** - łączenie sprężynowe utrzymuje dwa obiekty kolizyjne w stałej odległości od siebie. Połączenie sprężyny można zrobić miękkie jak sprężyna z częstotliwością i współczynnikiem tłumienia. W Box2D jest znane jako połączenie dystansowe (ang. distance joint). -* **Slider (physics.JOINT_TYPE_SLIDER)** - łączenie przesuwne/suwaka umożliwia względną translację dwóch obiektów kolizji wzdłuż określonej osi i zapobiega względnej rotacji. W Box2D jest znane jako połączenie pryzmatyczne (ang. prismatic joint). +* **Fixed (physics.JOINT_TYPE_FIXED)** - Łączenie linowe ograniczające maksymalną odległość między dwoma punktami. W Box2D nazywa się Rope joint. +* **Hinge (physics.JOINT_TYPE_HINGE)** - Łączenie zawiasowe określa punkt zakotwiczenia na dwóch obiektach kolizji i przesuwa je tak, aby oba obiekty zawsze znajdowały się w tym samym miejscu, przy czym ich względny obrót nie jest ograniczony. Łączenie zawiasowe może włączyć motor o określonym maksymalnym momencie obrotowym i prędkości. W Box2D odpowiada [Revolute joint](https://box2d.org/documentation/group__revolute__joint.html#details). +* **Weld (physics.JOINT_TYPE_WELD)** - Łączenie spawane próbuje ograniczyć cały względny ruch między dwoma obiektami kolizji. Może być zmiękczone jak sprężyna dzięki częstotliwości i współczynnikowi tłumienia. W Box2D odpowiada [Weld joint](https://box2d.org/documentation/group__weld__joint.html#details). +* **Spring (physics.JOINT_TYPE_SPRING)** - Łączenie sprężynowe utrzymuje dwa obiekty kolizji w stałej odległości od siebie. Także może być zmiękczone jak sprężyna dzięki częstotliwości i współczynnikowi tłumienia. W Box2D odpowiada [Distance joint](https://box2d.org/documentation/group__distance__joint.html#details). +* **Slider (physics.JOINT_TYPE_SLIDER)** - Łączenie przesuwne pozwala na względne przesunięcie dwóch obiektów kolizji wzdłuż wskazanej osi i zapobiega ich względnemu obrotowi. W Box2D odpowiada [Prismatic joint](https://box2d.org/documentation/group__prismatic__joint.html#details). +* **Wheel (physics.JOINT_TYPE_WHEEL)** - Łączenie koła ogranicza punkt na `bodyB` do linii na `bodyA`. Zapewnia też sprężynę zawieszenia. W Box2D odpowiada [Wheel joint](https://box2d.org/documentation/group__wheel__joint.html#details). -## Tworzenie połączeń +## Tworzenie łączeń -Obecnie połączenia można tworzyć tylko programowo za pomocą funkcji [`physics.create_joint()`](/ref/physics/#physics.create_joint:joint_type-collisionobject_a-joint_id-position_a-collisionobject_b-position_b-[properties]): +Łączenia można obecnie tworzyć tylko programowo za pomocą [`physics.create_joint()`](/ref/physics/#physics.create_joint:joint_type-collisionobject_a-joint_id-position_a-collisionobject_b-position_b-[properties]): ::: sidenote -Wsparcie Edytora do tworzenia połączeń jest planowane, ale nie ustalono jeszcze daty wydania. +Obsługa tworzenia łączeń w edytorze jest planowana, ale nie ustalono jeszcze daty wydania. ::: ```lua --- połącz dwa obiekty kolizyjne za pomocą połączenia liny (fixed joint) +-- połącz dwa obiekty kolizji za pomocą stałego ograniczenia łączenia (rope) physics.create_joint(physics.JOINT_TYPE_FIXED, "obj_a#collisionobject", "my_test_joint", vmath.vector3(10, 0, 0), "obj_b#collisionobject", vmath.vector3(0, 20, 0), { max_length = 20 }) ``` -Powyższy kod utworzy stałe połączenie o identyfikatorze `my_test_joint`, połączone między dwoma obiektami kolizyjnymi `obj_a#collisionobject` i `obj_b#collisionobject`. Połączenie jest ustanowione 10 pikseli na lewo od środka obiektu kolizyjnego `obj_a#collisionobject` i 20 pikseli nad środkiem obiektu kolizyjnego `obj_b#collisionobject`. Maksymalna długość połączenia wynosi 20 pikseli. +Powyższy przykład tworzy łączenie typu Fixed o id `my_test_joint` pomiędzy obiektami kolizji `obj_a#collisionobject` i `obj_b#collisionobject`. Łączenie jest umieszczone 10 pikseli na lewo od środka `obj_a#collisionobject` i 20 pikseli nad środkiem `obj_b#collisionobject`. Maksymalna długość łączenia wynosi 20 pikseli. -## Niszczenie połączeń +## Niszczenie łączeń -Połączenie można zniszczyć za pomocą funkcji [`physics.destroy_joint()`](/ref/physics/#physics.destroy_joint:collisionobject-joint_id): +Łączenie można zniszczyć za pomocą [`physics.destroy_joint()`](/ref/physics/#physics.destroy_joint:collisionobject-joint_id): ```lua --- zniszcz połączenie, które było wcześniej podłączone do pierwszego obiektu kolizyjnego +-- zniszcz łączenie wcześniej podłączone do pierwszego obiektu kolizji physics.destroy_joint("obj_a#collisionobject", "my_test_joint") ``` -## Odczytywanie i aktualizowanie połączeń +## Odczyt i aktualizacja łączeń -Właściwości połączenia można odczytać za pomocą funkcji [`physics.get_joint_properties()`](/ref/physics/#physics.get_joint_properties:collisionobject-joint_id) i ustawić za pomocą funkcji [`physics.set_joint_properties()`](/ref/physics/#physics.set_joint_properties:collisionobject-joint_id-properties): +Właściwości łączenia można odczytać przez [`physics.get_joint_properties()`](/ref/physics/#physics.get_joint_properties:collisionobject-joint_id), a ustawić przez [`physics.set_joint_properties()`](/ref/physics/#physics.set_joint_properties:collisionobject-joint_id-properties): ```lua function update(self, dt) if self.accelerating then local hinge_props = physics.get_joint_properties("obj_a#collisionobject", "my_hinge") - -- zwiększ prędkość silnika o 100 obrotów na sekundę + -- zwiększ prędkość motoru o 100 obrotów na sekundę hinge_props.motor_speed = hinge_props.motor_speed + 100 * 2 * math.pi * dt physics.set_joint_properties("obj_a#collisionobject", "my_hinge", hinge_props) end end ``` -## Odczytywanie siły i momentu reakcji połączenia -Siłę reakcji i moment reakcji, które zostały zastosowane do połączenia, można odczytać za pomocą funkcji odpowiednio [`physics.get_joint_reaction_force()`](/ref/physics/#physics.get_joint_reaction_force:collisionobject-joint_id) i [`physics.get_joint_reaction_torque()`](/ref/physics/#physics.get_joint_reaction_torque:collisionobject-joint_id). +## Odczyt siły i momentu reakcji łączenia + +Siłę reakcji i moment reakcji działające na łączenie można odczytać funkcjami [`physics.get_joint_reaction_force()`](/ref/physics/#physics.get_joint_reaction_force:collisionobject-joint_id) oraz [`physics.get_joint_reaction_torque()`](/ref/physics/#physics.get_joint_reaction_torque:collisionobject-joint_id). diff --git a/docs/pl/manuals/property-animation.md b/docs/pl/manuals/property-animation.md index 3978923a..8a29d886 100644 --- a/docs/pl/manuals/property-animation.md +++ b/docs/pl/manuals/property-animation.md @@ -1,109 +1,109 @@ --- title: Animacja właściwości -brief: Ta instrukcja opisuje wsparcie dla animacji właściwości w silniku Defold. +brief: Ta instrukcja opisuje, jak używać animacji właściwości w silniku Defold. --- # Animacja właściwości -Wszystkie właściwości (ang. properties) będące zmiennymi numerycznymi (typy Lua: numbers, vector3, vector4 i quaterions (kwaterniony)) oraz stałe shaderów mogą być animowane w Defoldzie wykorzystując wbudowany system animacji, używając funkcji `go.animate()`. Silnik będzie automatycznie dopasowywał wartość (ang. tween) uwzględniając wybrany tryb odtwarzania (playback mode) i funkcję wygładzania (easing function). Można również definiować własne funkcje wygładzania. +Wszystkie właściwości liczbowe, czyli `number`, `vector3`, `vector4` i kwaterniony, a także stałe shaderów, można animować za pomocą wbudowanego systemu animacji i funkcji `go.animate()`. Silnik automatycznie interpoluje wartości zgodnie z wybranym trybem odtwarzania i funkcją easing. Możesz też definiować własne funkcje easing. ![Property animation](images/animation/property_animation.png) ![Bounce loop](images/animation/bounce.gif) -## Animowanie właściwości +## Animacja właściwości -Aby animować właściwości (ang. properties) obiektu lub komponentu użyj funkcji `go.animate()`. Dla właściwości węzłów GUI, analogiczną funkcją jest `gui.animate()`. +Aby animować właściwość obiektu gry albo komponentu, użyj `go.animate()`. W przypadku właściwości węzłów GUI odpowiednikiem jest `gui.animate()`. ```lua --- Ustaw pozycję w osi Y - właściwość komponentu na 200 +-- Ustaw składową y właściwości position na 200 go.set(".", "position.y", 200) --- Następnie przeprowadź animację właściwości do 100 i z powrotem +-- Następnie ją animuj go.animate(".", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, go.EASING_OUTBOUNCE, 2) ``` -Aby zatrzymać wszystkie animacje danej właściwości, wywołaj `go.cancel_animations()`, a dla węzłów GUI, analogicznie: `gui.cancel_animation()` lub dookreśl, które właściwości chcesz zatrzymać: +Aby zatrzymać wszystkie animacje danej właściwości, wywołaj `go.cancel_animations()`, a dla węzłów GUI `gui.cancel_animation()`: ```lua --- Zatrzymaj rotację eulera na osi Z obecnego obiektu gry +-- Zatrzymaj animację obrotu euler.z bieżącego obiektu gry go.cancel_animations(".", "euler.z") ``` -Jeśli zatrzymasz animacje właściwości, która jest właściwością "kompozytową" (składającą się z kilku osobnych wartości, jak np. `vector3 position`), osobne animacje każdego z elementów składowych danej właściwości (`position.x`, `position.y` i `position.z`) zostaną zatrzymane. +Jeśli anulujesz animację właściwości złożonej, takiej jak `position`, anulowane zostaną również animacje jej składowych, czyli `position.x`, `position.y` i `position.z`. -[Instrukcja do właściwości](/manuals/properties) zawiera wszystkie informacje na temat dostępnych właściwości obiektów, komponentów i węzłów GUI. +[Instrukcja o właściwościach](/manuals/properties) zawiera listę wszystkich dostępnych właściwości obiektów gry, komponentów i węzłów GUI. -## Animowanie właściwości węzłów GUI +## Animacja właściwości węzłów GUI -Prawie każdą właściwość węzła GUI można animować. Możesz, przykładowo, ukryć węzeł poprzez ustawienie jego koloru (`color`) na całkowicie przezroczysty, a następnie pokazać go przez płynne pojawianie się animując kolor do wartości koloru białego (nieprzezroczystego): +Prawie wszystkie właściwości węzłów GUI można animować. Możesz na przykład ukryć węzeł, ustawiając jego właściwość `color` na pełną przezroczystość, a następnie płynnie go wyświetlić, animując kolor do bieli, czyli bez dodatkowego zabarwienia. ```lua local node = gui.get_node("button") local color = gui.get_color(node) --- Animuj kolor do białego +-- Animuj kolor do bieli gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5) --- Animuj kolor obrzeży do czerwonego +-- Animuj czerwony składnik koloru obramowania gui.animate(node, "outline.x", 1, gui.EASING_INOUTQUAD, 0.5) --- I animuj pozycję wzdłuż osi X do 100 +-- I przesuń do pozycji x równej 100 gui.animate(node, hash("position.x"), 100, gui.EASING_INOUTQUAD, 0.5) ``` -## Funkcje po zakończeniu animacji +## Callbacki zakończenia -Funkcje do animacji właściwości `go.animate()` i `gui.animate()` wspierają opcjonalną funkcję tzw. callback jako ostatni argument. Funkcja ta zostanie wywołana po zakończeniu animacji. Funkcja nigdy nie jest wywoływana dla animacji w pętli, więc takich, których tryby odtwarzania zaczynają się od: `PLAYBACK_LOOP_*`, ani w przypadku ręcznego anulowania animacji za pomocą `go.cancel_animations()`. Funkcję zwrotną można wykorzystać do wyzwalania zdarzeń po zakończeniu animacji lub do połączenia różnych animacji w serie, jedna za drugą. +Funkcje animacji właściwości `go.animate()` i `gui.animate()` obsługują opcjonalną funkcję callback jako ostatni argument. Zostanie ona wywołana po zakończeniu animacji. Callback nigdy nie jest wywoływany dla animacji zapętlonych ani wtedy, gdy animacja została ręcznie anulowana przez `go.cancel_animations()` lub `gui.cancel_animation()`. Można go używać do wyzwalania zdarzeń po zakończeniu animacji albo do łączenia kilku animacji w sekwencję. -## Wygładzanie +## Easing -Wygładzanie (ang. easing) określa w jaki sposób animowana będzie wartość w czasie. Poniżej zaprezentowano wykresy funkcji wygładzania przedstawiające wartość w czasie. +Easing określa, jak animowana wartość zmienia się w czasie. Poniższe obrazy pokazują funkcje używane do tworzenia poszczególnych krzywych easing. -Tutaj przedstawione są funkcje wygładzania dostępne dla funkcji `go.animate()`: +Poniżej znajdują się poprawne wartości easing dla `go.animate()`: |---|---| -| go.EASING_LINEAR | | -| go.EASING_INBACK | go.EASING_OUTBACK | -| go.EASING_INOUTBACK | go.EASING_OUTINBACK | -| go.EASING_INBOUNCE | go.EASING_OUTBOUNCE | -| go.EASING_INOUTBOUNCE | go.EASING_OUTINBOUNCE | -| go.EASING_INELASTIC | go.EASING_OUTELASTIC | -| go.EASING_INOUTELASTIC | go.EASING_OUTINELASTIC | -| go.EASING_INSINE | go.EASING_OUTSINE | -| go.EASING_INOUTSINE | go.EASING_OUTINSINE | -| go.EASING_INEXPO | go.EASING_OUTEXPO | -| go.EASING_INOUTEXPO | go.EASING_OUTINEXPO | -| go.EASING_INCIRC | go.EASING_OUTCIRC | -| go.EASING_INOUTCIRC | go.EASING_OUTINCIRC | -| go.EASING_INQUAD | go.EASING_OUTQUAD | -| go.EASING_INOUTQUAD | go.EASING_OUTINQUAD | -| go.EASING_INCUBIC | go.EASING_OUTCUBIC | -| go.EASING_INOUTCUBIC | go.EASING_OUTINCUBIC | -| go.EASING_INQUART | go.EASING_OUTQUART | -| go.EASING_INOUTQUART | go.EASING_OUTINQUART | -| go.EASING_INQUINT | go.EASING_OUTQUINT | -| go.EASING_INOUTQUINT | go.EASING_OUTINQUINT | - -Tutaj przedstawione są funkcje wygładzania dostępne dla funkcji `gui.animate()`: +| `go.EASING_LINEAR` | | +| `go.EASING_INBACK` | `go.EASING_OUTBACK` | +| `go.EASING_INOUTBACK` | `go.EASING_OUTINBACK` | +| `go.EASING_INBOUNCE` | `go.EASING_OUTBOUNCE` | +| `go.EASING_INOUTBOUNCE` | `go.EASING_OUTINBOUNCE` | +| `go.EASING_INELASTIC` | `go.EASING_OUTELASTIC` | +| `go.EASING_INOUTELASTIC` | `go.EASING_OUTINELASTIC` | +| `go.EASING_INSINE` | `go.EASING_OUTSINE` | +| `go.EASING_INOUTSINE` | `go.EASING_OUTINSINE` | +| `go.EASING_INEXPO` | `go.EASING_OUTEXPO` | +| `go.EASING_INOUTEXPO` | `go.EASING_OUTINEXPO` | +| `go.EASING_INCIRC` | `go.EASING_OUTCIRC` | +| `go.EASING_INOUTCIRC` | `go.EASING_OUTINCIRC` | +| `go.EASING_INQUAD` | `go.EASING_OUTQUAD` | +| `go.EASING_INOUTQUAD` | `go.EASING_OUTINQUAD` | +| `go.EASING_INCUBIC` | `go.EASING_OUTCUBIC` | +| `go.EASING_INOUTCUBIC` | `go.EASING_OUTINCUBIC` | +| `go.EASING_INQUART` | `go.EASING_OUTQUART` | +| `go.EASING_INOUTQUART` | `go.EASING_OUTINQUART` | +| `go.EASING_INQUINT` | `go.EASING_OUTQUINT` | +| `go.EASING_INOUTQUINT` | `go.EASING_OUTINQUINT` | + +Poniżej znajdują się poprawne wartości easing dla `gui.animate()`: |---|---| -| gui.EASING_LINEAR | | -| gui.EASING_INBACK | gui.EASING_OUTBACK | -| gui.EASING_INOUTBACK | gui.EASING_OUTINBACK | -| gui.EASING_INBOUNCE | gui.EASING_OUTBOUNCE | -| gui.EASING_INOUTBOUNCE | gui.EASING_OUTINBOUNCE | -| gui.EASING_INELASTIC | gui.EASING_OUTELASTIC | -| gui.EASING_INOUTELASTIC | gui.EASING_OUTINELASTIC | -| gui.EASING_INSINE | gui.EASING_OUTSINE | -| gui.EASING_INOUTSINE | gui.EASING_OUTINSINE | -| gui.EASING_INEXPO | gui.EASING_OUTEXPO | -| gui.EASING_INOUTEXPO | gui.EASING_OUTINEXPO | -| gui.EASING_INCIRC | gui.EASING_OUTCIRC | -| gui.EASING_INOUTCIRC | gui.EASING_OUTINCIRC | -| gui.EASING_INQUAD | gui.EASING_OUTQUAD | -| gui.EASING_INOUTQUAD | gui.EASING_OUTINQUAD | -| gui.EASING_INCUBIC | gui.EASING_OUTCUBIC | -| gui.EASING_INOUTCUBIC | gui.EASING_OUTINCUBIC | -| gui.EASING_INQUART | gui.EASING_OUTQUART | -| gui.EASING_INOUTQUART | gui.EASING_OUTINQUART | -| gui.EASING_INQUINT | gui.EASING_OUTQUINT | -| gui.EASING_INOUTQUINT | gui.EASING_OUTINQUINT | +| `gui.EASING_LINEAR` | | +| `gui.EASING_INBACK` | `gui.EASING_OUTBACK` | +| `gui.EASING_INOUTBACK` | `gui.EASING_OUTINBACK` | +| `gui.EASING_INBOUNCE` | `gui.EASING_OUTBOUNCE` | +| `gui.EASING_INOUTBOUNCE` | `gui.EASING_OUTINBOUNCE` | +| `gui.EASING_INELASTIC` | `gui.EASING_OUTELASTIC` | +| `gui.EASING_INOUTELASTIC` | `gui.EASING_OUTINELASTIC` | +| `gui.EASING_INSINE` | `gui.EASING_OUTSINE` | +| `gui.EASING_INOUTSINE` | `gui.EASING_OUTINSINE` | +| `gui.EASING_INEXPO` | `gui.EASING_OUTEXPO` | +| `gui.EASING_INOUTEXPO` | `gui.EASING_OUTINEXPO` | +| `gui.EASING_INCIRC` | `gui.EASING_OUTCIRC` | +| `gui.EASING_INOUTCIRC` | `gui.EASING_OUTINCIRC` | +| `gui.EASING_INQUAD` | `gui.EASING_OUTQUAD` | +| `gui.EASING_INOUTQUAD` | `gui.EASING_OUTINQUAD` | +| `gui.EASING_INCUBIC` | `gui.EASING_OUTCUBIC` | +| `gui.EASING_INOUTCUBIC` | `gui.EASING_OUTINCUBIC` | +| `gui.EASING_INQUART` | `gui.EASING_OUTQUART` | +| `gui.EASING_INOUTQUART` | `gui.EASING_OUTINQUART` | +| `gui.EASING_INQUINT` | `gui.EASING_OUTQUINT` | +| `gui.EASING_INOUTQUINT` | `gui.EASING_OUTINQUINT` | ![Linear interpolation](images/properties/easing_linear.png) ![In back](images/properties/easing_inback.png) @@ -147,22 +147,22 @@ Tutaj przedstawione są funkcje wygładzania dostępne dla funkcji `gui.animate( ![In-out quintic](images/properties/easing_inoutquint.png) ![Out-in quintic](images/properties/easing_outinquint.png) -## Własne funkcje wygładzania +## Własne funkcje easing -Możesz tworzyć własne funkcje wygładzania zdefiniowane jako specjalny `vector` ze zbiorem odpowiednich, kolejnych wartości i użyć go zamiast predefiniowanych stałych przedstawionych powyżej. Wektor ten reprezentuje krzywą zmiany wartości numerycznej od wartości startowej (`0`) do wartości końcowej (`1`). Silnik interpoluje w czasie działania programu te wartości liniowo. +Możesz tworzyć własne krzywe easing, definiując `vector` z zestawem wartości i przekazując go zamiast jednej z predefiniowanych stałych easing opisanych wyżej. Wartości wektora opisują krzywą od wartości początkowej (`0`) do wartości docelowej (`1`). W czasie działania silnik próbuje próbki z wektora i liniowo interpoluje wartości pomiędzy punktami opisanymi w tym wektorze. -For example, the vector: +Na przykład taki wektor: ```lua local values = { 0, 0.4, 0.2, 0.2, 0.5, 1 } local my_easing = vmath.vector(values) ``` -stworzy następującą krzywą: +da następującą krzywą: ![Custom curve](images/animation/custom_curve.png) -W poniższym przykładzie wartość y pozycji obiektu skacze między aktualną pozycją startową, a pozycją docelową 200: +W kolejnym przykładzie pozycja `y` obiektu gry będzie przeskakiwać między bieżącą pozycją a wartością `200` zgodnie z przebiegiem przypominającym falę prostokątną: ```lua local values = { 0, 0, 0, 0, 0, 0, 0, 0, diff --git a/docs/pl/manuals/resource.md b/docs/pl/manuals/resource.md index 77863c8c..2804221e 100644 --- a/docs/pl/manuals/resource.md +++ b/docs/pl/manuals/resource.md @@ -1,63 +1,67 @@ --- -title: Zarządzanie zasobami w Defoldzie -brief: Ta instrukcja wyjaśnia jak Defold automatycznie zarządza zasobami i jak można rędzie to robić. +title: Zarządzanie zasobami w Defold +brief: Ta instrukcja wyjaśnia, jak Defold automatycznie zarządza zasobami i jak ręcznie sterować ich ładowaniem, by pilnować zużycia pamięci oraz rozmiaru bundla. --- # Zarządzanie zasobami -Jeśli tworzysz bardzo małą grę, ograniczenia platformy docelowej (rozmiar pamięci, rozmiar paczki, moc obliczeniowa i zużycie baterii) mogą nigdy nie stanowić problemu. Jednak tworząc większe gry, zwłaszcza na urządzeniach przenośnych czy na przeglądarki, zużycie pamięci będzie prawdopodobnie jednym z największych ograniczeń. Doświadczony zespół będzie starannie zarządzać zasobami w oparciu o ograniczenia platformy. Defold dostarcza szereg funkcji do zarządzania pamięcią i rozmiarem paczki. Ta instrukcja pozwala się z nimi zapoznać. +Jeśli tworzysz bardzo małą grę, ograniczenia platformy docelowej, takie jak zużycie pamięci, rozmiar bundla, moc obliczeniowa czy pobór energii, mogą w ogóle nie stanowić problemu. Jednak przy większych grach, szczególnie na urządzeniach mobilnych, zużycie pamięci bywa jednym z najważniejszych ograniczeń. Doświadczony zespół przygotowuje budżety zasobów z uwzględnieniem ograniczeń platformy. Defold udostępnia zestaw funkcji pomagających zarządzać pamięcią i rozmiarem bundla. Ta instrukcja daje ich przegląd. ## Statyczne drzewo zasobów -Podczas tworzenia gry w Defoldzie deklarujesz statycznie drzewo zasobów. Każda część gry jest łączona z drzewem, począwszy od kolekcji rozruchowej (ang. bootrstrap collection), zwykle nazywanej "main.collection". Drzewo zasobów podąża za każdym odniesieniem i zawiera wszystkie zasoby powiązane z tymi odniesieniami: +Podczas budowania gry w Defold statycznie deklarujesz drzewo zasobów. Każdy element gry jest włączony do tego drzewa, począwszy od kolekcji bootstrapowej, zwykle o nazwie `main.collection`. Drzewo zasobów podąża za wszystkimi odwołaniami i zawiera wszystkie zasoby z nimi powiązane: -- Dane obiektów gry (game objects) i komponentów (atlasy, dźwięki itp). -- Prototypy komponentów fabryki (obiekty gry i kolekcje). -- Odniesienia komponentów pełnomocników kolekcji (kolekcje). -- Niestandardowe zasoby deklarowane w *game.project*. +- dane obiektów gry i komponentów, takie jak atlasy czy dźwięki +- prototypy komponentów Factory, czyli obiekty gry i kolekcje +- odwołania komponentów pełnomocników kolekcji +- [Custom Resources](/manuals/project-settings/#custom-resources) zadeklarowane w *game.project* -![Drzewo zasobów](images/resource/resource_tree.png) +![Resource tree](images/resource/resource_tree.png) -Podczas tworzenia i pakowania gry, tylko to, co znajduje się w drzewie zasobów, zostanie uwzględnione w paczce. To, czego nie ma w drzewie, jest pomijane. Nie ma potrzeby ręcznego wybierania, co ma być uwzględnione lub wyłączone z paczki. +::: sidenote +Defold ma też pojęcie [bundle resources](/manuals/project-settings/#bundle-resources). Są one dołączane do bundla aplikacji, ale nie należą do drzewa zasobów. Mogą to być zarówno pliki pomocnicze specyficzne dla platformy, jak i zewnętrzne pliki [wczytywane z systemu plików](/manuals/file-access/#how-to-access-files-bundled-with-the-application) i używane przez grę, na przykład banki dźwięków FMOD. +::: -Podczas *uruchamiania* gry, silnik rozpoczyna działanie od korzenia drzewa rozruchowego (ang. bootstrap root) i ściąga zasoby do pamięci: +Podczas *bundlowania* do gry zostanie dołączone tylko to, co znajduje się w drzewie zasobów. Wszystko, do czego nie prowadzi żadne odwołanie w drzewie, zostanie pominięte. Nie trzeba ręcznie wybierać, co uwzględnić lub wykluczyć. -- Każda kolekcja, do której odniesienie istnieje, wraz z jej zawartością. -- Obiekty gry i dane komponentów. -- Prototypy komponentów fabryki (obiekty gry i kolekcje). +Podczas *uruchamiania* gry silnik startuje od bootstrapowego korzenia drzewa i ładuje zasoby do pamięci: -Defold nie ładuje jednak automatycznie następujących rodzajów odniesionych zasobów podczas działania: +- wszystkie wskazane kolekcje wraz z ich zawartością +- obiekty gry i dane komponentów +- prototypy komponentów Factory -- Kolekcji świata gry, do której odniesienie istnieje przez proxy kolekcji. Światy gry są stosunkowo duże, więc będziesz musiał ręcznie uruchamiać i wyłączać ich ładowanie w kodzie. Zobacz [instrukcję do pełnomocników kolekcji](/manuals/collection-proxy), aby poznać szczegóły. -- Pliki dodane za pomocą ustawienia *Custom Resources* (Niestandardowe zasoby) w *game.project*. Te pliki są ręcznie ładowane za pomocą funkcji [sys.load_resource()](/ref/sys/#sys.load_resource). +Silnik nie ładuje jednak automatycznie następujących typów zasobów wskazanych w drzewie: -Domyślny sposób, w jaki Defold pakuje i ładuje zasoby, można zmienić, aby uzyskać kontrolę nad tym, jak i kiedy zasoby wchodzą do pamięci. +- kolekcji światów gry wskazywanych przez pełnomocników kolekcji; światy gry są relatywnie duże, więc ich ładowanie i zwalnianie trzeba wyzwalać ręcznie w kodzie; szczegóły znajdziesz w [instrukcji Collection proxy](/manuals/collection-proxy) +- plików dodanych przez ustawienie *Custom Resources* w *game.project*; te pliki wczytuje się ręcznie funkcją [`sys.load_resource()`](/ref/sys/#sys.load_resource) -![Wczytywanie zasobów](images/resource/loading.png) +Domyślny sposób bundlowania i ładowania zasobów w Defold można zmieniać, aby precyzyjnie sterować tym, kiedy i jak zasoby trafiają do pamięci. -## Dynamiczne ładowanie zasobów fabryki +![Resource loading](images/resource/loading.png) -Zasoby odniesione przez komponenty fabryki (ang. factory components) są zazwyczaj ładowane do pamięci, w momencie, gdy komponent jest ładowany. Zasoby są gotowe do użycia w grze, zanim fabryka zostanie utworzona w czasie działania. Aby zmienić domyślne zachowanie i opóźnić ładowanie zasobów fabryki, można po prostu zaznaczyć w właściwościach fabryki opcję *Load Dynamically* (Ładuj dynamicznie). +## Dynamiczne ładowanie zasobów Factory -![Opcja Ładuj dynamicznie](images/resource/load_dynamically.png) +Zasoby wskazywane przez komponenty Factory są zwykle ładowane do pamięci razem z samym komponentem. Dzięki temu są gotowe do użycia od razu, gdy Factory istnieje w czasie działania. Aby zmienić to zachowanie i odroczyć ładowanie zasobów Factory, zaznacz pole *Load Dynamically*. -Zaznaczenie tej opcji spowoduje, że silnik wciąż zawierać będzie odniesione zasoby w paczce gry, ale nie załaduje ich automatycznie. Zamiast tego masz dwie opcje: +![Load dynamically](images/resource/load_dynamically.png) -1. Wywołać funckję [`factory.create()`](/ref/factory/#factory.create) lub [`collectionfactory.create()`](/ref/collectionfactory/#collectionfactory.create), gdy chcesz tworzyć obiekty. To spowoduje synchroniczne ładowanie zasobów, a następnie tworzenie nowych instancji. -2. Wywołać funckję [`factory.load()`](/ref/factory/#factory.load) lub [`collectionfactory.load()`](/ref/collectionfactory/#collectionfactory.load), aby asynchronicznie ładować zasoby. Gdy zasoby będą gotowe do tworzenia, zostanie odebrane odpowiednie wywołanie zwrotne (callback). +Po zaznaczeniu tego pola silnik nadal dołączy wskazane zasoby do bundla gry, ale nie załaduje ich automatycznie. Zamiast tego masz dwie możliwości: -Zobacz [instrukcję do fabryk](/manuals/factory) i [instrukcję do fabryk kolekcji](/manuals/collection-factory) po szczegóły dotyczące działania tych opcji. +1. Wywołaj [`factory.create()`](/ref/factory/#factory.create) albo [`collectionfactory.create()`](/ref/collectionfactory/#collectionfactory.create), gdy chcesz tworzyć obiekty. Spowoduje to synchroniczne załadowanie zasobów, a następnie utworzenie nowych instancji. +2. Wywołaj [`factory.load()`](/ref/factory/#factory.load) albo [`collectionfactory.load()`](/ref/collectionfactory/#collectionfactory.load), aby załadować zasoby asynchronicznie. Gdy będą gotowe do tworzenia instancji, otrzymasz callback. -## Dynamiczne zwalnianie ładowanych zasobów +Szczegóły działania znajdziesz w [instrukcji Factory](/manuals/factory) i [instrukcji Collection factory](/manuals/collection-factory). -Defold zachowuje liczniki odniesień dla wszystkich zasobów. Jeśli licznik odniesienia zasobu wynosi zero, oznacza to, że nie ma do niego już żadnego odniesienia. Zasób zostaje wtedy automatycznie usunięty z pamięci. Na przykład, jeśli usuniesz wszystkie obiekty utworzone przez fabrykę i dodatkowo usuniesz obiekt zawierający komponent fabryki, zasoby wcześniej odniesione przez fabrykę zostaną usunięte z pamięci. +## Zwalnianie dynamicznie wczytanych zasobów -Dla fabryk oznaczonych jako *Load Dynamically* można wywołać funkcję [`factory.unload()`](/ref/factory/#factory.unload) albo [`collectionfactory.unload()`](/ref/collectionfactory/#collectionfactory.unload). To wywołanie usuwa odniesienie komponentu fabryki do zasobu. Jeśli nic innego nie odnosi się do zasobu (np. wszystkie utworzone obiekty są usunięte), zasób zostanie zwolniony z pamięci. +Defold utrzymuje liczniki referencji dla wszystkich zasobów. Jeśli licznik zasobu spadnie do zera, oznacza to, że nic już się do niego nie odwołuje. Wtedy zasób jest automatycznie usuwany z pamięci. Przykładowo, jeśli usuniesz wszystkie obiekty utworzone przez Factory i dodatkowo usuniesz obiekt zawierający komponent Factory, zasoby wcześniej wskazywane przez tę fabrykę zostaną zwolnione. -## Wykluczanie zasobów z paczki +Dla fabryk oznaczonych jako *Load Dynamically* możesz wywołać [`factory.unload()`](/ref/factory/#factory.unload) albo [`collectionfactory.unload()`](/ref/collectionfactory/#collectionfactory.unload). To wywołanie usuwa referencję komponentu Factory do zasobu. Jeśli nic innego nie odwołuje się już do tego zasobu, na przykład wszystkie utworzone obiekty zostały usunięte, zasób zostanie zwolniony z pamięci. -Dzięki proxy (pełnomocnikom) kolekcji można pominąć wszystkie zasoby, do których odnosi się komponent, w procesie pakowania (bundling). Jest to przydatne, jeśli potrzebujesz zachować minimalny rozmiar paczki. Na przykład, podczas uruchamiania gier w sieci jako HTML5, przeglądarka pobierze całą paczkę przed uruchomieniem gry. +## Wykluczanie zasobów z bundla -![Wykluczanie zasobów z paczki](images/resource/exclude.png) +W przypadku pełnomocników kolekcji można pominąć w procesie bundlowania wszystkie zasoby, do których odwołuje się komponent. Jest to przydatne, jeśli chcesz zminimalizować rozmiar bundla. Na przykład przy uruchamianiu gry w przeglądarce jako HTML5 przeglądarka pobiera cały bundle przed rozpoczęciem wykonywania gry. -Zaznaczenie opcji pełnomocnika kolekcji nazwanej *Exclude* (Wyklucz) spowoduje, że odniesienie do zasobu zostanie pominięte w paczce gry. Zamiast tego można przechowywać wyłączone kolekcje w wybranym przechowywaniu w chmurze. W [instrukcji do aktualizacji na żywo - Live update](/manuals/live-update/) wyjaśniono, jak działa ta funkcja. +![Exclude](images/resource/exclude.png) + +Po oznaczeniu pełnomocnika kolekcji jako *Exclude* wskazany zasób nie trafi do bundla gry. Zamiast tego wykluczone kolekcje możesz przechowywać w wybranej chmurze. [Instrukcja Live update](/manuals/live-update/) wyjaśnia, jak działa ta funkcja. diff --git a/docs/pl/manuals/texture-profiles.md b/docs/pl/manuals/texture-profiles.md index 88dfbbb2..1ab5d2a9 100644 --- a/docs/pl/manuals/texture-profiles.md +++ b/docs/pl/manuals/texture-profiles.md @@ -1,211 +1,263 @@ --- -title: Profile tekstur w Defoldzie -brief: Defold wspiera automatyczne przetwarzanie tekstur i kompresję obrazów. Ta instrukcja opisuje te funckjonalności. +title: Profile tekstur w Defold +brief: Defold obsługuje automatyczne przetwarzanie tekstur i kompresję danych obrazów. Ta instrukcja opisuje dostępne funkcje. --- -# Profile tekstur w Defoldzie +# Profile tekstur -Defold obsługuje automatyczne przetwarzanie tekstur i kompresję danych obrazów (w Atlasie, Źródłach Kafelków (*Tile sources*), Mapach Kostkowych (*Cubemaps*) i samodzielnych teksturach używanych do modeli, GUI itp). +Defold obsługuje automatyczne przetwarzanie tekstur i kompresję danych obrazów w zasobach typu *Atlas*, *Tile source*, *Cubemap* oraz w samodzielnych teksturach używanych przez modele, GUI i inne elementy. -Istnieją dwa rodzaje kompresji: programowa i sprzętowa kompresja tekstur. +Istnieją dwa typy kompresji: programowa kompresja obrazów oraz sprzętowa kompresja tekstur. -1. Programowa kompresja tekstur (software texture compression) (takie jak PNG i JPEG) zmniejsza rozmiar pamięci zasobów obrazu. Powoduje to zmniejszenie ostatecznego rozmiaru paczki z grą. Jednak pliki obrazów muszą być rozpakowane podczas wczytywania do pamięci, więc nawet jeśli obraz jest mały na dysku, może zajmować dużo miejsca w pamięci. +1. Kompresja programowa, taka jak PNG i JPEG, zmniejsza rozmiar zasobów obrazów na dysku. Dzięki temu końcowy bundle jest mniejszy. Jednak pliki obrazów muszą zostać rozpakowane podczas wczytywania do pamięci, więc mimo niewielkiego rozmiaru na dysku mogą zajmować dużo pamięci RAM. -2. Sprzętowa kompresja tekstur (hardware texture compression) również zmniejsza rozmiar pamięci zasobów obrazu. Jednak w przeciwieństwie do kompresji programowej, zmniejsza rozmiar tekstur w pamięci. Dzieje się tak, ponieważ sprzęt graficzny może bezpośrednio zarządzać teksturami skompresowanymi, bez konieczności ich wcześniejszego dekompresowania. +2. Sprzętowa kompresja tekstur również zmniejsza rozmiar zasobów obrazów, ale w przeciwieństwie do kompresji programowej obniża także zużycie pamięci przez tekstury po załadowaniu. Dzieje się tak dlatego, że układ graficzny potrafi bezpośrednio pracować na skompresowanych teksturach, bez wcześniejszego rozpakowywania. -Przetwarzanie tekstur jest konfigurowane za pomocą konkretnego profilu tekstury (ang. texture profile). W tym pliku tworzysz _profile_, które wyrażają, jakie skompresowane formaty i jakiego typu powinny być używane przy tworzeniu paczki z grą dla określonej platformy. _Profile_ są przypisane do odpowiadających im wzorców plików - _paths patterns_, co pozwala na dokładną kontrolę nad tym, które pliki w twoim projekcie powinny być kompresowane i w jaki sposób dokładnie. +Przetwarzanie tekstur konfiguruje się za pomocą konkretnego profilu tekstur. W tym pliku tworzysz *profiles*, które określają, jakich skompresowanych formatów i jakiego typu kompresji należy użyć podczas tworzenia bundli dla konkretnej platformy. Następnie profile łączy się z pasującymi *path patterns*, co daje precyzyjną kontrolę nad tym, które pliki projektu mają zostać skompresowane i w jaki sposób. -Ponieważ każda dostępna sprzętowa kompresja tekstur jest stratna, otrzymasz tzw. artefakty w danych tekstury. Te artefakty są silnie zależne od tego, jak wygląda twój materiał źródłowy i jakie metody kompresji są używane. Powinieneś przetestować swój materiał źródłowy i eksperymentować, aby uzyskać najlepsze wyniki. Wujek Google może być twoim przyjacielem w tej kwestii. +Ponieważ wszystkie dostępne sprzętowe metody kompresji tekstur są stratne, w danych tekstury pojawią się artefakty. To, jak będą wyglądały, mocno zależy od materiału źródłowego i użytej metody kompresji. Warto testować własne zasoby i eksperymentować, aby uzyskać najlepszy rezultat. -Możesz wybrać, jakie kompresje obrazów oprogramowania są stosowane na ostatecznych danych tekstury (skompresowane lub nieskompresowane) w archiwum paczki (bundle archives). Defold obsługuje kompresję tekstury [Basis Universal](https://github.com/BinomialLLC/basis_universal), która kompresuje obraz w pośredni format. Ten format jest przekształcany w czasie rzeczywistym na format sprzętu odpowiedni dla GPU bieżącego urządzenia. Format Basis Universal jest formatem wysokiej jakości, ale stratnym. Wszystkie obrazy są również kompresowane za pomocą LZ4, aby jeszcze bardziej zmniejszyć rozmiar pliku, gdy są przechowywane w archiwum gry. +Możesz wybrać, jaka programowa kompresja obrazu zostanie zastosowana do końcowych danych tekstury w archiwach bundla, zarówno dla danych już skompresowanych, jak i surowych. Defold obsługuje formaty kompresji [Basis Universal](https://github.com/BinomialLLC/basis_universal) oraz [ASTC](https://www.khronos.org/opengl/wiki/ASTC_Texture_Compression). ::: sidenote -Kompresja jest operacją czasochłonną i wymagającą sporych zasobów, która może spowodować bardzo długie czasy kompilacji, w zależności od liczby obrazów do skompresowania oraz wybranych formatów tekstury i rodzaju wybranej programowej kompresji tekstur. +Kompresja jest operacją kosztowną obliczeniowo i czasowo. W zależności od liczby kompresowanych tekstur, wybranych formatów i rodzaju kompresji programowej może bardzo wydłużyć czas builda. ::: +### Basis Universal + +Basis Universal, w skrócie BasisU, kompresuje obraz do formatu pośredniego, który podczas działania jest transkodowany do sprzętowego formatu odpowiedniego dla GPU bieżącego urządzenia. Format Basis Universal zapewnia wysoką jakość, ale jest stratny. Wszystkie obrazy są dodatkowo kompresowane przy użyciu LZ4, aby jeszcze bardziej zmniejszyć rozmiar plików przechowywanych w archiwum gry. + +### ASTC + +ASTC to elastyczny i wydajny format kompresji tekstur opracowany przez ARM i ustandaryzowany przez Khronos Group. Oferuje szeroki zakres rozmiarów bloków i przepływności bitowej, dzięki czemu można skutecznie wyważyć jakość obrazu i zużycie pamięci. ASTC obsługuje rozmiary bloków od 4×4 do 12×12 texeli, co odpowiada przepływności od 8 bitów na texel do 0,89 bita na texel. Taka elastyczność pozwala bardzo precyzyjnie sterować kompromisem między jakością a wymaganiami pamięciowymi. + +Poniższa tabela pokazuje obsługiwane rozmiary bloków i odpowiadające im przepływności bitowe: + +| Rozmiar bloku (szerokość x wysokość) | Bity na piksel | +| ------------------------------------ | -------------- | +| 4x4 | 8.00 | +| 5x4 | 6.40 | +| 5x5 | 5.12 | +| 6x5 | 4.27 | +| 6x6 | 3.56 | +| 8x5 | 3.20 | +| 8x6 | 2.67 | +| 10x5 | 2.56 | +| 10x6 | 2.13 | +| 8x8 | 2.00 | +| 10x8 | 1.60 | +| 10x10 | 1.28 | +| 12x10 | 1.07 | +| 12x12 | 0.89 | + +#### Obsługiwane urządzenia + +Choć ASTC daje bardzo dobre rezultaty, nie jest wspierane przez wszystkie karty graficzne. Oto skrócona lista wsparcia według producenta GPU: + +| Producent GPU | Wsparcie | +| ------------------- | ------------------------------------------------------------------------ | +| ARM (Mali) | Wszystkie układy ARM Mali obsługujące OpenGL ES 3.2 lub Vulkan wspierają ASTC. | +| Qualcomm (Adreno) | Układy Adreno obsługujące OpenGL ES 3.2 lub Vulkan wspierają ASTC. | +| Apple | GPU Apple od układu A8 obsługują ASTC. | +| NVIDIA | Wsparcie ASTC dotyczy głównie mobilnych GPU, np. układów Tegra. | +| AMD (Radeon) | GPU AMD obsługujące Vulkan zwykle wspierają ASTC programowo. | +| Intel (Integrated) | Nowoczesne GPU Intela wspierają ASTC programowo. | + ## Profile tekstur -Każdy projekt zawiera określony plik *.texture_profiles*, który zawiera konfigurację używaną podczas kompresji tekstur. Domyślnie ten plik to *builtins/graphics/default.texture_profiles* i zawiera konfigurację dopasowującą każdy zasób tekstury do profilu przy użyciu RGBA bez sprzętowej kompresji tekstur i z domyślną kompresją plików ZLib. +Każdy projekt zawiera plik `*.texture_profiles`, który przechowuje konfigurację używaną podczas kompresji tekstur. Domyślnie jest to `builtins/graphics/default.texture_profiles`, a jego konfiguracja przypisuje każdy zasób tekstury do profilu używającego formatu RGBA, bez sprzętowej kompresji tekstur i z domyślną kompresją plików ZLib. Aby dodać kompresję tekstur: -- Wybierz File ▸ New..., a następnie *Texture Profiles* (Profile tekstur), aby utworzyć nowy plik profili tekstur. (Albo skopiuj *default.texture_profiles* poza folder *builtins* na wybrane miejsce) +- Wybierz File ▸ New... i utwórz nowy plik *Texture Profiles*. Alternatywnie skopiuj `default.texture_profiles` poza katalog `builtins`. - Wybierz nazwę i lokalizację nowego pliku. -- Zmień wpis *texture_profiles* w *game.project*, aby wskazywał na nowy plik. -- Otwórz plik *.texture_profiles* i skonfiguruj go zgodnie z własnymi wymaganiami. +- Zmień wpis `texture_profiles` w `game.project`, aby wskazywał na nowy plik. +- Otwórz plik `*.texture_profiles` i skonfiguruj go zgodnie z potrzebami projektu. -![Nowy plik profili tekstur](images/texture_profiles/texture_profiles_new_file.png) +![New profiles file](images/texture_profiles/texture_profiles_new_file.png) -![Ustawienia profilu tekstur](images/texture_profiles/texture_profiles_game_project.png) +![Setting the texture profile](images/texture_profiles/texture_profiles_game_project.png) -W preferencjach Edytora można włączyć i wyłączyć korzystanie z profili tekstur. Wybierz File ▸ Preferences.... Karta *General* zawiera opcję *Enable texture profiles* (Włącz profile tekstur). +Możesz włączać i wyłączać użycie profili tekstur w preferencjach edytora. Wybierz File ▸ Preferences.... W zakładce *General* znajduje się pole wyboru *Enable texture profiles*. -![Preferencje profili tekstur](images/texture_profiles/texture_profiles_preferences.png) +![Texture profiles preferences](images/texture_profiles/texture_profiles_preferences.png) -## Ustawienia ścieżki +## Ustawienia ścieżek -Sekcja *Path Settings* (Ustawienia ścieżki) w pliku profilów tekstur zawiera listę wzorców ścieżek i informacje, który *profil* ma być używany przy przetwarzaniu zasobów odpowiadających danej ścieżce. Ścieżki wyrażone są jako wzorce "Ant Glob" ([zobacz tutaj](http://ant.apache.org/manual/dirtasks.html#patterns) w celu uzyskania szczegółów). Wzorce można wyrazić przy użyciu następujących symboli wieloznacznych (wildcards): +Sekcja *Path Settings* w pliku profili tekstur zawiera listę wzorców ścieżek oraz informację, który *profile* należy zastosować do zasobów pasujących do danej ścieżki. Ścieżki zapisuje się jako wzorce "Ant Glob" - szczegóły znajdziesz w [dokumentacji](http://ant.apache.org/manual/dirtasks.html#patterns). Można używać następujących wildcardów: `*` -: Dopasowanie do zera lub więcej znaków. Na przykład `sprite*.png` pasuje do plików `sprite.png`, `sprite1.png` i `sprite_with_a_long_name.png`. +: Dopasowuje zero lub więcej znaków. Na przykład `sprite*.png` pasuje do plików `sprite.png`, `sprite1.png` i `sprite_with_a_long_name.png`. `?` -: Dopasowanie dokładnie do jednego znaku. Na przykład `sprite?.png` pasuje do plików `sprite1.png`, `spriteA.png`, ale nie pasuje do `sprite.png` ani `sprite_with_a_long_name.png`. +: Dopasowuje dokładnie jeden znak. Na przykład `sprite?.png` pasuje do plików `sprite1.png` i `spriteA.png`, ale nie do `sprite.png` ani `sprite_with_a_long_name.png`. `**` -: Dopasowanie do całego drzewa katalogów lub - gdy używane jako nazwa katalogu - do zera lub więcej katalogów. Na przykład `/gui/**` pasuje do wszystkich plików w katalogu `/gui` i wszystkich jego podkatalogach. +: Dopasowuje całe drzewo katalogów albo, gdy jest użyte jako nazwa katalogu, zero lub więcej katalogów. Na przykład `/gui/**` pasuje do wszystkich plików w katalogu `/gui` i jego podkatalogach. -![Ścieżki](images/texture_profiles/texture_profiles_paths.png) +![Paths](images/texture_profiles/texture_profiles_paths.png) Ten przykład zawiera dwa wzorce ścieżek i odpowiadające im profile. `/gui/**/*.atlas` -: Wszystkie pliki *.atlas* w katalogu */gui* lub którymkolwiek z jego podkatalogów będą przetwarzane zgodnie z profilem "gui_atlas". +: Wszystkie pliki `*.atlas` w katalogu `/gui` i jego podkatalogach będą przetwarzane zgodnie z profilem `gui_atlas`. `/**/*.atlas` -: Wszystkie pliki *.atlas* w dowolnym miejscu w projekcie będą przetwarzane zgodnie z profilem "atlas". +: Wszystkie pliki `*.atlas` w dowolnym miejscu projektu będą przetwarzane zgodnie z profilem `atlas`. -Należy zauważyć, że bardziej ogólna ścieżka jest podawana na końcu. Kryterium działania jest określone jako od góry do dołu. Pierwsze wystąpienie, które pasuje do ścieżki zasobu, zostanie użyte. Dopasowanie ścieżki niżej na liście nigdy nie zastępuje pierwszego trafienia. Gdyby ścieżki były podane w odwrotnej kolejności, każda mapa kostek zostałaby przetworzona profilem "atlas", nawet te w katalogu */gui*. +Zwróć uwagę, że bardziej ogólny wzorzec umieszczono na końcu. Algorytm dopasowania działa od góry do dołu. Zostanie użyte pierwsze wystąpienie pasujące do ścieżki zasobu. Dopasowanie niżej na liście nigdy nie nadpisuje pierwszego trafienia. Gdyby kolejność była odwrotna, każdy atlas zostałby przetworzony profilem `atlas`, również te z katalogu `/gui`. -Zasoby tekstur, które _nie_ pasują do żadnej ścieżki w pliku profili, zostaną skompilowane i przeskalowane do najbliżej potęgi liczby 2, ale poza tym pozostaną nietknięte. +Zasoby tekstur, które *nie* pasują do żadnej ścieżki z pliku profili, zostaną skompilowane i przeskalowane do najbliższej potęgi dwójki, ale poza tym pozostaną bez zmian. ## Profile -Sekcja *profiles* (profile) w pliku profili tekstur zawiera listę nazwanych profili. Każdy profil zawiera jedną lub więcej platform (*platforms*), a każdą platformę opisuje lista właściwości. +Sekcja *profiles* w pliku profili tekstur zawiera listę nazwanych profili. Każdy profil zawiera jedną lub więcej pozycji *platforms*, a każda platforma jest opisana zestawem właściwości. -![Profile](images/texture_profiles/texture_profiles_profiles.png) +![Profiles](images/texture_profiles/texture_profiles_profiles.png) *Platforms* -: Określa pasującą platformę. `OS_ID_GENERIC` pasuje do wszystkich platform, w tym do wersji dev-app na urządzeniu, `OS_ID_WINDOWS` pasuje do wersji docelowych systemów Windows, `OS_ID_IOS` pasuje do wersji na urządzenia iOS itp. Należy zauważyć, że jeśli określono `OS_ID_GENERIC`, zostanie on uwzględniony we wszystkich platformach. +: Określa pasującą platformę. `OS_ID_GENERIC` pasuje do wszystkich platform, `OS_ID_WINDOWS` do bundli Windows, `OS_ID_IOS` do bundli iOS itd. Jeśli podasz `OS_ID_GENERIC`, zostanie on uwzględniony dla wszystkich platform. ::: important -Jeśli dwa [ustawienia ścieżki](#path-settings) pasują do tego samego pliku i ścieżka używa różnych profili z różnymi platformami, zostaną użyte **oba** profile i zostaną wygenerowane **dwie** tekstury. +Jeśli dwa [ustawienia ścieżek](#ustawienia-ścieżek) pasują do tego samego pliku, a dana ścieżka używa różnych profili z różnymi platformami, zostaną użyte **oba** profile i wygenerowane zostaną **dwie** tekstury. ::: *Formats* -: Jedna lub więcej formatów tekstury do wygenerowania. Jeśli określono wiele formatów, zostaną wygenerowane tekstury dla każdego formatu i dołączone do paczki. Silnik wybiera tekstury formatu obsługiwanego przez platformę uruchomieniową. +: Jeden lub więcej formatów tekstur do wygenerowania. Jeśli podasz kilka formatów, do bundla trafią tekstury w każdym z nich. Silnik wybierze podczas działania format obsługiwany przez bieżącą platformę. *Mipmaps* -: Jeśli zaznaczone, generowane są [mipmapy](https://pl.wikipedia.org/wiki/Mipmapping) dla platformy. Domyślnie nie jest zaznaczone. +: Jeśli opcja jest zaznaczona, dla tej platformy zostaną wygenerowane mipmapy. Domyślnie jest wyłączona. *Premultiply alpha* -: Jeśli zaznaczone, alfa, czyli wskaźnik przezroczystości, jest wstępnie mnożona do danych tekstury. Domyślnie jest zaznaczone. +: Jeśli opcja jest zaznaczona, kanał alfa zostanie przemnożony z danymi tekstury. Domyślnie jest włączona. *Max Texture Size* -: Maksymalny rozmiar tekstury. Jeśli ustawiono tę opcję na wartość różną od zera, tekstury są ograniczone pod względem liczby pikseli do określonej liczby. Każda tekstura, która ma szerokość lub wysokość większą niż określona wartość, zostanie przeskalowana w dół. +: Jeśli ustawisz wartość inną niż zero, rozmiar tekstur w pikselach zostanie ograniczony do tej wartości. Każda tekstura szersza lub wyższa od tej granicy zostanie przeskalowana w dół. -Do każdego profilu dodawane są następujące formaty (*Formats*): +Każdy wpis *Formats* dodany do profilu ma następujące właściwości: *Format* -: Format do użycia podczas enkodowania tekstury. Poniżej znajdują się dostępne formaty tekstur. +: Format używany podczas kodowania tekstury. Listę dostępnych formatów znajdziesz poniżej. -*Compression* -: Kompresja. Wybiera poziom jakości wynikowego obrazu skompresowanego. +*Compressor* +: Kompresor używany do kodowania tekstury. -| Poziom | Informacja | -| -------- | ----------------------------------------------- | -| `FAST` | Najszybsza kompresja. Niska jakość grafiki | -| `NORMAL` | Domyślna kompresja. Najlepsza jakość grafiki | -| `HIGH` | Najwolniejsza kompresja. Mniejszy rozmiar pliku | -| `BEST` | Wolna kompresja. Najmniejszy rozmiar pliku | +*Compressor Preset* +: Ustawia preset kompresji używany podczas kodowania wynikowego obrazu. Każdy preset zależy od danego kompresora i jego wewnętrznych ustawień. Dla uproszczenia dostępne presety mają obecnie cztery poziomy: -::: sidenote -Od wersji 1.2.185 nazwy te zostały zmienione - zredefiniowane, aby uniknąć niejednoznaczności. -::: +| Preset | Informacja | +| ----------- | ------------------------------------------- | +| `LOW` | Najszybsza kompresja. Niska jakość obrazu | +| `MEDIUM` | Domyślna kompresja. Najlepsza jakość obrazu | +| `HIGH` | Najwolniejsza kompresja. Mniejszy plik | +| `HIGHEST` | Wolna kompresja. Najmniejszy plik | -*Type* -: Pozwala określić typ kompresji dla obrazów, `COMPRESSION_TYPE_DEFAULT` albo `COMPRESSION_TYPE_BASIS_UASTC`. Zobacz [Typy Kompresji tutaj](#compression-types). +Pamiętaj, że kompresor `uncompressed` ma tylko jeden preset o nazwie `uncompressed`, co oznacza brak kompresji tekstur. +Listę dostępnych kompresorów znajdziesz w sekcji [Kompresory](#compressors). ## Formaty tekstur -Tekstury sprzętowe mogą być przetwarzane na dane nieskompresowane lub skompresowane *stratnie* o różnej liczbie kanałów i głębi bitowej. Kompresja sprzętowa oznacza, że ostateczny obraz będzie miał stały rozmiar, niezależnie od zawartości obrazu. Oznacza to, że utrata jakości podczas kompresji zależy od zawartości oryginalnej tekstury. +Tekstury sprzętowe mogą być przetwarzane do danych nieskompresowanych albo *stratnie* skompresowanych, z różną liczbą kanałów i różną głębią bitową. W przypadku stałorozmiarowej kompresji sprzętowej wynikowy obraz ma zawsze z góry określony rozmiar, niezależnie od treści. Oznacza to, że utrata jakości zależy od zawartości oryginalnej tekstury. + +Ponieważ transkodowanie Basis Universal zależy od możliwości GPU urządzenia, zalecane formaty do stosowania z kompresją Basis Universal to formaty ogólne: +`TEXTURE_FORMAT_RGB`, `TEXTURE_FORMAT_RGBA`, `TEXTURE_FORMAT_RGB_16BPP`, `TEXTURE_FORMAT_RGBA_16BPP`, `TEXTURE_FORMAT_LUMINANCE` oraz `TEXTURE_FORMAT_LUMINANCE_ALPHA`. + +Transkoder Basis Universal obsługuje wiele formatów wyjściowych, między innymi `ASTC4x4`, `BCx`, `ETC2`, `ETC1` i `PVRTC1`. -Ponieważ transkodowanie kompresji Basis Universal zależy od możliwości karty graficznej (GPU) urządzenia, zalecane formaty do użycia z kompresją Basis Universal to ogólne formaty, takie jak: -`TEXTURE_FORMAT_RGB`, `TEXTURE_FORMAT_RGBA`, `TEXTURE_FORMAT_RGB_16BPP`, `TEXTURE_FORMAT_RGBA_16BPP`, `TEXTURE_FORMAT_LUMINANCE` i `TEXTURE_FORMAT_LUMINANCE_ALPHA`. +Obecnie obsługiwane są następujące formaty stratnej kompresji: -Transkoder Basis Universal obsługuje wiele formatów wyjściowych, takich jak: `ASTC4x4`, `BCx`, `ETC2`, `ETC1` i `PVRTC1`. +| Format | Kompresja | Szczegóły | +| -------------------------------- | --------- | --------- | +| `TEXTURE_FORMAT_RGB` | brak | Kolor 3-kanałowy. Kanał alfa jest odrzucany. | +| `TEXTURE_FORMAT_RGBA` | brak | Kolor 3-kanałowy i pełny kanał alfa. | +| `TEXTURE_FORMAT_RGB_16BPP` | brak | Kolor 3-kanałowy. 5+6+5 bitów. | +| `TEXTURE_FORMAT_RGBA_16BPP` | brak | Kolor 3-kanałowy i pełny kanał alfa. 4+4+4+4 bity. | +| `TEXTURE_FORMAT_LUMINANCE` | brak | 1-kanałowa skala szarości, bez alfy. Kanały RGB są zredukowane do jednego. Alfa jest odrzucana. | +| `TEXTURE_FORMAT_LUMINANCE_ALPHA` | brak | 1-kanałowa skala szarości i pełny kanał alfa. Kanały RGB są zredukowane do jednego. | -Obecnie obsługiwane są następujące formaty kompresji stratnej: +W przypadku ASTC liczba kanałów zawsze wynosi 4 (RGB + alfa), a sam format określa rozmiar kompresji blokowej. +Te formaty są zgodne wyłącznie z kompresorem ASTC. Każda inna kombinacja spowoduje błąd builda. -| Format | Kompresja | Szczegóły | -| --------------------------------- | ----------- | -------------------------------- | ---- | -| `TEXTURE_FORMAT_RGB` | brak | Kolor 3-kanałowy. Alfa jest usuwana. | -| `TEXTURE_FORMAT_RGBA` | brak | Kolor 3-kanałowy i pełna alfa. | -| `TEXTURE_FORMAT_RGB_16BPP` | brak | Kolor 3-kanałowy. 5+6+5 bitów. | -| `TEXTURE_FORMAT_RGBA_16BPP` | brak | Kolor 3-kanałowy i pełna alfa. 4+4+4+4 bity. | -| `TEXTURE_FORMAT_LUMINANCE` | brak | Skala szarości 1-kanałowa, brak alfy. Kanały RGB pomnożone przez siebie. Alfa jest usuwana. | -| `TEXTURE_FORMAT_LUMINANCE_ALPHA` | brak | Skala szarości 1-kanałowa i pełna alfa. Kanały RGB pomnożone przez siebie. | +`TEXTURE_FORMAT_RGBA_ASTC_4X4` +`TEXTURE_FORMAT_RGBA_ASTC_5X4` +`TEXTURE_FORMAT_RGBA_ASTC_5X5` +`TEXTURE_FORMAT_RGBA_ASTC_6X5` +`TEXTURE_FORMAT_RGBA_ASTC_6X6` +`TEXTURE_FORMAT_RGBA_ASTC_8X5` +`TEXTURE_FORMAT_RGBA_ASTC_8X6` +`TEXTURE_FORMAT_RGBA_ASTC_8X8` +`TEXTURE_FORMAT_RGBA_ASTC_10X5` +`TEXTURE_FORMAT_RGBA_ASTC_10X6` +`TEXTURE_FORMAT_RGBA_ASTC_10X8` +`TEXTURE_FORMAT_RGBA_ASTC_10X10` +`TEXTURE_FORMAT_RGBA_ASTC_12X10` +`TEXTURE_FORMAT_RGBA_ASTC_12X12` +## Kompresory -## Typy kompresji +Domyślnie obsługiwane są następujące kompresory tekstur. Dane zostaną rozpakowane po załadowaniu pliku tekstury do pamięci. -Obsługiwane są następujące typy programowych kompresji obrazów. Dane są rozpakowywane, gdy plik tekstury jest ładowany do pamięci. +| Nazwa | Formaty | Informacja | +| -------------- | -------------------- | ---------- | +| `Uncompressed` | Wszystkie formaty | Brak kompresji. Ustawienie domyślne. | +| `BasisU` | Wszystkie formaty RGB/RGBA | Wysokiej jakości, stratna kompresja Basis Universal. Niższa jakość daje mniejszy rozmiar. | +| `ASTC` | Wszystkie formaty ASTC | Stratna kompresja ASTC. Niższa jakość daje mniejszy rozmiar. | ::: sidenote -Obecnie analizujemy, jak ponownie wprowadzić obsługę sprzętowa formatów, a także dodatkową obsługę kompresji WEBP. -Nasze obecne długotrwałe zadanie polegające na wprowadzeniu wtyczek do przetwarzania treści ma na celu rozwiązanie tego problemu. +W Defold 1.9.7 przebudowano pipeline kompresji tekstur tak, aby obsługiwał instalowalne kompresory. To pierwszy krok do umożliwienia implementowania algorytmów kompresji tekstur w rozszerzeniach, na przykład WEBP albo własnych rozwiązań. ::: -| Typ | Formaty | Szczegóły | -| --------------------------------- | -------------------------- | --------- | -| `COMPRESSION_TYPE_DEFAULT` | Wszystkie formaty | Ogólna kompresja danych bez utraty. Domyślna. | -| `COMPRESSION_TYPE_BASIS_UASTC` | Wszystkie formaty RGB/RGBA | Wysoka jakość kompresji Basis Universal, utrata jakości. Niższy poziom jakości prowadzi do mniejszego rozmiaru. | - ## Przykładowy obraz -Aby lepiej zrozumieć wyniki, oto przykład. -Należy pamiętać, że jakość obrazu, czas kompresji i rozmiar kompresji zawsze zależą od obrazu wejściowego i mogą się różnić. +Aby lepiej pokazać wynik działania kompresji, poniżej znajduje się przykład. Pamiętaj, że jakość obrazu, czas kompresji i rozmiar skompresowanych danych zawsze zależą od obrazu wejściowego i mogą się różnić. -Obraz oryginalny (1024x512): -![Obraz oryginalny](images/texture_profiles/kodim03_pow2.png) +Obraz bazowy (1024x512): +![New profiles file](images/texture_profiles/kodim03_pow2.png) -### Czasy kompresji +### Czas kompresji -| Poziom | Czas kompresji | Czasy relatywny | -| ----------------------------- | --------------- | -| `FAST` | 0m0.143s | 0.5x | -| `NORMAL` | 0m0.294s | 1.0x | -| `HIGH` | 0m1.764s | 6.0x | -| `BEST` | 0m1.109s | 3.8x | +| Preset | Czas kompresji | Czas względny | +| ----------- | -------------- | ------------- | +| `LOW` | 0m0.143s | 0.5x | +| `MEDIUM` | 0m0.294s | 1.0x | +| `HIGH` | 0m1.764s | 6.0x | +| `HIGHEST` | 0m1.109s | 3.8x | ### Utrata sygnału -Porównanie wykonuje się za pomocą narzędzia `basisu` (pomiar PSNR) -100 dB oznacza brak utraty sygnału (jest to to samo co oryginalny obraz) - -| Poziom | Sygnał | -| ------------------------------------------------------------ | -| `FAST` | Max: 34 Mean: 0.470 RMS: 1.088 PSNR: 47.399 dB | -| `NORMAL` | Max: 35 Mean: 0.439 RMS: 1.061 PSNR: 47.620 dB | -| `HIGH` | Max: 37 Mean: 0.898 RMS: 1.606 PSNR: 44.018 dB | -| `BEST` | Max: 51 Mean: 1.298 RMS: 2.478 PSNR: 40.249 dB | +Porównanie wykonano narzędziem `basisu`, mierząc PSNR. +100 dB oznacza brak utraty sygnału, czyli identyczny obraz jak oryginał. -### Rozmiary plików skompresowanych +| Preset | Sygnał | +| ----------- | ------ | +| `LOW` | Max: 34 Mean: 0.470 RMS: 1.088 PSNR: 47.399 dB | +| `MEDIUM` | Max: 35 Mean: 0.439 RMS: 1.061 PSNR: 47.620 dB | +| `HIGH` | Max: 37 Mean: 0.898 RMS: 1.606 PSNR: 44.018 dB | +| `HIGHEST` | Max: 51 Mean: 1.298 RMS: 2.478 PSNR: 40.249 dB | -Oryginalny rozmiar pliku wynosi 1572882 bajtów. +### Rozmiary skompresowanych plików -| Poziom | Rozmiar pliku | Procent | -| ------------------------------------- | -| `FAST` | 357225 | 22.71 % | -| `NORMAL` | 365548 | 23.24 % | -| `HIGH` | 277186 | 17.62 % | -| `BEST` | 254380 | 16.17 % | +Oryginalny plik ma rozmiar 1572882 bajtów. +| Preset | Rozmiar pliku | Udział | +| ----------- | ------------- | ------ | +| `LOW` | 357225 | 22.71 % | +| `MEDIUM` | 365548 | 23.24 % | +| `HIGH` | 277186 | 17.62 % | +| `HIGHEST` | 254380 | 16.17 % | ### Jakość obrazu -Oto wynikowe obrazy (pobrane z kodowania ASTC przy użyciu narzędzia `basisu`) +Poniżej znajdują się obrazy wynikowe uzyskane z kodowania ASTC przy użyciu narzędzia `basisu`. -`FAST` -![fast compression level](images/texture_profiles/kodim03_pow2.fast.png) +`LOW` +![low compression preset](images/texture_profiles/kodim03_pow2.fast.png) -`NORMAL` -![normal compression level](images/texture_profiles/kodim03_pow2.normal.png) +`MEDIUM` +![medium compression preset](images/texture_profiles/kodim03_pow2.normal.png) `HIGH` -![high compression level](images/texture_profiles/kodim03_pow2.high.png) - -`BEST` -![best compression level](images/texture_profiles/kodim03_pow2.best.png) - +![high compression preset](images/texture_profiles/kodim03_pow2.high.png) +`HIGHEST` +![best compression preset](images/texture_profiles/kodim03_pow2.best.png) diff --git a/docs/pl/manuals/writing-code.md b/docs/pl/manuals/writing-code.md index 2c780cd9..4e110d43 100644 --- a/docs/pl/manuals/writing-code.md +++ b/docs/pl/manuals/writing-code.md @@ -1,59 +1,74 @@ --- title: Pisanie kodu -brief: Ta instrukcja krótko omawia, jak pracować z kodem w Defold. +brief: Ta instrukcja krótko omawia pracę z kodem w silniku Defold. --- # Pisanie kodu -Podczas gdy Defold pozwala tworzyć wiele zawartości gry za pomocą narzędzi wizualnych, takich jak Edytory map kafelków (tilemap) i efektów cząsteczkowych (particle FX), logikę gry tworzysz za pomocą Edytora kodu. Logikę gry pisze się za pomocą języka programowania [Lua](https://www.lua.org/), podczas gdy rozszerzenia samego silnika pisze się przy użyciu języków niskopoziomowych dedykowanych dla docelowej platformy. +Choć Defold pozwala tworzyć znaczną część zawartości gry za pomocą narzędzi wizualnych, takich jak edytory map kafelków i efektów cząsteczkowych, logikę gry nadal tworzysz w edytorze kodu. Logikę gry pisze się w [języku Lua](https://www.lua.org/), natomiast rozszerzenia samego silnika tworzy się w języku lub językach natywnych dla docelowej platformy. ## Pisanie kodu Lua -Defold używa Lua 5.1 i LuaJIT (w zależności od docelowej platformy) i należy stosować specyfikację tego języka dla konkretnych wersji Lua podczas pisania logiki gry. Aby uzyskać więcej szczegółów na temat pracy z Lua w Defoldzie, zobacz nasz [podręcznik Lua w Defold](/manuals/lua). +Defold używa Lua 5.1 oraz LuaJIT, zależnie od platformy docelowej, dlatego podczas pisania logiki gry trzeba trzymać się specyfikacji tych wersji języka. Więcej informacji znajdziesz w [instrukcji Lua w silniku Defold](/manuals/lua). + +## Używanie innych języków kompilowanych do Lua + +Defold obsługuje transpiler’y generujące kod Lua. Po zainstalowaniu rozszerzenia transpiler’a możesz używać alternatywnych języków, takich jak [Teal](https://github.com/defold/extension-teal), aby pisać statycznie sprawdzany kod Lua. To funkcja podglądowa i ma ograniczenia: obecna obsługa transpiler’ów nie udostępnia informacji o modułach i funkcjach zdefiniowanych w środowisku uruchomieniowym Lua w Defold. Oznacza to, że używając API Defold, takiego jak `go.animate`, musisz samodzielnie przygotować zewnętrzne definicje. ## Pisanie kodu natywnego -Defold pozwala na rozszerzenie silnika gry kodem natywnym (native extensions), aby uzyskać dostęp do funkcji specyficznych dla danej platformy, których nie dostarcza sam silnik. Możesz również użyć kodu natywnego, gdy wydajność Lua nie jest wystarczająca (obliczenia wymagające dużych zasobów, przetwarzanie obrazów itp.). Aby dowiedzieć się więcej, zajrzyj do naszych [podręczników dotyczących Rozszerzeń Natywnych](/manuals/extensions/). +Defold pozwala rozszerzać silnik gry kodem natywnym, aby uzyskać dostęp do funkcji specyficznych dla platformy, których sam silnik nie udostępnia. Kod natywny przydaje się też wtedy, gdy wydajność Lua okazuje się niewystarczająca, na przykład przy kosztownych obliczeniach lub przetwarzaniu obrazów. Szczegóły znajdziesz w [instrukcjach o Native Extensions](/manuals/extensions/). -## Używanie wbudowanego Edytora kodu +## Używanie wbudowanego edytora kodu -Defold posiada wbudowany Edytor kodu, który pozwala na otwieranie i edytowanie plików Lua (.lua), plików skryptów Defold (.script, .gui_script i .render_script) oraz innych plików z rozszerzeniem, które nie są obsługiwane natywnie przez Edytor. Dodatkowo Edytor ten oferuje podświetlanie składni dla plików Lua i skryptów oraz podręczny dostęp do dokumentacji dla funkcji API. +Defold ma wbudowany edytor kodu, który pozwala otwierać i edytować pliki Lua (`.lua`), pliki skryptów Defold (`.script`, `.gui_script` i `.render_script`), a także inne pliki z rozszerzeniami, których edytor nie obsługuje natywnie. Edytor zapewnia również podświetlanie składni dla plików Lua i skryptów. ![](/images/editor/code-editor.png) +### Uzupełnianie kodu -### Dodawanie sprawdzania poprawności kodu Lua za pomocą LSP +Wbudowany edytor kodu wyświetla podpowiedzi funkcji podczas pisania: -Defold obsługuje część protokołu Language Server Protocol (LSP), który można użyć do analizy kodu i wskazywania błędów programistycznych i stylowych. Proces ten jest również znany jako sprawdzanie poprawności kodu (linting). +![](/images/editor/codecompletion.png) -Serwer języka Lua i linter kodu są dostępne jako wtyczka (plugin). Zainstaluj wtyczkę, [dodając ją jako zależność](/manuals/libraries/#setting-up-library-dependencies): +Naciśnięcie CTRL + Space pokazuje dodatkowe informacje o funkcjach, argumentach i wartościach zwracanych: -``` -https://github.com/defold/lua-language-server/releases/download/v0.0.5/release.zip -``` -Dostępne wersje można znaleźć na [stronie wydań](https://github.com/defold/lua-language-server/releases) wtyczki. Dowiedz się więcej na temat tej wtyczki na [stronie wsparcia na forum Defold](https://forum.defold.com/t/linting-in-the-code-editor/72465). +![](/images/editor/apireference.png) +### Konfiguracja lintingu + +Wbudowany edytor kodu wykonuje linting przy użyciu [Luacheck](https://luacheck.readthedocs.io/en/stable/index.html) oraz [Lua language server](https://luals.github.io/wiki/diagnostics/). Aby skonfigurować Luacheck, utwórz plik `.luacheckrc` w katalogu głównym projektu. Listę dostępnych opcji znajdziesz na [stronie konfiguracji Luacheck](https://luacheck.readthedocs.io/en/stable/config.html). Defold używa domyślnie następującej konfiguracji Luacheck: + +```lua +unused_args = false -- don't warn on unused arguments (common for .script files) +max_line_length = false -- don't warn on long lines +ignore = { + "611", -- line contains only whitespace + "612", -- line contains trailing whitespace + "614" -- trailing whitespace in a comment +}, +``` -## Użycie zewnętrznego Edytora kodu +## Używanie zewnętrznego edytora kodu -Edytor kodu w Defoldzie zapewnia podstawową funkcjonalność do pisania kodu, ale dla bardziej zaawansowanych przypadków użycia lub dla użytkowników z ulubionym Edytorem kodu, można pozwolić Defoldowi otwierać pliki za pomocą zewnętrznego Edytora, ponieważ skrypty i pliki tworzone przez Defolda w projekcie są edytowalnymi plikami tekstowymi. W [oknie preferencji w zakładce "Code"](/manuals/editor-preferences/#code) można zdefiniować zewnętrzny Edytor, który ma być używany podczas edycji kodu. +Edytor kodu w Defold zapewnia podstawowe możliwości potrzebne do pisania kodu, ale w bardziej zaawansowanych zastosowaniach lub jeśli wolisz własne narzędzie, możesz skonfigurować Defold tak, aby otwierał pliki w zewnętrznym edytorze. W [oknie Preferences, w zakładce Code](/manuals/editor-preferences/#code), można wskazać zewnętrzny edytor używany podczas pracy z kodem. ### Visual Studio Code - Defold Kit -Defold Kit to wtyczka dla Visual Studio Code z następującymi funkcjami: +Defold Kit to wtyczka do Visual Studio Code z następującymi funkcjami: -* Instalowanie zalecanych rozszerzeń -* Podświetlanie, autouzupełnianie i sprawdzanie poprawności (linting) Lua -* Zastosowanie odpowiednich ustawień do przestrzeni roboczej -* Adnotacje Lua dla interfejsu API Defold -* Adnotacje Lua dla zależności -* Budowanie i uruchamianie -* Debugowanie z punktami przerwania (breakpoints) -* Budowanie i pakowanie dla wszystkich platform -* Wdrażanie na podłączone urządzenia mobilne +* instalacja zalecanych rozszerzeń +* podświetlanie, autouzupełnianie i linting Lua +* stosowanie odpowiednich ustawień do obszaru roboczego +* adnotacje Lua dla API Defold +* adnotacje Lua dla zależności +* budowanie i uruchamianie +* debugowanie z punktami przerwania +* bundlowanie na wszystkie platformy +* wdrażanie na podłączone urządzenia mobilne -Dowiedz się więcej i zainstaluj Defold Kit z [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=astronachos.defold). +Więcej informacji i instalację Defold Kit znajdziesz w [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=astronachos.defold). ## Oprogramowanie dokumentacyjne -Dostępne są paczki przygotowane przez społeczność Defolda do generowania dokumentacji API dla [Dash i Zeal](https://forum.defold.com/t/defold-docset-for-dash/2417). +Społeczność przygotowała pakiety referencji API do programów [Dash i Zeal](https://forum.defold.com/t/defold-docset-for-dash/2417). From 91f83436b386c106ef90691bcee5c01e7dadcf6e Mon Sep 17 00:00:00 2001 From: AGulev Date: Fri, 13 Mar 2026 13:19:40 +0100 Subject: [PATCH 2/8] actualization butch two --- docs/pl/manuals/camera.md | 269 +++++++-- docs/pl/manuals/editor-scripts.md | 857 +++++++++++++++++++++++----- docs/pl/manuals/editor.md | 341 ++++++++--- docs/pl/manuals/font.md | 230 ++++++-- docs/pl/manuals/gui-layouts.md | 105 ++-- docs/pl/manuals/live-update.md | 374 +++--------- docs/pl/manuals/physics-shapes.md | 153 +++-- docs/pl/manuals/project-settings.md | 788 +++++++++++++++++-------- docs/pl/manuals/script.md | 187 +++--- docs/pl/manuals/sprite.md | 108 ++-- 10 files changed, 2340 insertions(+), 1072 deletions(-) diff --git a/docs/pl/manuals/camera.md b/docs/pl/manuals/camera.md index 93f522d3..983be98b 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 prostą 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 prostopadłościenny 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ę, kliknij prawym przyciskiem myszy 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 +: Identyfikator (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 (ang. clipping plane). 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,73 +126,161 @@ 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 projekcją perspektywiczną ma 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). -::: +### Render script + +Podczas używania domyślnego skryptu renderującego 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 kompatybilności wstecznej. + +Alternatywnie możesz ustawić w skrypcie renderującym 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: +### Adaptive zoom + +Idea adaptive zoom polega na dostosowywaniu wartości zoomu kamery, gdy rozdzielczość ekranu zmienia się względem początkowej rozdzielczości ustawionej w *game.project*. + +Dwa częste podejścia do adaptive zoom 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 adaptive zoom 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`). @@ -150,18 +295,18 @@ Kamera ma wiele różnych właściwości (properties), które można manipulowa : Zoom kamery ortograficznej (typ `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/editor-scripts.md b/docs/pl/manuals/editor-scripts.md index 162e911b..6e7b83c4 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 polecenia menu i haki 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 workflow. -## 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 [Execution modes](#execution-modes). -## 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 [Commands](#commands) i [Lifecycle hooks](#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 [Preferences](#preferences). + +Pełne API edytora znajdziesz [tutaj](https://defold.com/ref/alpha/editor/). + +## Commands + +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. 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 + }) +}) ``` -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. +#### Edycja particlefx -Każdy hak cyklu życia może zwracać akcje lub zapisywać pliki w katalogu projektu. +`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: -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`. +```lua +editor.transact({ + editor.tx.add("/fire.particlefx", "emitters", { + type = "emitter-type-circle", + modifiers = { + {type = "modifier-type-acceleration"} + } + }) +}) +``` -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ń. +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: -## Skrypty Edytora w bibliotekach +- `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))`. -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`. +Krzywe ze spreadem mają dodatkowo właściwość liczbową `spread`. -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`. +Przykład ustawienia krzywej alpha czasu życia cząsteczki dla istniejącego emitera: -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 +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 + }}) +}) +``` + +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ą. + +#### Edycja obiektów kolizji + +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: + +```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 [Editor scripts in libraries](#editor-scripts-in-libraries). +::: + +## Lifecycle hooks + +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ć haki 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 haki 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 haki cyklu życia są obecnie funkcją dostępną wyłącznie w edytorze i nie są wykonywane przez Boba podczas bundlowania z wiersza poleceń. + +## Language servers + +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). + +## HTTP server + +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`. + +## Editor scripts in libraries + +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}` obok tego pliku. 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ć. + +## Preferences + +Skrypty edytora mogą definiować i używać preferencji, czyli trwałych, niecommitowanych 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 +}) +``` + +## Execution modes + +Ś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. + +## Actions + +::: 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. + +### Undoable actions + +::: sidenote +Preferuj używanie `editor.transact()`. +::: + +Undoable action 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 undoable actions: + +- `"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. + +### Non-undoable actions + +::: sidenote +Preferuj używanie `editor.execute()`. +::: + +Non-undoable action 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 non-undoable actions: + +- `"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. + +### Mixing actions and side effects -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..78fb3824 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 Editor -## 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 panelu `Editor` 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) +## Preferences + +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 Preferences](/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 jest uruchomiony 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 + +## Editor Server + +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/font.md b/docs/pl/manuals/font.md index 4aee5f96..277f6cca 100644 --- a/docs/pl/manuals/font.md +++ b/docs/pl/manuals/font.md @@ -1,164 +1,268 @@ --- -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 silnik Defold obsługuje fonty i jak wyświetlać tekst 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 (Etykieta) 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 ograniczenia: - 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. Wadą tego podejścia jest to, że każdy font musi wyrasteryzować wszystkie możliwe glify już na etapie buildu, co może prowadzić do powstawania bardzo dużych tekstur zużywających pamięć i zwiększających rozmiar bundla. + +Jeśli używasz runtime fonts, pliki `.ttf` są dołączane do bundla bez zmian, a rasteryzacja odbywa się na żądanie podczas działania aplikacji. Dzięki temu zmniejsza się zarówno zużycie pamięci w runtime, jak i rozmiar bundla. + +## Obsługa układu tekstu, na przykład right-to-left + +Runtime fonts mają też tę zaletę, że obsługują pełny układ tekstu, na przykład right-to-left. +Obecnie wykorzystywane są biblioteki [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ż nazywany font collection (kolekcją fontów). W trybie offline powiązany jest z nim tylko jeden font. +Przy użyciu runtime fonts z kolekcją fontów możesz powiązać więcej niż jeden plik fontu `.ttf`. + +Dzięki temu możesz używać kolekcji fontów podczas renderowania wielu tekstów w różnych językach i jednocześnie utrzymywać niskie zużycie pamięci. +Przykładowo możesz 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ż kliknąć prawym przyciskiem myszy 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 dostosuj 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 na teksturę atlasu fontu, w której dane bitmapowe służą do renderowania tekstu. Kanały kolorów służą do kodowania kształtu znaku, obrysu i cienia. Dla plików *`.fnt`* źródłowa tekstura bitmapowa jest używana bez zmian. + - `TYPE_DISTANCE_FIELD` konwertuje zaimportowany font do tekstury atlasu fontu, w której dane pikseli reprezentują nie piksele ekranu, lecz odległości od krawędzi glifu. 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 osobne quady odpowiednio dla kształtu glifu, obrysu i cienia. 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 na docelowej bitmapie. Ustaw 0, jeśli chcesz uzyskać pikselowo idealne renderowanie. *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ługa cienia jest włączona we wbudowanych shaderach materiałów fontów i działa 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. +: Dla fontów bitmapowych to ustawienie określa, ile razy ma zostać zastosowane małe jądro rozmycia do każdego glifu. Dla Distance field ta wartość odpowiada 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`. + +*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. -*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. + Dla runtime fonts ten tekst działa też jako wstępne podgrzewanie pamięci podręcznej właściwymi 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 { | } ~ ::: *All Chars* -: Jeśli zaznaczysz tę właściwość, wszystkie glify dostępne w pliku źródłowym zostaną uwzględnione w wyniku. +: Po zaznaczeniu tej właściwości 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 pamięci podręcznej glifów. Gdy silnik renderuje tekst, wyszukuje glif w bitmapie cache. Jeśli go tam nie ma, glif zostaje 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 jest dobierany automatycznie i może urosnąć 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 wykorzystujący je 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 przy tworzeniu fontu zmienić właściwość *Material* na *`builtins/fonts/font-df.material`* lub inny materiał obsługujący dane Distance field. W przeciwnym razie font nie będzie używał poprawnego 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. +Takie fonty nie przynoszą 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 muszą znajdować się w tym samym katalogu. 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 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 generującego odpowiednie pliki. Możesz użyć między innymi: -* [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ędzia tylko dla Windows od AngelCode. +* [Shoebox](http://renderhjs.net/shoebox/), darmowej aplikacji opartej na Adobe Air dla Windows i macOS. +* [Hiero](https://libgdx.com/wiki/tools/hiero), narzędzia open source opartego na Java. +* [Glyph Designer](https://71squared.com/glyphdesigner), komercyjnego narzędzia dla macOS od 71 Squared. +* [bmGlyph](https://www.bmglyph.com), komercyjnego narzędzia 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, pamiętaj o ustawieniu właściwości materiału na *`builtins/fonts/font-fnt.material`* podczas tworzenia fontu. ## Artefakty i najlepsze 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). +Ogólnie fonty bitmapowe sprawdzają się najlepiej wtedy, gdy są renderowane bez skalowania. 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 zwiększaniu rozmiaru piksele rosną razem z fontem, powodując widoczne 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: +Przy zmniejszaniu rozmiaru tekstury bitmapowe mogą być skutecznie i estetycznie skalowane w dół oraz wygładzane przez GPU. Font bitmapowy zachowuje też kolor lepiej niż font typu Distance field. Poniżej znajdziesz powiększenie 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 rozmiaru docelowego wystarczająco dużego, aby pomieścić informacje o odległości opisujące krzywizny glifów. Poniżej użyto tego samego fontu co wyżej, ale w rozmiarze 18 pikseli i powiększono go 10 razy. Wyraźnie widać, że ten rozmiar jest zbyt mały, by 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 potrzebujesz cienia ani obrysu, ustaw ich wartości alfa na zero. W przeciwnym razie dane cienia i obrysu nadal będą generowane, zajmując 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. -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. +* 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 (teksturą pamięci podręcznej glifów) i jest używana podczas renderowania tekstu dla konkretnego 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: +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. -* `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 +Każdy glif jest wewnętrznie umieszczany w cache zgodnie z linią bazową fontu, co umożliwia obliczanie lokalnych współrzędnych tekstury glifu w odpowiadającej mu komórce cache bezpośrednio w shaderze. Dzięki temu można uzyskać dynamiczne efekty tekstowe, takie jak gradienty albo nakładki tekstur. Silnik udostępnia shaderowi metryki cache przez specjalną stałą shadera `texture_size_recip`, która zawiera następujące informacje w komponentach wektora: -Na przykład, aby wygenerować gradient w fragmencie shadera, wystarczy napisać: +* `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 shaderze fragmentu, wystarczy zapisać: `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 [instrukcji do shaderów](/manuals/shader). + +## Włączanie runtime fonts + +Można używać generowania w runtime dla fontów typu SDF, gdy korzystasz z fontów TrueType (`.ttf`). +Takie podejście może znacząco zmniejszyć rozmiar pobieranych danych i zużycie pamięci w runtime w grze 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ć pracę 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 zaznaczone jest `All Chars`, podgrzewanie wstępne nie zostanie wykonane, ponieważ niweczyłoby to korzyść z niewymuszania generowania wszystkich glifów naraz. +::: + +Jeśli pole `Characters` w pliku `.fontc` jest ustawione, jego zawartość służy jako tekst do ustalenia, które glify trzeba dodać do cache. + +Możesz też ręcznie zaktualizować cache glifów, wywołując `font.prewarm_text(font_collection, text, callback)`. Funkcja przyjmuje callback informujący, że 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 + +Dla 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, na przykład 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 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/gui-layouts.md b/docs/pl/manuals/gui-layouts.md index 87da2cbc..fea44558 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 silniku 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 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 kliknij prawym przyciskiem myszy odpowiednie miejsce 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. + +### Automatyczny wybór układu (Display Profiles) -## Układy interfejsu +Zasób Display Profiles ma opcję `Auto Layout Selection` (domyślnie włączoną). 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 + +Aktualny zestaw profili wyświetlania można wykorzystać do tworzenia wariantów układów dla zestawu węzłów GUI. Aby dodać nowy układ do sceny GUI, kliknij prawym przyciskiem myszy ikonę *Layouts* w widoku *Outline* i wybierz Add ▸ Layout ▸ ...: ![Add layout to scene](images/gui-layouts/add_layout.png) -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*. +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*. ![Layouts toolbar](images/gui-layouts/toolbar.png) ![portrait edit](images/gui-layouts/portrait.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. +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ść. ![landscape edit](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 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. +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. Zwracaj też uwagę na aktualnie wybrany układ. Jeśli dodasz nowy układ do projektu, zostanie on skonfigurowany według układu wybranego w danej chwili. 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 w runtime jako fallback, 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 zahaszowane id 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/). +Przy 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 dla 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 hash id 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/live-update.md b/docs/pl/manuals/live-update.md index e6efc68c..606f8484 100644 --- a/docs/pl/manuals/live-update.md +++ b/docs/pl/manuals/live-update.md @@ -1,364 +1,146 @@ --- -title: Aktualizacja na żywo (Live update) w Defoldzie -brief: Ta instrukcja opisuje i wyjaśnia funkcjonalność Live update umożliwiającą aplikacjom pobieranie i przetrzymywanie danych, które początkowo były celowo nie dołączone do zbudowanej paczki. +title: Zawartość Live update w silniku Defold +brief: Funkcja Live update pozwala środowisku uruchomieniowemu pobierać i przechowywać zasoby, które zostały celowo pominięte w bundlu podczas budowania aplikacji. Ta instrukcja wyjaśnia, jak to działa. --- -# Aktualizacja na żywo (Live Update) +# Live update -Podczas pakowania gry, Defold pakuje wszystkie zasoby gry do końcowego pakietu specyficznego dla platformy. W większości przypadków jest to preferowane rozwiązanie, ponieważ działający silnik ma natychmiastowy dostęp do wszystkich zasobów i może szybko je ładować. Jednak istnieją sytuacje, w których chcielibyśmy odłożyć ładowanie zasobów na późniejszy etap. Na przykład: +Podczas bundlowania gry Defold pakuje wszystkie zasoby do końcowej paczki specyficznej dla danej platformy. W większości przypadków jest to korzystne, ponieważ działający silnik ma natychmiastowy dostęp do wszystkich zasobów i może szybko ładować je z nośnika. Czasem jednak warto odłożyć ładowanie części zasobów na później. Na przykład wtedy, gdy: -- Twoja gra zawiera serię odcinków/części, a chcesz uwzględnić tylko pierwszy, aby gracze mogli go wypróbować, zanim zdecydują, czy chcą kontynuować resztę gry. -- Twoja gra jest przeznaczona na HTML5. W przeglądarce ładowanie aplikacji z pamięci oznacza, że cały pakiet aplikacji musi zostać pobrany przed uruchomieniem. Na takiej platformie możesz chcieć wysłać minimalny pakiet startowy i uruchomić aplikację szybko, zanim pobierzesz pozostałe zasoby gry, dzięki czemu gracze wypróbują grę, a gdy będzie wymagane pobranie dodatkowej zawartości może to być wykonane na późniejszym etapie. -- Twoja gra zawiera bardzo duże zasoby (obrazy, filmy itp.), których pobieranie chciałbyś odłożyć do momentu, gdy są gotowe do wyświetlenia w grze. Jest to celem utrzymania rozmiaru instalacji na niskim poziomie. +- gra składa się z odcinków i chcesz dołączyć tylko pierwszy, aby gracz mógł go wypróbować przed odblokowaniem reszty +- gra jest przeznaczona na HTML5, gdzie przeglądarka musi pobrać całą paczkę aplikacji przed uruchomieniem, więc chcesz dostarczyć mały pakiet startowy i doładować resztę zawartości później +- gra zawiera bardzo duże zasoby, takie jak obrazy czy filmy, których pobieranie chcesz odłożyć do momentu, gdy faktycznie będą potrzebne -Funkcja Aktualizacji na żywo Live Update) rozszerza koncepcję pełnomocnika kolekcji (collection proxy), oferując mechanizm, który pozwala na pobieranie i przechowywanie zasobów w pakiecie aplikacji, które celowo zostały pominięte podczas tworzenia pakietu na etapie kompilacji. +Funkcja Live update rozszerza koncepcję Collection proxy (pełnomocnika kolekcji) o mechanizm, który pozwala środowisku uruchomieniowemu pobierać i przechowywać w bundlu aplikacji zasoby celowo pominięte podczas budowania. -## Przygotowanie treści do Aktualizacji na żywo +Pozwala to podzielić zawartość na wiele archiwów: -Załóżmy, że tworzymy grę zawierającą duże zasoby graficzne o wysokiej rozdzielczości. Gra przechowuje te obrazy w kolekcjach z obiektami gry i sprite'ami wykorzystującymi te obrazy: +* _Archiwum bazowe_ +* Wspólne pliki poziomów +* Pakiet poziomów 1 +* Pakiet poziomów 2 +* ... -![Mona Lisa collection](images/live-update/mona-lisa.png) - -Aby silnik mógł dynamicznie ładować taką kolekcję, możemy po prostu dodać komponent pełnomocnika kolekcji, będącego pełnomocnikiem właśnie kolekcji `monalisa.collection`. Teraz gra może wybrać, kiedy załadować zawartość kolekcji do pamięci, wysyłając komunikat `load` do pełnomocnika kolekcji. Jeśli chcielibyśmy pójść dalej i kontrolować ładowanie zasobów zawartych w kolekcji samodzielnie możemy to zrobić, zaznaczając opcję *Exclude* w właściwościach pełnomocnika kolekcji, informując kompilator, że zawartość w `monalisa.collection` powinna być pominięta podczas tworzenia pakietu aplikacji. - -![Collection proxy excluded](images/live-update/proxy-excluded.png) - -## Ustawienia Aktualizacji na żywo - -Kiedy kompilator tworzy pakiet aplikacji, musi gdzieś przechować te wykluczone zasoby. Ustawienia projektu dla Aktualizacji na żywo (Live update settings) określają lokalizację tych zasobów. Ustawienia te znajdują się w Project ▸ Live update Settings.... Kliknięcie w tę opcję spowoduje utworzenie pliku ustawień, jeśli jeszcze nie istnieje. W pliku `game.project` wybierz, które ustawienia Aktualizacji na żywo chcesz użyć podczas kompilacji. Dzięki temu można używać różnych ustawień Aktualizacji na żywo w różnych środowiskach, na przykład na żywo, w QA, w trybie deweloperskim itp. - -When Defold creates an application bundle it needs to store any excluded resources somewhere. The project settings for Live update govern the location for those resources. The settings are found under Project ▸ Live update Settings.... This will create a settings file if none exists. In *game.project*, select which liveupdate settings file to use when bundling. This allows for using different liveupdate settings for different environments, for example for live, QA, dev etc. - -![Live update settings](images/live-update/aws-settings.png) - -Obecnie istnieją dwie metody, które Defold może wykorzystać do przechowywania zasobów. Wybierz metodę z rozwijanego menu *Mode* w oknie ustawień: - -`Amazon` -: Ta opcja mówi Defoldowi, aby automatycznie przesyłał wykluczone zasoby do Amazon Web Service (AWS) S3 bucket. Wprowadź nazwę swojego *Credential profile* (profilu uwierzytelnienia) AWS, wybierz odpowiedni *Bucket* (Kubełek) i podaj *Prefix*. Zobacz [szczegóły dotyczące](#setting_up_amazon_web_service). +## Przygotowanie zawartości do Live update -`Zip` -: Ta opcja mówi Defoldowi, aby utworzyć plik archiwum Zip z wykluczonymi zasobami. Archiwum jest zapisywane w lokalizacji określonej w ustawieniu *Export path* (ścieżka eksportu). - -## Programowanie z wykluczonymi pełnomocnikami kolekcji - -Pełnomocnik kolekcji (collection proxy), które zostały wykluczone z kompilacji, działają jak zwykłe proksy kolekcji, z jedną ważną różnicą. Wysłanie im komunikatu `load`, podczas gdy wciąż mają zasoby, które nie są dostępne w składzie pakietu, spowoduje ich niepowodzenie. - -Dlatego zanim wyślemy komunikat `load`, musimy sprawdzić, czy brakuje jakichkolwiek zasobów. Jeśli tak, musimy je pobrać, a następnie przechować. Poniższy, przykładowy kod zakłada, że zasoby są przechowywane w Amazon S3, w kubełku o nazwie `"my-game-bucket"` z prefiksem `my-resources`. - -```lua -function init(self) - self.resources_pending = 0 -- <1> - msg.post("#", "attempt_load_resources") -end - --- This function is called whenever we have tried to store a downloaded resource --- necessary for our collection proxy to load. -local function resource_store_response(self, hexdigest, status) - if status == true then - -- Successfully loaded resource - print("Resource data stored: " .. hexdigest) - - -- One less resource to go... - self.resources_pending = self.resources_pending - 1 - - -- That was all of them, time to load the proxied collection. - if self.resources_pending == 0 then - msg.post("#proxy", "load") -- <8> - end - else - -- ERROR! Failed to store the data! - print("Failed to store resource data: " .. hexdigest) - end -end - -function on_message(self, message_id, message, sender) - if message_id == hash("attempt_load_resources") then - local missing_resources = collectionproxy.missing_resources("#proxy") -- <2> - - -- initiate a download request for each of the missing resources that has not yet been tried. - for _,resource_hash in ipairs(missing_resources) do - msg.post("#", "attempt_download", { resource_hash = resource_hash}) - end - - self.resources_pending = #missing_resources -- <3> - - -- if we're running from editor all resources are there from the start. - if self.resources_pending == 0 then - msg.post("#proxy", "load") - end - elseif message_id == hash("attempt_download") then - local manifest = resource.get_current_manifest() -- <4> - local base_url = "https://my-game-bucket.s3.amazonaws.com/my-resources/" -- <5> - http.request(base_url .. message.resource_hash, "GET", function(self, id, response) - if response.status == 200 or response.status == 304 then -- <6> - -- We got the response ok. - print("storing " .. message.resource_hash) - resource.store_resource(manifest, response.response, message.resource_hash, resource_store_response) -- <7> - else - -- ERROR! Failed to download resource! - print("Failed to download resource: " .. message.resource_hash) - end - end) - elseif message_id == hash("proxy_loaded") then - msg.post(sender, "init") - msg.post(sender, "enable") - end -end -``` -1. Prosty licznik mówiący nam, ile zasobów musimy jeszcze pobrać i przechować, zanim będziemy mogli załadować kolekcję proxy. Należy zauważyć, że ten kod w ogóle nie zajmuje się obsługą błędów, więc w kodzie produkcyjnym należy śledzić operacje pobierania i przechowywania. -2. Pobierz wszelkie zasoby, które musimy pobrać i przechować. -3. Przechowaj liczbę brakujących zasobów, abyśmy mogli je zliczyć. -4. Potrzebujemy bieżącego manifestu, ponieważ zawiera on listę wszystkich zasobów w bundlu oraz informacje, czy są dostępne, czy nie. -5. Przechowujemy nasze zasoby na Amazon S3. Jeśli tworzysz archiwum Zip z zasobami, musisz hostować pliki w określonym miejscu i odnosić się do ich lokalizacji podczas pobierania ich za pomocą `http.request()`. -6. Amazon zwraca status 304, gdy pliki są w pamięci podręcznej. -7. Mamy dane w tym punkcie. Spróbujmy je przechować. -8. Przechowywanie było udane, a liczba brakujących zasobów spadła do zera. Teraz bezpiecznie możemy wysłać komunikat `"load"` do kolekcji proxy. Należy zauważyć, że jeśli pobieranie lub przechowywanie zawiedzie w którymś momencie, licznik nigdy nie osiągnie zera. - -Z kodem ładowania możemy przetestować aplikację. Jednak uruchamianie jej z edytora nie spowoduje pobierania niczego. Dzieje się tak, ponieważ funkcja Live update to funkcja paczki. W środowisku edytora nie wyklucza się żadnych zasobów. Aby upewnić się, że wszystko działa prawidłowo, trzeba utworzyć paczkę (bundle). +Załóżmy, że tworzymy grę z dużymi obrazami o wysokiej rozdzielczości. Gra przechowuje te obrazy w kolekcjach zawierających obiekt gry i sprite korzystający z obrazu: -## Pakowanie z funkcją Live update - -Pakowanie (bundle) z funkcją aktualizacji na żywo jest proste. Wybierz Project ▸ Bundle ▸ ..., a następnie platformę, dla której chcesz utworzyć pakiet aplikacji. Otwiera to okno dialogowe do pakowania: - -![Bundle Live application](images/live-update/bundle-app.png) - -Podczas pakowania wszelkie wykluczone zasoby zostaną pominięte w pakiecie aplikacji. Zaznaczając pole wyboru *Publish Live update content* (Opublikuj zawartość aktualizacji na żywo), informujesz Defolda, żeby albo przesyłał wykluczone zasoby na Amazon, albo tworzył archiwum Zip, w zależności od tego, jak skonfigurowałeś ustawienia aktualizacji na żywo (patrz wyżej). Plik manifestu dla paczki zostanie również uwzględniony w wykluczonych zasobach. +![Mona Lisa collection](images/live-update/mona-lisa.png) -Kliknij *Package* i wybierz lokalizację pakietu aplikacji. Teraz możesz uruchomić aplikację i sprawdzić, czy wszystko działa zgodnie z oczekiwaniami. +Aby silnik ładował taką kolekcję dynamicznie, wystarczy dodać komponent Collection proxy i wskazać w nim plik *`monalisa.collection`*. Gra może wtedy zdecydować, kiedy załadować zawartość tej kolekcji z nośnika do pamięci, wysyłając do Collection proxy wiadomość `load`. My jednak chcemy pójść krok dalej i samodzielnie sterować ładowaniem zasobów zawartych w kolekcji. -## Manifest +W tym celu zaznaczamy pole *Exclude* we właściwościach Collection proxy. Informuje to Defold, aby podczas tworzenia bundla aplikacji pominął całą zawartość z *`monalisa.collection`*. -Manifest to wewnętrzna struktura danych zawierająca listę wszystkich zasobów zawartych w buildzie oraz wartość skrótu każdego zasobu. Funkcjonalność Live update wykorzystuje manifest do śledzenia, co jest częścią zbudowanej gry, co można załadować z zewnętrznych źródeł i, jeśli tak się stanie, sprawdzenie, czy załadowane dane są nietknięte. +::: important +Żadne zasoby, do których odwołuje się bazowa paczka gry, nie zostaną wykluczone. +::: -Z perspektywy użytkownika manifest to liczbowy uchwyt, ukrywający detale, jak jest zarządzany, w silniku. +![Collection proxy excluded](images/live-update/proxy-excluded.png) -## Aktualizacja manifestu w funkcji Live update +## Ustawienia Live update -Z funkcją aktualizacji na żywo nowy manifest można przechowywać lokalnie w trakcie działania programu. Manifest lokalny zostanie użyty podczas uruchamiania aplikacji zamiast tego, który jest dołączony w pakiecie aplikacji. Jest to przydatne do modyfikowania lub dodawania zasobów aktualizacji na żywo do opublikowanej gry, które nie były znane podczas budowy, bez konieczności publikowania pełnej wersji. +Kiedy Defold tworzy bundle aplikacji, musi gdzieś zapisać wykluczone zasoby. Lokalizacją tych zasobów sterują ustawienia projektu dla Live update. Znajdziesz je pod Project ▸ Live update Settings.... Jeśli plik ustawień jeszcze nie istnieje, zostanie utworzony. W pliku *game.project* wybierasz, którego pliku ustawień Live update użyć podczas bundlowania. Dzięki temu możesz mieć różne ustawienia Live update dla różnych środowisk, na przykład produkcyjnego, QA albo deweloperskiego. -Podczas publikowania zasobów aktualizacji na żywo na Amazon Web Service lub do archiwum ZIP, manifest będzie uwzględniony w pakiecie obok zasobów. Nazwa pliku manifestu to `liveupdate.game.dmanifest`. +![Live update settings](images/live-update/05-liveupdate-settings-zip.png) -Rozpoczęcie pracy z silnikiem Defold po raz pierwszy po przechowywaniu manifestu spowoduje utworzenie pliku identyfikatora paczki `bundle.ver` obok manifestu. Służy to do wykrywania, czy paczka uległa zmianie od czasu przechowywania manifestu, na przykład po pełnej aktualizacji sklepu z aplikacjami. Jeśli tak się stanie, przechowany manifest zostanie usunięty z systemu plików, a nowszy manifest z paczki zastąpi go. Oznacza to, że pełna aktualizacja sklepu z aplikacjami usunie wcześniej przechowywany manifest. Wszystkie istniejące zasoby aktualizacji na żywo pozostaną jednak nietknięte. +Obecnie Defold może przechowywać zasoby na dwa sposoby. Metodę wybierasz z listy *Mode* w oknie ustawień: -### Weryfikacja manifestu +`Zip` +: Ta opcja każe Defold utworzyć archiwum Zip zawierające wszystkie wykluczone zasoby. Archiwum zostanie zapisane w lokalizacji wskazanej w ustawieniu *Export path*. -Podczas przechowywania nowego manifestu jego dane zostaną zweryfikowane, zanim zostaną faktycznie zapisane na dysku. Weryfikacja składa się z kilku sprawdzeń: +`Folder` +: Ta opcja każe Defold utworzyć katalog zawierający wszystkie wykluczone zasoby. Działa tak samo jak tryb Zip, ale zapisuje pliki w katalogu zamiast w archiwum. Przydaje się to wtedy, gdy chcesz dodatkowo przetwarzać pliki przed wysłaniem i samodzielnie spakować je później do archiwum. -* Poprawny format pliku binarnego. -* Obsługuje obecną wersję silnika lub jakąkolwiek inną obsługiwaną wersję z ustawień. -* Sygnatura kryptograficzna. -* Podpisany przy użyciu tej samej pary kluczy publicznych i prywatnych co załączony manifest. -* Zweryfikowanie, że wszystkie zasoby, których manifest oczekuje w paczce, rzeczywiście znajdują się w niej. +`Amazon` +: Ta opcja każe Defold automatycznie wysłać wykluczone zasoby do bucketa S3 w Amazon Web Services (AWS). Podaj nazwę swojego profilu AWS w polu *Credential profile*, wybierz odpowiedni *Bucket* i wpisz *Prefix*. Więcej informacji o konfiguracji konta AWS znajdziesz w [instrukcji AWS](/manuals/live-update-aws). -Z perspektywy użytkownika proces weryfikacji jest zupełnie niewidoczny, ale ważne jest zrozumienie kroków, które są zaangażowane, aby uniknąć najczęstszych problemów. +## Bundlowanie z Live update ::: important -Jeśli widzisz błąd `"ERROR:RESOURCE: Byte mismatch in decrypted manifest signature. Different keys used for signing?"` w konsoli w trakcie budowania gry na HTML5, to prawdopodobnie oznacza, że Twój serwer WWW nie serwuje wykluczonych zasobów, ani zaktualizowanego pliku manifestu z właściwym typem MIME. Upewnij się, że typ MIME to `application/octet-stream`. Możesz dodać plik `.htaccess` z pojedynczą linią `AddType application/octet-stream .` do folderu, z którego pobierane są zasoby aktualizacji na żywo. +Budowanie i uruchamianie projektu z poziomu edytora (Project ▸ Build) nie obsługuje Live Update. Aby testować Live Update, musisz zbudować bundle. ::: -### Obsługiwane wersje silnika Defold +Aby zbudować bundle z Live update, wybierz Project ▸ Bundle ▸ ..., a następnie platformę, dla której chcesz utworzyć paczkę aplikacji. Otworzy się okno bundlowania: -Manifest zawsze będzie obsługiwać wersję Defolda używaną do jego generowania. Jeśli chcesz obsługiwać dodatkowe wersje silnika, dodaj je do listy w ustawieniach aktualizacji na żywo. Jest to przydatne, jeśli Twoja gra na żywo używa innej wersji Defolda niż ta, którą używasz do generowania manifestu. +![Bundle Live application](images/live-update/bundle-app.png) -![Manifest supported engine versions](images/live-update/engine-versions-settings.png) +Podczas bundlowania wszystkie wykluczone zasoby zostaną pominięte w bundlu aplikacji. Zaznaczając pole *Publish Live update content*, każesz Defold albo wysłać wykluczone zasoby do Amazon, albo utworzyć archiwum Zip, zależnie od konfiguracji ustawień Live update. Plik manifestu bundla również zostanie dołączony do wykluczonych zasobów. -### Generowanie kluczy do podpisu +Kliknij *Package* i wybierz lokalizację dla bundla aplikacji. Następnie możesz uruchomić aplikację i sprawdzić, czy wszystko działa zgodnie z oczekiwaniami. -Sygnatura manifestu służy do weryfikowania, że nikt ze złymi zamiarami nie będzie mógł grzebać w jego treści, i że załączony manifest i nowy manifest były podpisane tymi samymi kluczami. Podpisanie jest wykonywane w procesie budowania paczki (bundlowania). +## Archiwa `.zip` -Do kryptograficznego podpisywania manifestu używa się pary kluczy publicznych/prywatnych. Podpisanie jest realizowane przy użyciu kluczy RSA o długości 512/1024/2048 bitów w formacie `.der`, które użytkownik musi dostarczyć. Możesz wygenerować je przykładowo za pomocą narzędzia `openssl`: +Plik `.zip` dla Live update zawiera pliki wykluczone z bazowej paczki gry. -```sh -$ openssl genrsa -out private_raw.key 1024 -$ openssl pkcs8 -topk8 -inform pem -in private_raw.key -outform der -nocrypt -out private.der -$ openssl rsa -in private_raw.key -outform DER -RSAPublicKey_out -pubout -out public.der -``` +Obecny pipeline potrafi utworzyć tylko jeden plik `.zip`, ale w praktyce można go podzielić na kilka mniejszych archiwów `.zip`. Dzięki temu możesz przygotować mniejsze pobrania dla gry, na przykład pakiety poziomów albo sezonową zawartość. Każdy plik `.zip` zawiera również manifest opisujący metadane wszystkich zasobów znajdujących się w tym archiwum. -To spowoduje wygenerowanie plików `private_raw.key` (można go bezpiecznie usunąć), `private.der` i `public.der`. Aby użyć kluczy do podpisywania, otwórz widok ustawień aktualizacji na żywo (live update settings) i wskaz odpowiednie pola na wygenerowane klucze. +## Dzielenie archiwów `.zip` -![Manifest signature key-pair](images/live-update/manifest-keys.png) +Często warto podzielić wykluczoną zawartość na kilka mniejszych archiwów, aby precyzyjniej sterować użyciem zasobów. Typowym przykładem jest gra podzielona na kilka pakietów poziomów. Innym przykładem jest umieszczenie różnych sezonowych dekoracji interfejsu w osobnych archiwach i ładowanie tylko tego motywu, który jest aktualnie aktywny. -### Programowanie z manifestem aktualizacji na żywo -Dodając do powyższego przykładu skryptu, dodajmy poniższą funkcję zwrotną: +Graf zasobów jest zapisywany w pliku `build/default/game.graph.json`, generowanym automatycznie przy każdym bundlowaniu projektu. Plik ten zawiera listę wszystkich zasobów projektu oraz zależności każdego z nich. Przykładowy wpis: -```lua -local function store_manifest_cb(self, status) - if status == resource.LIVEUPDATE_OK then - print("Successfully stored manifest!") - else - print("Failed to store manifest, status: ", status) - end -end -``` -i następujący kod do funkcji `on_message`, aby obsłużyć wiadomość `attempt_download_manifest`: - -```lua -... -elseif message_id == hash("attempt_download_manifest") then - local base_url = "https://my-game-bucket.s3.amazonaws.com/my-resources/" -- <1> - http.request(base_url .. MANIFEST_FILENAME, "GET", function(self, id, response) - if response.status == 200 or response.status == 304 then - -- We got the response ok. - print("verifying and storing manifest " .. MANIFEST_FILENAME) - resource.store_manifest(response.response, store_manifest_cb) -- <2> - else - -- ERROR! Failed to download manifest! - print("Failed to download manifest: " .. MANIFEST_FILENAME) - end - end) -end +```json +{ + "path" : "/game/player.goc", + "hexDigest" : "caa342ec99794de45b63735b203e83ba60d7e5a1", + "children" : [ "/game/ship.spritec", "/game/player.scriptc" ] +} ``` -1. Manifest zostanie przechowywany na Amazon S3 obok reszty zasobów aktualizacji na żywo. Tak, jak poprzedniu, jeśli tworzysz archiwum Zip z zasobami, musisz hostować je gdzieś i podać referencję do ich lokalizacji podczas pobierania przy użyciu `http.request()`. -2. Podobnie jak w przypadku pobierania i przechowywania zasobów, wywołanie `resource.store_manifest` przyjmuje dane manifestu do pobrania i funkcję zwrotną jako argumenty. Funkcja zwrotna zweryfikuje manifest i zapisze go w pamięci lokalnej. - -Jeśli `resource.store_manifest` zakończy się powodzeniem, nowy manifest będzie teraz w pamięci lokalnej. Następnym razem, gdy silnik zostanie uruchomiony, używany będzie ten nowy manifest zamiast tego, który był dołączony do gry. - -### Uwagi - -Istnieją pewne rzeczy, o których warto wiedzieć, jeśli planujesz użyć tej funkcji do przechowywania nowego manifestu z aktualizacją na żywo. - -* Możliwe jest tylko dodawanie lub modyfikowanie zasobów używanych przez kolekcje proxy oznaczone jako `Exclude` w nowym manifeście. Nie można dokonywać zmian w już dodanych zasobach lub zasobach, które nie znajdują się w wykluczonych pełnomocnikach kolekcji. Na przykład, wprowadzenie zmian w skrypcie używanym przez dołączoną kolekcję spowoduje, że system zasobów będzie szukał tego zasobu w archiwum danych paczki. Jednak ponieważ paczka gry nie zmieniła się (zmienił się tylko manifest), zmienionego skryptu nie można odnaleźć i w konsekwencji nie można go załadować. - -* Nawet jeśli funkcjonalność ta pozwala na bardzo szybkie wprowadzanie zmian lub łatanie błędów bez pełnego, nowego release aplikacji w sklepie, live update należy używać z zachowaniem szczególnej ostrożności. Dołączenie nowego manifestu powinno poprzedzać wszystko, co jest potrzebne przy faktycznym wydaniu nowej wersji gry (testowanie, QA, itd.). - -## Konfiguracja Amazon Web Service +Każdy wpis zawiera pole `path`, które reprezentuje unikalną ścieżkę zasobu w projekcie. Pole `hexDigest` to kryptograficzny odcisk zasobu i jednocześnie nazwa pliku używana w archiwum `.zip` dla Live update. Pole `children` zawiera listę zależności, od których dany zasób zależy. W powyższym przykładzie `/game/player.goc` zależy od komponentu sprite i komponentu script. -Aby korzystać z funkcji Defold Live Update razem z usługami Amazon, potrzebujesz konta Amazon Web Services. Jeśli jeszcze nie masz konta, możesz je utworzyć [tutaj](https://aws.amazon.com/). +Możesz sparsować plik `game.graph.json` i użyć tych informacji do znalezienia grup wpisów w grafie zasobów, a następnie zapisać odpowiadające im zasoby w osobnych archiwach razem z oryginalnym plikiem manifestu. Manifest zostanie później przycięty w runtime tak, aby zawierał tylko pliki obecne w danym archiwum. -W tej sekcji wyjaśnimy, jak utworzyć nowego użytkownika z ograniczonym dostępem w usługach Amazon Web Services, który może być wykorzystywany razem z edytorem Defold do automatycznego przesyłania zasobów aktualizacji na żywo podczas pakowania gry oraz jak skonfigurować Amazon S3, aby umożliwić klientom gier pobieranie zasobów. Dodatkowe informacje na temat konfigurowania Amazon S3 znajdziesz w [dokumentacji Amazon S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html). +## Live Update na Androidzie -1. Utwórz bucket (kubełek) na zasoby aktualizacji na żywo +Możesz używać Play Asset Delivery do pobierania i montowania zawartości Live Update. Więcej informacji znajdziesz [w oficjalnej instrukcji](https://defold.com/extension-pad/). - Otwórz menu `Services` i wybierz `S3`, które znajduje się w kategorii _Storage_ ([Amazon S3 Console](https://console.aws.amazon.com/s3)). Zobaczysz swoje istniejące kubełki wraz z opcją utworzenia nowego kubełka. Choć możliwe jest użycie istniejącego kubełka, zalecamy utworzenie nowego kubełka na zasoby aktualizacji na żywo, aby łatwo ograniczyć dostęp. +## Weryfikacja zawartości - ![Create a bucket](images/live-update/01-create-bucket.png) +Jedną z ważniejszych cech systemu Live update jest możliwość używania wielu archiwów zawartości, potencjalnie pochodzących z wielu różnych wersji Defold. -2. Dodaj politykę kubełka (bucket policy) do swojego kubełka +Domyślne zachowanie `liveupdate.add_mount()` polega na dodaniu kontroli wersji silnika podczas dołączania mounta. Oznacza to, że zarówno bazowe archiwum gry, jak i archiwa Live update muszą zostać utworzone w tym samym czasie, tą samą wersją silnika i z użyciem opcji bundlowania. W przeciwnym razie klient unieważni wcześniej pobrane archiwa i wymusi ponowne pobranie zawartości. - Wybierz kubełek, który chcesz użyć, otwórz panel *Properties* i rozwiń opcje *Permissions* w panelu. Otwórz politykę kubełka, klikając przycisk *Add bucket policy*. Polityka kubełka w tym przykładzie umożliwi anonimowemu użytkownikowi pobieranie plików z kubełka, co umożliwi graczowi pobieranie zasobów aktualizacji na żywo wymaganych przez grę. Dodatkowe informacje na temat polityk kubełka znajdziesz w [dokumentacji Amazon o polityce](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-iam-policies.html). +To zachowanie można wyłączyć odpowiednią flagą opcji. Po wyłączeniu pełna odpowiedzialność za weryfikację zgodności zawartości spoczywa na programiście, który musi zagwarantować, że każde archiwum Live update będzie działało z uruchomionym silnikiem. - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "AddPerm", - "Effect": "Allow", - "Principal": "*", - "Action": "s3:GetObject", - "Resource": "arn:aws:s3:::defold-liveupdate-example/*" - } - ] - } - ``` +Zalecamy przechowywanie pewnych metadanych dla każdego mounta, aby _bezpośrednio po uruchomieniu_ zdecydować, czy dany mount lub archiwum należy usunąć. Jednym ze sposobów jest dodanie dodatkowego pliku do archiwum zip po zbudowaniu gry, na przykład `metadata.json` zawierającego potrzebne informacje. Następnie przy starcie gry można go odczytać przez `sys.load_resource("/metadata.json")`. _Pamiętaj, że dane niestandardowe każdego mounta muszą mieć unikalną nazwę. W przeciwnym razie silnik zwróci plik z mounta o najwyższym priorytecie._ - ![Bucket policy](images/live-update/02-bucket-policy.png) +Jeśli tego nie zrobisz, możesz doprowadzić do sytuacji, w której zawartość okaże się całkowicie niezgodna z silnikiem i wymusi zamknięcie aplikacji. -3. Dodaj konfigurację CORS do swojego kubełka (opcjonalnie) +## Mounty - Udostępnianie zasobów z różnych domen ([Cross-Origin Resource Sharing - CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)) to mechanizm, który umożliwia witrynie pobieranie zasobu z innej domeny za pomocą JavaScript. Jeśli planujesz opublikować swoją grę jako klienta HTML5, będziesz musiał dodać konfigurację CORS do swojego kubełka. +System Live update może używać jednocześnie wielu archiwów zawartości. Każde archiwum jest „montowane” do systemu zasobów silnika z własną nazwą i priorytetem. - Wybierz kubełek, który chcesz użyć, otwórz panel *Properties* i rozwiń opcje *Permissions*. Otwórz konfigurację CORS klikając przycisk *Add CORS Configuration*. Konfiguracja w tym przykładzie umożliwi dostęp z dowolnej witryny, określając domenę wieloznaczną, choć możliwe jest bardziej restrykcyjne ograniczenie dostępu, jeśli wiesz, na jakich domenach zamierzasz udostępnić swoją grę. Dodatkowe informacje na temat konfiguracji CORS w Amazonie znajdziesz w [dokumentacji Amazono CORS](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html). +Jeśli dwa archiwa zawierają ten sam plik `sprite.texturec`, silnik załaduje go z mounta o wyższym priorytecie. - ```xml - - - - * - GET - - - ``` +Silnik nie utrzymuje referencji do zasobów znajdujących się w mouncie. Gdy zasób zostanie już załadowany do pamięci, archiwum może zostać odmontowane. Sam zasób pozostanie w pamięci do momentu jego zwolnienia. - ![CORS configuration](images/live-update/03-cors-configuration.png) +Mounty są automatycznie dodawane ponownie po restarcie silnika. -4. Utwórz politykę IAM - - Otwórz menu *Services* i wybierz *IAM*, które znajduje się w kategorii _Security, Identity & Compliance_ category ([Amazon IAM Console](https://console.aws.amazon.com/iam)). Wybierz *Policies* w menu po lewej stronie i zobaczysz swoje istniejące polityki, wraz z opcją utworzenia nowej polityki. - - Kliknij przycisk *Create Policy* i wybierz _Create Your Own Policy_. Polityka w tym przykładzie umożliwi użytkownikowi wyświetlenie wszystkich kubełków, co jest wymagane tylko podczas konfigurowania projektu Defold dla aktualizacji na żywo. Będzie również umożliwiać użytkownikowi uzyskanie listy kontroli dostępu (Access Control List - ACL) i przesyłanie zasobów do konkretnej nazwy kubełka używanej do zasobów aktualizacji na żywo. Dodatkowe informacje na temat Amazon Identity and Access Management (IAM) znajdziesz w [dokumentacji Amazon](http://docs.aws.amazon.com/IAM/latest/UserGuide/access.html). - - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:ListAllMyBuckets" - ], - "Resource": "arn:aws:s3:::*" - }, - { - "Effect": "Allow", - "Action": [ - "s3:GetBucketAcl" - ], - "Resource": "arn:aws:s3:::defold-liveupdate-example" - }, - { - "Effect": "Allow", - "Action": [ - "s3:PutObject" - ], - "Resource": "arn:aws:s3:::defold-liveupdate-example/*" - } - ] - } - ``` - - ![IAM policy](images/live-update/04-create-policy.png) - -5. Utwórz użytkownika do dostępu programistycznego - - Otwórz menu *Services* i wybierz *IAM*, które znajduje się w kategorii _Security, Identity & Compliance_ category ([Amazon IAM Console](https://console.aws.amazon.com/iam)). Wybierz *Users* w menu po lewej stronie i zobaczysz swoich istniejących użytkowników wraz z opcją dodania nowego użytkownika. Choć możliwe jest użycie istniejącego użytkownika, zalecamy dodanie nowego użytkownika do zasobów aktualizacji na żywo, aby łatwo ograniczyć dostęp. - - Kliknij przycisk *Add User*, podaj nazwę użytkownika i wybierz *Programmatic access* jako *Access type*, a następnie kliknij *Next: Permissions*. Wybierz *Attach existing policies directly* i wybierz politykę, którą utworzyłeś w kroku 4. - - Po zakończeniu procesu zostaniesz dostarczony z *Access key ID* i *Secret access key*. - - ::: important - *Bardzo ważne* jest, aby zachować te klucze, ponieważ nie będziesz w stanie ich odzyskać z Amazon po opuszczeniu strony. - ::: - -6. Utwórz plik profilu poświadczeń +::: sidenote +Zamontowanie archiwum nie kopiuje go ani nie przenosi. Silnik przechowuje jedynie ścieżkę do archiwum. Oznacza to, że programista może usunąć archiwum w dowolnym momencie, a mount zostanie usunięty przy następnym uruchomieniu. +::: - W tym momencie powinieneś już mieć kubełek (bucket), skonfigurowaną politykę kubełka, dodaną konfigurację CORS, utworzoną politykę użytkownika i utworzonego nowego użytkownika. Jedyną rzeczą, która pozostała, jest utworzenie [pliku profilu poświadczeń](https://aws.amazon.com/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks), aby Defold mógł uzyskać dostęp do kubełka w twoim imieniu. +## Skryptowanie z Live Update -Utwórz nowy katalog `~/.aws` w folderze domowym i utwórz w nim plik o nazwie `credentials`. +Aby faktycznie korzystać z zawartości Live update, musisz pobrać dane i zamontować je w swojej grze. +Więcej informacji znajdziesz w [instrukcji skryptowania Live update](/manuals/live-update-scripting). - ```bash - $ mkdir ~/.aws - $ touch ~/.aws/credentials - ``` - Plik `~/.aws/credentials` zawiera twoje poświadczenia dostępu do Amazon Web Services poprzez dostęp programistyczny i jest standaryzowany sposób na zarządzanie poświadczeniami AWS. Otwórz plik w edytorze tekstowym i wprowadź swoje *Access key ID* i *Secret access key* w formacie pokazanym poniżej. - - ```ini - [defold-liveupdate-example] - aws_access_key_id = - aws_secret_access_key = - ``` - Identyfikator określony w nawiasach kwadratowych, w tym przykładzie `_defold-liveupdate-example_`, jest taki sam jak identyfikator, który powinieneś podać podczas konfigurowania ustawień aktualizacji na żywo projektu w edytorze Defold. - - ![Live update settings](images/live-update/05-liveupdate-settings.png) - -## Uwagi dotyczące rozwoju oprogramowania +## Uwagi deweloperskie Debugowanie -: Podczas uruchamiania spakowanej wersji swojej gry nie masz bezpośredniego dostępu do konsoli. To może sprawić problemy z debugowaniem. Niemniej jednak, możesz uruchomić aplikację z wiersza poleceń lub podwójnie klikając na plik wykonywalny w paczce: +: Gdy uruchamiasz zbundlowaną wersję gry, nie masz bezpośredniego dostępu do konsoli, co utrudnia debugowanie. Możesz jednak uruchomić aplikację z wiersza poleceń albo klikając bezpośrednio plik wykonywalny znajdujący się w bundlu: ![Running a bundle application](images/live-update/run-bundle.png) - Teraz gra zaczyna się z oknem konsoli, które będzie wyświetlać wszystkie instrukcje `print()`: + Gra uruchomi się wtedy z oknem powłoki, w którym będą widoczne wszystkie wywołania `print()`: ![Console output](images/live-update/run-bundle-console.png) -Wymuszanie ponownego pobierania zasobów -: Gdy aplikacja przechowuje zasoby, trafiają one na dysk lokalny komputera lub urządzenia przenośnego. Gdy zrestartujesz aplikację, zasoby są dostępne i gotowe do użycia. Podczas pracy nad projektem gry może być potrzeba usunięcia zasobów i wymuszenia na aplikacji ich ponownego pobrania. +Wymuszenie ponownego pobrania zasobów +: Programista może pobrać zawartość do dowolnego pliku lub katalogu, ale często trafia ona do ścieżki aplikacji. Lokalizacja katalogu wsparcia aplikacji zależy od systemu operacyjnego. Możesz ją sprawdzić przez `print(sys.get_save_file("", ""))`. - Defold tworzy folder o nazwie hasha stworzonej paczki na urządzeniu w folderze obsługi aplikacji. Jeśli usuniesz pliki z tego folderu, aplikacja unieważni zasoby z manifestu, dzięki czemu będziesz mógł je pobrać i ponownie przechować. + Plik `liveupdate.mounts` znajduje się w pamięci lokalnej, a jego ścieżka jest wypisywana do konsoli przy starcie jako `"INFO:LIVEUPDATE: Live update folder located at: ..."` ![Local storage](images/live-update/local-storage.png) - - Lokalizacja folderu obsługi aplikacji zależy od systemu operacyjnego. Możesz ją znaleźć, używając polecenia `print(sys.get_save_file("", ""))`. diff --git a/docs/pl/manuals/physics-shapes.md b/docs/pl/manuals/physics-shapes.md index a51805cc..53d6ff9b 100644 --- a/docs/pl/manuals/physics-shapes.md +++ b/docs/pl/manuals/physics-shapes.md @@ -1,74 +1,159 @@ --- -title: Kształty Kolizji -brief: Ta instrukcja opisuje szczegóły działania kształtów kolizji silnika fizyki. +title: Kształty kolizji +brief: Komponent obiektu kolizji może używać kilku kształtów podstawowych albo jednego kształtu złożonego. --- -# Kształty Kolizji +# Kształty kolizji -Komponent Obiektu Kolizji (Collision Object) może używać kilku kształtów podstawowych (ang. primitive shapes) lub pojedynczego kształtu złożonego. +Komponent obiektu kolizji może używać kilku kształtów podstawowych albo jednego kształtu złożonego. ### Kształty podstawowe -Podstawowe kształty to *box* - prostokąt, *sphere* - sfera i *capsule* - kapsuła. Aby dodać kształt podstawowy, kliknij prawym przyciskiem myszy obiekt kolizji, a następnie wybierz Add Shape: +Kształty podstawowe to *box*, *sphere* i *capsule*. Aby dodać kształt podstawowy, kliknij prawym przyciskiem myszy obiekt kolizji i wybierz Add Shape: ![Add a primitive shape](images/physics/add_shape.png) -## Kształt prostokątny -Kształt prostokątny (box) posiada pozycję, rotację i wymiary (szerokość, wysokość i głębokość): +## Kształt prostokątny (box) -![Kształt prostokątny](images/physics/box.png) +Kształt prostokątny (box) ma pozycję, obrót i wymiary: szerokość, wysokość oraz głębokość: -## Kształt sfery -Sfera (sphere) posiada pozycję, rotację i średnicę: +![Box shape](images/physics/box.png) -![Kształt sfery](images/physics/sphere.png) +## Kształt sfery (sphere) -## Kształt kapsuły -Kapsuła posiada pozycję, rotację, średnicę i wysokość: +Kształt sfery (sphere) ma pozycję, obrót i średnicę: -![Kształt kapsuły](images/physics/capsule.png) +![Sphere shape](images/physics/sphere.png) + +## Kształt kapsuły (capsule) + +Kształt kapsuły (capsule) ma pozycję, obrót, średnicę i wysokość: + +![Sphere shape](images/physics/capsule.png) ::: important -Kształty kapsuły są obsługiwane tylko w przypadku korzystania z fizyki 3D (skonfigurowanej w sekcji *Physics* w pliku *game.project*). +Kształty capsule są obsługiwane tylko przy korzystaniu z fizyki 3D, skonfigurowanej w sekcji *Physics* pliku *game.project*. ::: ### Kształty złożone -Kształty złożone (ang. complex shapes) można utworzyć z komponentu mapy kafelków lub z kształtu wypukłego (convex hull shape). -## Kształt kolizji mapy kafelków -Defold zawiera funkcję, która umożliwia łatwe generowanie kształtów fizyki dla Źródła Kafelków (Tile Source) używanego przez mapę kafelków. W [instrukcji Źródła Kafelków](/manuals/tilesource/#tile-source-collision-shapes) wyjaśniono, jak dodać grupy kolizji do źródła kafelków i przypisać kafelki do grup kolizji ([przykład](/examples/tilemap/collisions/)). +Kształt złożony można utworzyć albo z komponentu Tile map (mapy kafelków), albo z kształtu convex hull. + +## Kształt kolizji Tile map -Aby dodać kolizję do mapy kafelków: +Defold zawiera funkcję, która pozwala łatwo generować kształty fizyki dla Tile source używanego przez Tile map. W [instrukcji Tile source](/manuals/tilesource/#tile-source-collision-shapes) wyjaśniono, jak dodawać grupy kolizji do Tile source i przypisywać kafelki do grup kolizji ([przykład](/examples/tilemap/collisions/)). -1. Dodaj mapę kafelków do obiektu gry, klikając go prawym przyciskiem myszy i wybierając Add Component File. Wybierz plik mapy kafelków. -2. Dodaj komponent obiektu kolizji do obiektu gry, klikając go prawym przyciskiem myszy i wybierając Add Component ▸ Collision Object. -3. Zamiast dodawać kształty do komponentu, ustaw właściwość Kształt kolizji na plik mapa kafelków (*tilemap*). -4. Skonfiguruj *Properties* komponentu obiektu kolizji. +Aby dodać kolizję do Tile map: -![Kształt kolizji mapy kafelków](images/physics/collision_tilemap.png) +1. Dodaj Tile map do obiektu gry, klikając prawym przyciskiem myszy obiekt gry i wybierając Add Component File. Następnie wybierz plik Tile map. +2. Dodaj komponent obiektu kolizji do obiektu gry, klikając prawym przyciskiem myszy obiekt gry i wybierając Add Component ▸ Collision Object. +3. Zamiast dodawać kształty do komponentu, ustaw właściwość *Collision Shape* na plik *tilemap*. +4. Skonfiguruj *Properties* komponentu obiektu kolizji jak zwykle. + +![Tilesource collision](images/physics/collision_tilemap.png) ::: important -Należy zauważyć, że właściwość *Group* **nie** jest tutaj używana, ponieważ grupy kolizji są definiowane w źródle kafelków (tile source) mapy kafelków. +Zwróć uwagę, że właściwość *Group* **nie** jest tutaj używana, ponieważ grupy kolizji są definiowane w Tile source mapy kafelków. ::: -## Kształt kolizji wypukłej -Defold zawiera funkcję, która umożliwia tworzenie kształtu wypukłego (convex hull shape) z trzech lub więcej punktów. Możesz użyć zewnętrznego narzędzia, takiego jak [Defold Polygon Editor](/assets/defoldpolygoneditor/) lub [Physics Body Editor](https://selimanac.github.io/physics-body-editor/), aby utworzyć kształt wypukły. +## Kształt wypukły (convex hull) -1. Utwórz plik kształtu wypukłego (o rozszerzeniu pliku .`.convexshape`) za pomocą zewnętrznego edytora. -2. Zamiast dodawać kształty do komponentu obiektu kolizji, ustaw właściwość *Collision Shape* na plik *convex shape*. +Defold zawiera funkcję pozwalającą tworzyć kształt wypukły (convex hull) z trzech lub większej liczby punktów. + +1. Utwórz plik kształtu convex hull o rozszerzeniu `.convexshape` przy użyciu zewnętrznego edytora. +2. Edytuj plik ręcznie w edytorze tekstu albo przy użyciu zewnętrznego narzędzia, opisanego poniżej. +3. Zamiast dodawać kształty do komponentu obiektu kolizji, ustaw właściwość *Collision Shape* na plik *convex shape*. + +### Format pliku + +Format pliku convex hull używa tego samego formatu danych co pozostałe pliki Defold, czyli tekstowego formatu protobuf. Kształt convex hull definiuje punkty bryły. W fizyce 2D punkty powinny być podane w kolejności przeciwnej do ruchu wskazówek zegara. W trybie fizyki 3D używana jest abstrakcyjna chmura punktów. Przykład dla 2D: + +``` +shape_type: TYPE_HULL +data: 200.000 +data: 100.000 +data: 0.0 +data: 400.000 +data: 100.000 +data: 0.0 +data: 400.000 +data: 300.000 +data: 0.0 +data: 200.000 +data: 300.000 +data: 0.0 +``` + +Powyższy przykład definiuje cztery narożniki prostokąta: + +``` + 200x300 400x300 + 4---------3 + | | + | | + | | + | | + 1---------2 + 200x100 400x100 +``` + +## Narzędzia zewnętrzne + +Istnieje kilka narzędzi zewnętrznych, których można użyć do tworzenia kształtów kolizji: + +* [Physics Editor](https://www.codeandweb.com/physicseditor/tutorials/how-to-create-physics-shapes-for-defold) od CodeAndWeb pozwala tworzyć obiekty gry ze sprite’ami i pasującymi do nich kształtami kolizji. +* [Defold Polygon Editor](https://rossgrams.itch.io/defold-polygon-editor) można użyć do tworzenia kształtów convex hull. +* [Physics Body Editor](https://selimanac.github.io/physics-body-editor/) również można użyć do tworzenia kształtów convex hull. -::: sidenote -Kształt taki nie będzie rysowany w Edytorze. Możesz włączyć [debugowanie fizyki](/manuals/debugging/#debugging-problems-with-physics) podczas działania programu, aby zobaczyć kształt. -::: # Skalowanie kształtów kolizji -Obiekt kolizji i jego kształty dziedziczą skalę obiektu gry. Aby wyłączyć to zachowanie, odznacz pole wyboru "[Allow Dynamic Transforms](/manuals/project-settings/#allow-dynamic-transforms)", czyli Zezwalaj na dynamiczne transformacje w sekcji *Physics* pliku *game.project*. Należy pamiętać, że obsługiwane jest tylko skalowanie jednolite (uniform), a jeśli skala nie jest jednolita, zostanie użyta najmniejsza wartość skali. +Obiekt kolizji i jego kształty dziedziczą skalę obiektu gry. Aby wyłączyć to zachowanie, odznacz pole [Allow Dynamic Transforms](/manuals/project-settings/#allow-dynamic-transforms) w sekcji *Physics* pliku *game.project*. Zwróć uwagę, że obsługiwane jest tylko skalowanie jednolite, a jeśli skala nie jest jednolita, użyta zostanie najmniejsza wartość skali. + +# Zmienianie rozmiaru kształtów kolizji + +Rozmiar kształtów obiektu kolizji można zmieniać w czasie działania przy użyciu `physics.set_shape()`. Przykład: + +```lua +-- ustaw dane kształtu capsule +local capsule_data = { + type = physics.SHAPE_TYPE_CAPSULE, + diameter = 10, + height = 20, +} +physics.set_shape("#collisionobject", "my_capsule_shape", capsule_data) + +-- ustaw dane kształtu sphere +local sphere_data = { + type = physics.SHAPE_TYPE_SPHERE, + diameter = 10, +} +physics.set_shape("#collisionobject", "my_sphere_shape", sphere_data) + +-- ustaw dane kształtu box +local box_data = { + type = physics.SHAPE_TYPE_BOX, + dimensions = vmath.vector3(10, 10, 5), +} +physics.set_shape("#collisionobject", "my_box_shape", box_data) +``` + +::: sidenote +Na obiekcie kolizji musi już istnieć kształt właściwego typu o podanym id. +::: # Obracanie kształtów kolizji ## Obracanie kształtów kolizji w fizyce 3D + Kształty kolizji w fizyce 3D można obracać wokół wszystkich osi. + ## Obracanie kształtów kolizji w fizyce 2D -Kształty kolizji w fizyce 2D można obracać tylko wokół osi Z. Obrót wokół osi X lub Y spowoduje nieprawidłowe wyniki i powinno się go unikać, nawet przy obracaniu o 180 stopni, aby efektywnie odwrócić kształt wzdłuż osi x lub y. Aby odwrócić kształt fizyczny, zaleca się korzystanie z [`physics.set_hlip(url, flip)`](/ref/stable/physics/?#physics.set_hflip:url-flip) i [`physics.set_vlip(url, flip)`](/ref/stable/physics/?#physics.set_vflip:url-flip). + +Kształty kolizji w fizyce 2D można obracać tylko wokół osi Z. Obracanie wokół osi X albo Y daje nieprawidłowe wyniki i należy go unikać, nawet przy obrocie o 180 stopni, który pozornie miałby tylko odwrócić kształt wzdłuż osi X albo Y. Do odwracania kształtu fizyki zaleca się używać [`physics.set_hlip(url, flip)`](/ref/stable/physics/?#physics.set_hflip:url-flip) oraz [`physics.set_vlip(url, flip)`](/ref/stable/physics/?#physics.set_vflip:url-flip). + + +# Debugowanie + +Możesz [włączyć debugowanie fizyki](/manuals/debugging/#debugging-problems-with-physics), aby zobaczyć kształty kolizji w czasie działania. diff --git a/docs/pl/manuals/project-settings.md b/docs/pl/manuals/project-settings.md index da7e9572..0e17d7f7 100644 --- a/docs/pl/manuals/project-settings.md +++ b/docs/pl/manuals/project-settings.md @@ -1,530 +1,840 @@ --- -title: Ustawienie projektu -brief: Instrukcja opisuje poszczególne ustawienia projektu w Defoldzie. +title: Ustawienia projektu +brief: Ta instrukcja opisuje, jak działają ustawienia specyficzne dla projektu w silniku Defold. --- -# Ustawienie projektu +# Ustawienia projektu -Plik *game.project* zawiera wszystkie ustawienia wykorzystywane w projekcie. Jest to specjalny plik i musi pozostać w głównej lokalizacji Twojego projektu, a nazwa musi pozostać niezmieniona - *game.project*. Pierwsza rzeczą jaką zajmuje się silnik Defold zaraz po starcie Twojej gry jest właśnie wyszukanie tego pliku. (W systemie Windows można przypisać plik .project do domyślnego otwierania za pomocą aplikacji Defold) +Plik *game.project* zawiera wszystkie ustawienia obowiązujące w całym projekcie. Musi znajdować się w katalogu głównym projektu i musi mieć nazwę *game.project*. Jedną z pierwszych czynności wykonywanych przez silnik podczas uruchamiania gry jest odnalezienie właśnie tego pliku. -Każde ustawienie w tym pliku przynależy do konkretnej kategorii. Defold wyświetla ustawienia z tego pliku podzielone właśnie na te kategorie. +Każde ustawienie w tym pliku należy do określonej kategorii. Po otwarciu pliku Defold wyświetla ustawienia pogrupowane według kategorii. ![Project settings](images/project-settings/settings.jpg) -Poniżej przedstawiono wszystkie dostępne ustawienia, poukładane w sekcje. Niektóre z nich nie są pokazywane po otwarciu w Edytorze Defold (oznaczono je "hidden setting" (z ang. ukryte ustawienie))), ale wciąż można je zmienić ręcznie otwierając plik *game.project* w edytorze tekstu: Open With ▸ Text Editor. +## File format -## Project +Ustawienia w *game.project* najczęściej zmienia się bezpośrednio w Defold, ale sam plik można też edytować w dowolnym zwykłym edytorze tekstu. Plik używa formatu INI i wygląda następująco: + +```ini +[category1] +setting1 = value +setting2 = value +[category2] +... +``` + +Rzeczywisty przykład: + +```ini +[bootstrap] +main_collection = /main/main.collectionc +``` + +oznacza, że ustawienie *main_collection* należy do kategorii *bootstrap*. Gdy używasz odwołania do pliku, jak w powyższym przykładzie, ścieżka musi kończyć się literą `c`, co oznacza odwołanie do skompilowanej wersji pliku. Zwróć też uwagę, że katalog zawierający *game.project* jest katalogiem głównym projektu, dlatego ścieżka ustawienia zaczyna się od `/`. + +## Runtime access + +Każdą wartość z *game.project* można odczytać w czasie działania za pomocą funkcji [`sys.get_config_string(key)`](/ref/sys/#sys.get_config_string), [`sys.get_config_number(key)`](/ref/sys/#sys.get_config_number) i [`sys.get_config_int(key)`](/ref/sys/#sys.get_config_int). Przykład: + +```lua +local title = sys.get_config_string("project.title") +local gravity_y = sys.get_config_number("physics.gravity_y") +``` + +::: sidenote +Klucz składa się z nazwy kategorii i nazwy ustawienia, oddzielonych kropką, zapisanych małymi literami, a spacje zastępuje się znakami podkreślenia. Przykładowo pole `Title` z kategorii `Project` staje się `project.title`, a `Gravity Y` z kategorii `Physics` staje się `physics.gravity_y`. +::: + +## Sections and settings + +Poniżej znajdują się wszystkie dostępne ustawienia, uporządkowane według kategorii. + +### Project #### Title -Tytuł aplikacji +Tytuł aplikacji. #### Version -Wersja aplikacji +Wersja aplikacji. + +#### Publisher +Nazwa wydawcy. + +#### Developer +Nazwa dewelopera. #### Write Log File -Określa, kiedy silnik zapisuje log do pliku. Opcje: +Określa, kiedy silnik zapisuje plik logu. Dostępne opcje: -- "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. +- `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 -Jeśli uruchamiasz więcej niż jedną instancję z edytora, plik będzie nazwany *instance_2_log.txt*, gdzie `2` to indeks instancji. Jeśli uruchamiasz pojedynczą instancję lub paczkę, plik będzie nazwany *log.txt*. Lokalizacja pliku logu będzie jedną z poniższych (sprawdzane w tej kolejności): +Jeśli uruchamiasz z edytora więcej niż jedną instancję, plik będzie miał nazwę *instance_2_log.txt*, gdzie `2` oznacza indeks instancji. Przy pojedynczej instancji lub uruchomieniu z bundla plik będzie miał nazwę *log.txt*. Lokalizacja pliku logu będzie jedną z poniższych ścieżek, sprawdzanych w tej kolejności: 1. Ścieżka określona w *project.log_dir* (ukryte ustawienie) 2. Systemowa ścieżka logów: - * macOS/iOS: `NSDocumentDirectory` - * Android: `Context.getExternalFilesDir()` - * Inne: katalog aplikacji -3. Ścieżka wsparcia aplikacji: - * macOS/iOS: `NSApplicationSupportDirectory` - * Windows: `CSIDL_APPDATA` (np. `C:\Users\\AppData\Roaming`) - * Android: `Context.getFilesDir()` - * Linux: zmienna środowiskowa `HOME` + * macOS/iOS: `NSDocumentDirectory` + * Android: `Context.getExternalFilesDir()` + * Pozostałe platformy: katalog główny aplikacji +3. Ścieżka danych wsparcia aplikacji: + * macOS/iOS: `NSApplicationSupportDirectory` + * Windows: `CSIDL_APPDATA` (na przykład `C:\Users\\AppData\Roaming`) + * Android: `Context.getFilesDir()` + * Linux: zmienna środowiskowa `HOME` + +#### Minimum Log Level +Określa minimalny poziom logowania. Wyświetlane będą tylko komunikaty na tym poziomie lub wyższym. #### Compress Archive -Umożliwia kompresowanie archiwów podczas budowania paczki. Zauważ, że dotyczy to wszystkich platform oprócz systemu Android, gdzie plik apk zawiera od razy skompresowane dane. +Włącza kompresję archiwów podczas bundlowania. Obecnie dotyczy to wszystkich platform poza Androidem, gdzie plik APK i tak zawiera już skompresowane dane. #### Dependencies -Zależoności - lista adresów URL do projektów bibliotek (*Library URL*s). Więcej szczegółów znajdziesz w [instrukcji do Bibliotek](/manuals/libraries/). +Lista adresów URL do projektów będących *Library URL*. Więcej informacji znajdziesz w [instrukcji Libraries](/manuals/libraries/). #### Custom Resources -Własne zasoby - lista oddzielonych przecinkami zasobów, które będą dołączone do projektu. Jeśli określone są lokalizacje, wszystkie pliki i katalogi w danej lokalizacji są rekursywnie załączane. Zasoby te można załadować w trakcie działania programu używając [`sys.load_resource()`](/ref/sys/#sys.load_resource). +`custom_resources` +: Zasoby dołączane do głównego archiwum gry przez pole *Custom Resources* w *game.project*. Więcej o ich ładowaniu znajdziesz w [instrukcji File Access](/manuals/file-access/#how-to-access-files-bundled-with-the-application). #### Bundle Resources -Zasoby paczki - lista oddzielonych przecinkami lokalizacji zasobów zawierających pliki i katalogi, które można skopiować w obecnym stanie do paczki wynikowej podczas budowania. Lokalizacje muszą być opisane ścieżkami bezwzględnymi od poziomu głównego katalogu Twojego projektu, np. `/res`. Taka lokalizacja z zasobami musi zawierać podfoldery nazwane zgodnie z platformą (`platform` lub `architecure-platform`). - - Wspierane platformy to: `ios`, `android`, `osx`, `win32`, `linux`, `web`. - - Dozwolony jest również podfolder `common` zawierający zasoby wspólne dla wszystkich platform. +`bundle_resources` +: Dodatkowe pliki i katalogi dołączane bezpośrednio do bundla aplikacji przez pole *Bundle Resources* w *game.project*. Więcej o ich użyciu znajdziesz w [instrukcji File Access](/manuals/file-access/#how-to-access-files-bundled-with-the-application). #### Bundle Exclude Resources -Zasoby, które należy usunąć z paczki - lista oddzielonych przecinkami zasobów, które nie będą dołączane do paczki. +`bundle_exclude_resources` +Lista zasobów rozdzielonych przecinkami, które nie powinny zostać dołączone do bundla. Są usuwane z wyniku kroku zbierania zasobów `bundle_resources`. + +--- -## Bootstrap (Ustawienia początkowe) +### Bootstrap #### Main Collection -Główna kolekcja - referencja do pliku kolekcji używanej w aplikacji jako startowa, domyślnie: `/logic/main.collection`. +Odwołanie do pliku kolekcji używanej przy uruchamianiu aplikacji. Domyślnie `/logic/main.collection`. #### Render -Referencja do pliku render określającego sposób renderowania, domyślnie: `/builtins/render/default.render`. +Plik konfiguracji renderowania definiujący pipeline renderowania. Domyślnie `/builtins/render/default.render`. -## Library (Biblioteki) +--- + +### Library #### Include Dirs -Dołączane lokalizacje - lista oddzielonych spacjami lokalizacji, które będą współdzielone z Twojego projektu poprzez udostępnianie bibliotek. +Lista katalogów rozdzielonych spacjami, które mają być współdzielone z projektu przez mechanizm bibliotek. Więcej informacji znajdziesz w [instrukcji Libraries](/manuals/libraries/). -## Script (Skrypy) +--- + +### Script #### Shared State -Stan współdzielony - Gdy opcja ta jest zaznaczona, projekt dzieli wspólny, pojedynczy stan Lua pomiędzy wszystkimi skryptami. Domyślnie odznaczone. +Zaznacz, aby współdzielić pojedynczy stan Lua między wszystkimi typami skryptów. + +--- -## Engine (silnik) +### Engine #### Run While Iconified -Kontynuuj po zminimalizowaniu okna - pozwól silnikowi na kontynuację pracy, gdy okno aplikacji jest zminimalizowane (dotyczy tylko komputerów), domyślnie odznaczone - `false`. +Pozwala silnikowi działać dalej, gdy okno aplikacji jest zminimalizowane lub zredukowane do ikony. Dotyczy tylko platform desktopowych. + +#### Fixed Update Frequency +Częstotliwość aktualizacji funkcji cyklu życia `fixed_update(self, dt)`, wyrażona w hercach. + +#### Max Time Step +Jeśli krok czasu w pojedynczej klatce stanie się zbyt duży, zostanie ograniczony do tej maksymalnej wartości. Jednostką są sekundy. + +--- -## Display (Wyświetlanie) +### Display #### Width -Szerokość okna aplikacji w pikselach, domyślnie: `960`. +Szerokość okna aplikacji w pikselach. #### Height -Wysokość okna aplikacji w pikselach, domyślnie: `640`. +Wysokość okna aplikacji w pikselach. #### High Dpi -Tworzy bufor High Dpi na wyświetlaczach, które to wspierają. Gra zostanie wyrenderowana w rozdzielczości dwukrotnie większej niż podana w ustawieniach *Width* i *Height*, ale podana rozdzielczość będzie nadal rozdzielczością dla logiki gry. +Tworzy bufor o wysokim DPI na wyświetlaczach, które to wspierają. Zwykle gra będzie renderowana w rozdzielczości dwukrotnie wyższej od ustawień *Width* i *Height*, ale wartości te nadal pozostaną logiczną rozdzielczością używaną w skryptach i właściwościach. #### Samples -Określa jak wiele próbek aplikacja ma używać przy anty-aliasingu. Ustawia wartość GLFW_FSAA_SAMPLES dla okna. Domyślnie: `0`, co oznacza, że anty-aliasing jest wyłączony. +Liczba próbek używanych do supersamplingu antyaliasingu. Ustawia wartość podpowiedzi okna `GLFW_FSAA_SAMPLES`. Wartość `0` wyłącza antyaliasing. #### Fullscreen -Zaznacz, żeby aplikacja startowała w trybie pełnego ekranu. Odznacz, żeby startowała w oknie. +Zaznacz, jeśli aplikacja ma startować w trybie pełnoekranowym. Gdy pole nie jest zaznaczone, aplikacja uruchomi się w oknie. + +#### Update Frequency +Docelowa liczba klatek na sekundę, wyrażona w hercach. Ustaw `0`, aby używać zmiennej liczby klatek. Wartość większa od `0` powoduje użycie stałej liczby klatek ograniczanej w czasie działania do rzeczywistej częstotliwości, co oznacza, że pętla gry nie może zostać wykonana dwa razy w ramach jednej klatki silnika. Wartość można zmieniać w czasie działania funkcją [`sys.set_update_frequency(hz)`](https://defold.com/ref/stable/sys/?q=set_update_frequency#sys.set_update_frequency:frequency). To ustawienie działa także w buildach headless. -#### Frame Cap -Jeśli opcja `Vsync` jest zaznaczona, przybliż do najbliższego pasującego przedziału wymiany dla ustawionego limiu ramki, jeśli monitor jest wykryty. W przeciwnym przypadku używaj timer'ów w celu zgodności z ustawioną wartością. 0 oznacza, że nie ma limitu. Ustawienie to dotyczy `display.update_frequency`. +#### Swap interval +Ta liczba całkowita steruje sposobem obsługi vsync. `0` wyłącza vsync, a wartością domyślną jest `1`. Przy adapterze OpenGL wartość określa liczbę klatek pomiędzy [zamianami buforów](https://www.khronos.org/opengl/wiki/Swap_Interval). W przypadku Vulkana nie istnieje wbudowane pojęcie swap interval, więc wartość określa po prostu, czy vsync ma być włączony. #### Vsync -Vertical sync, czyli pionowa synchronizacja - polegaj na sprzętowej synchronizacji do określania czasu ramki. Może być nadpisane w zależności od sterownika karty graficznej i specyfiki platformy. +Polegaj na sprzętowym vsync przy wyznaczaniu czasu klatki. To ustawienie może zostać nadpisane przez sterownik graficzny lub specyfikę platformy. Aby uzyskać przestarzałe zachowanie `variable_dt`, odznacz tę opcję i ustaw limit liczby klatek na `0`. #### Display Profiles -Profile wyświetlania - określa, których profili używać, domyślnie: `/builtins/render/default.display_profilesc`. Więce szczegółów znajdziesz w [instrukcji do layout'ów GUI](/manuals/gui-layouts/#creating-display-profiles). +Określa plik profili wyświetlania, którego należy użyć. Domyślnie `/builtins/render/default.display_profilesc`. Więcej informacji znajdziesz w [instrukcji GUI Layouts](/manuals/gui-layouts/#creating-display-profiles). #### Dynamic Orientation -Dynamiczna orientacja - zaznacz, żeby pozwolić aplikacji dynamicznie zmieniać między ustawieniem horyzontalnym i portretowym w zależności od orientacji urządzenia. Aplikacja deweloperska dmegine obecnie nie respektuje tego ustawienia. +Zaznacz, jeśli aplikacja ma dynamicznie przełączać się między orientacją pionową i poziomą po obróceniu urządzenia. Aplikacja deweloperska obecnie nie respektuje tego ustawienia. -## Render (Renderowanie) +#### Display Device Info +Wypisuje informacje o GPU do konsoli podczas uruchamiania. + +--- + +### Render #### Clear Color Red -Czerwona składowa koloru czyszczenia ekranu, używana przez skrypt renderowania, kiedy okno jest tworzone. Dodano w 1.2.167. +Składowa czerwona koloru czyszczenia, używana przez skrypt renderujący i przy tworzeniu okna. #### Clear Color Green -Zielona składowa koloru czyszczenia ekranu, używana przez skrypt renderowania, kiedy okno jest tworzone. Dodano w 1.2.167. +Składowa zielona koloru czyszczenia, używana przez skrypt renderujący i przy tworzeniu okna. #### Clear Color Blue -Niebieska składowa koloru czyszczenia ekranu, używana przez skrypt renderowania, kiedy okno jest tworzone. Dodano w 1.2.167. +Składowa niebieska koloru czyszczenia, używana przez skrypt renderujący i przy tworzeniu okna. #### Clear Color Alpha -Składowa koloru czyszczenia ekranu odpowiedzialna za transparentność, używana przez skrypt renderowania, kiedy okno jest tworzone. Dodano w 1.2.167. +Składowa alfa koloru czyszczenia, używana przez skrypt renderujący i przy tworzeniu okna. + +--- -## Physics (Fizyka) +### Font + +#### Runtime Generation +Włącz generowanie fontów w czasie działania. + +--- + +### Physics + +#### Max Collision Object Count +Maksymalna liczba obiektów kolizji. #### Type -Jaki typ fizyki jest używany: `2D` (domyślnie) albo `3D`. +Typ fizyki, którego należy użyć: `2D` albo `3D`. + +#### Gravity X +Grawitacja świata wzdłuż osi X, w metrach na sekundę. #### Gravity Y -Składowa Y wektora siły grawitacji, domyślnie `-10` (ziemska grawitacja). +Grawitacja świata wzdłuż osi Y, w metrach na sekundę. + +#### Gravity Z +Grawitacja świata wzdłuż osi Z, w metrach na sekundę. #### Debug -Zaznacz, żeby wizualizować fizykę do celów debugowania. +Zaznacz, aby wizualizować fizykę do celów debugowania. #### Debug Alpha -Składowa koloru wizualizacji fizyki odpowiedzialna za transparentność z przedziału `0`--`1`. Domyślnie: `0.9`. +Wartość składowej alfa dla wizualizacji fizyki, z zakresu `0`--`1`. #### World Count -Maksymalna liczba oddzielnych światów z fizyką, domyślnie: `4`. Jeśli wczytujesz więcej niż 4 światy poprzez pełnomocników kolekcji (collection proxies) musisz zwiększyć tę wartość. Pamiętaj, że każdy osobny świat fizyki zajmuje odpowiednią ilość pamięci. - -#### Gravity X -Składowa X wektora siły grawitacji, domyślnie `0`. - -#### Gravity Z -Składowa Z wektora siły grawitacji, domyślnie `0`. +Maksymalna liczba jednoczesnych światów fizyki. Domyślnie `4`. Jeśli przez pełnomocników kolekcji wczytujesz więcej niż 4 światy jednocześnie, musisz zwiększyć tę wartość. Pamiętaj, że każdy świat fizyki zużywa sporą ilość pamięci. #### Scale -Skala fizyki - pomaga silnikowi określić w jaki sposób skalować wartości świata fizyki, aby zachować precyzję numeryczną, z przedziału `0.01`--`1.0`. Jeśli ustawisz wartość `0.02`, oznacza to, że świat fizyki będzie postrzegał 50 jednostek jako jeden metr.($1 / 0.02$). Domyślnie: `1.0`. +Informuje silnik fizyki, jak skalować świat fizyczny względem świata gry dla zachowania precyzji numerycznej, w zakresie `0.01`--`1.0`. Jeśli wartość wynosi `0.02`, oznacza to, że silnik fizyki traktuje 50 jednostek jako 1 metr ($1 / 0.02$). #### Allow Dynamic Transforms -Zaznacz, aby silnik fizyki skalował obiekty kolizji używając skali obiektów gry, do których należą. +Zaznacz, jeśli silnik fizyki ma stosować transformację obiektu gry do dołączonych komponentów obiektu kolizji. Umożliwia to przesuwanie, skalowanie i obracanie kształtów kolizji, także tych dynamicznych. + +#### Use Fixed Timestep +Zaznacz, jeśli silnik fizyki ma używać stałych, niezależnych od liczby klatek aktualizacji. Tego ustawienia należy używać razem z funkcją cyklu życia `fixed_update(self, dt)` oraz ustawieniem projektu `engine.fixed_update_frequency`, aby wchodzić w interakcję z fizyką w regularnych odstępach. Dla nowych projektów zalecaną wartością jest `true`. #### Debug Scale -Określa jak duże rysować obiekty służące do debugowania fizyki - np. wektory normalne, domyślnie `30`. +Określa rozmiar obiektów jednostkowych rysowanych w debugowaniu fizyki, takich jak osie lokalne i normalne. #### Max Collisions -Określa jak wiele kolizji będzie obsługiwanych przez skrypty, domyślnie `64`. +Określa, ile kolizji zostanie przekazanych do skryptów. #### Max Contacts -Określa jak wiele punktów styku będzie obsługiwanych przez skrypty, domyślnie `128`. +Określa, ile punktów kontaktu zostanie przekazanych do skryptów. #### Contact Impulse Limit -Silnik zignoruje zderzenia z impulsem mniejszym niż ta wartość, domyślnie `0.0`. +Ignoruje impulsy kontaktu o wartościach mniejszych niż to ustawienie. #### Ray Cast Limit 2d -Maksymalna liczba promieni 2D rzucanych w czasie jednej ramki, domyślnie `64`. +Maksymalna liczba zapytań ray cast 2D na klatkę. #### Ray Cast Limit 3d -Maksymalna liczba promieni 3D rzucanych w czasie jednej ramki, domyślnie `128`. +Maksymalna liczba zapytań ray cast 3D na klatkę. #### Trigger Overlap Capacity -Maksymalna liczba pokrywających się przełączników (triggers), domyślnie `16`. +Maksymalna liczba nakładających się triggerów fizyki. + +#### Velocity Threshold +Minimalna prędkość powodująca zderzenia sprężyste. + +#### Max Fixed Timesteps +Maksymalna liczba kroków symulacji przy użyciu stałego kroku czasu. Dotyczy tylko 3D. -## Graphics (Grafika) +--- + +### Graphics #### Default Texture Min Filter -Określa jakiego filtra używać podczas pomniejszającego filtrowania tekstur, `linear` (domyślnie) lub `nearest`. +Określa filtr używany przy minifikacji tekstur. #### Default Texture Mag Filter -Określa jakiego filtra używać podczas powiększającego filtrowania tekstur, `linear` (domyślnie) lub `nearest`. +Określa filtr używany przy magnifikacji tekstur. #### Max Draw Calls -Maksymalna liczba wywołań rysowania grafiki (renderowania, ang. render calls), domyślnie `1024`. +Maksymalna liczba wywołań renderowania. #### Max Characters: -Maksymalna liczba znaków zaalokowanych wcześniej w buforze renderowania tekstu, czyli liczba znaków, które można wyświetlić w każdej ramce, domyślnie `8192`. +Liczba znaków prealokowanych w buforze renderowania tekstu, czyli liczba znaków możliwych do wyświetlenia w każdej klatce. + +#### Max Font Batches +Maksymalna liczba partii tekstu, które można wyświetlić w każdej klatce. #### Max Debug Vertices -Maksymalna liczba punktów służących do debugowania, między innymi do rysowania kształtów silnika fizyki, domyślnie `10000`. +Maksymalna liczba wierzchołków debugowania. Używana między innymi do renderowania kształtów fizyki. #### Texture Profiles -Określa jakiego profilu teksturowania należy używać do tego projektu, domyślnie `/builtins/graphics/default.texture_profiles`. +Plik profili teksturowania używany przez projekt. Domyślnie `/builtins/graphics/default.texture_profiles`. -## Input (Wejścia) +#### Verify Graphics Calls +Sprawdza wartość zwrotną po każdym wywołaniu grafiki i raportuje błędy w logu. + +#### OpenGL Version Hint +Podpowiedź dotycząca wersji kontekstu OpenGL. Jeśli wybierzesz konkretną wersję, będzie ona używana jako minimalnie wymagana wersja. Nie dotyczy OpenGL ES. + +#### OpenGL Core Profile Hint +Ustawia podpowiedź profilu `core` podczas tworzenia kontekstu. Profil core usuwa wszystkie przestarzałe funkcje OpenGL, takie jak renderowanie w trybie immediate. Nie dotyczy OpenGL ES. + +--- + +### Shader + +#### Exclude GLES 2.0 +Nie kompiluj shaderów dla urządzeń używających OpenGLES 2.0 / WebGL 1.0. + +--- + +### Input #### Repeat Delay -Czas w sekundach, który należy odczekać po odczytaniu danego wejścia, zanim to samo wejście może zostać powtórzone, domyślnie `0.5`. +Liczba sekund oczekiwania, zanim przytrzymane wejście zacznie się powtarzać. #### Repeat Interval -Czas w sekundach, który należy odczekać po odczytaniu danego wejścia, które jest ciągle wciskane, zanim to samo wejście może zostać odczytane jako powtórzone, domyślnie `0.2`. +Liczba sekund pomiędzy kolejnymi powtórzeniami przytrzymanego wejścia. #### Gamepads -Określa jakiego pliku należy używać do konfiguracji kontrolerów, który mapuje wejścia kontrolera do systemu operacyjnego, domyślnie `/builtins/input/default.gamepads`. +Odwołanie do pliku konfiguracji gamepadów mapującego sygnały gamepada na system operacyjny. Domyślnie `/builtins/input/default.gamepads`. #### Game Binding -Określa jakiego pliku należy używać do konfiguracji wejść, który mapuje wejścia sprzętowe do podanych akcji, domyślnie `/input/game.input_binding`. +Odwołanie do pliku konfiguracji wejść mapującego sprzętowe wejścia na akcje. Domyślnie `/input/game.input_binding`. #### Use Accelerometer -Zaznacz, żeby silnik mógł otrzymywać dane z akceleratora jako wejście dla każdej ramki. Wyłączenie akcelerometra może dawać korzyści pod względem wydajności. Domyślnie zaznaczone. +Zaznacz, aby silnik otrzymywał zdarzenia z akcelerometru w każdej klatce. Wyłączenie akcelerometru może przynieść pewne korzyści wydajnościowe. + +--- -## Resource (Źródła) +### Resource #### Http Cache -Kiedy zaznaczone, pamięć podręczna (cache) HTTP jest aktywowana, aby szybciej ładować zasoby przez sieć do działającego na urządzeniu silnika. Domyślnie odznaczone. +Po zaznaczeniu włącza pamięć podręczną HTTP, aby szybciej ładować przez sieć zasoby do silnika uruchomionego na urządzeniu. #### Uri -Wskazuje gdzie szukać danych do budowania projektu, w formacie URI. +Określa lokalizację danych builda projektu w formacie URI. #### Max Resources -Maksymalna liczba zasobów, które mogą być załadowane jednocześnie, domyślnie `1024`. +Maksymalna liczba zasobów, które mogą być załadowane jednocześnie. + +--- -## Network (Sieć) +### Network #### Http Timeout -Czas w sekundach do zaniechania czekania na odpowiedź HTTP. Ustaw na `0`, żeby wyłączyć timeout, domyślnie właśnie wyłączony, czyli czeka na odpowiedź nieskończenie długo. +Limit czasu HTTP w sekundach. Ustaw `0`, aby wyłączyć limit czasu. -## Collection (Kolekcje) +#### Http Thread Count +Liczba wątków roboczych używanych przez usługę HTTP. + +#### Http Cache Enabled +Zaznacz, aby włączyć pamięć podręczną HTTP dla żądań sieciowych wykonywanych przez `http.request()`. Cache HTTP przechowuje odpowiedź skojarzoną z żądaniem i ponownie używa jej przy kolejnych żądaniach. Obsługiwane są nagłówki odpowiedzi `ETag` i `Cache-Control: max-age`. + +#### SSL Certificates +Plik zawierający główne certyfikaty SSL używane przy weryfikacji łańcucha certyfikatów podczas handshake SSL. + +--- + +### Collection #### Max Instances -Maksymalna liczba instancji obiektów gry w jednej kolekcji, domyślnie `1024`. +Maksymalna liczba instancji obiektów gry w kolekcji. Domyślnie `1024`. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). + +#### Max Input Stack Entries +Maksymalna liczba obiektów gry na stosie wejścia. -## Sound (Dźwięk) +--- + +### Sound #### Gain -Globalne wzmocnienie dźwięku (volume), `0`--`1`, domyślnie `1`. +Globalne wzmocnienie dźwięku (głośność), `0`--`1`. + +#### Use Linear Gain +Po włączeniu wzmocnienie jest liniowe. Po wyłączeniu używana jest krzywa wykładnicza. #### Max Sound Data -Maksymalna liczba źródeł dźwięku, czyli liczba unikalnych plików dźwiękowych, które można otworzyć jednocześnie, domyślnie `128`. +Maksymalna liczba zasobów dźwiękowych, czyli unikalnych plików dźwiękowych dostępnych w czasie działania. #### Max Sound Buffers -(Obecnie nie używane) Maksymalna liczba jednocześnie istniejących buforów dźwiękowych, domyślnie `32`. +(Obecnie nieużywane) Maksymalna liczba jednoczesnych buforów dźwięku. #### Max Sound Sources -(Obecnie nie używane) Maksymalna liczba jednocześnie istniejących źródeł dźwięku, domyślnie `16`. +(Obecnie nieużywane) Maksymalna liczba jednocześnie odtwarzanych dźwięków. #### Max Sound Instances -Maksymalna liczba jednocześnie istniejących instancji dźwięku, czyli liczba aktualnych dźwięków odtwarzanych w tym samym momencie, domyślnie `256`. +Maksymalna liczba jednoczesnych instancji dźwięku, czyli rzeczywistych dźwięków odtwarzanych w tym samym momencie. + +#### Max Component Count +Maksymalna liczba komponentów dźwięku w jednej kolekcji. + +#### Sample Frame Count +Liczba próbek używanych przy każdej aktualizacji audio. `0` oznacza tryb automatyczny (`1024` dla 48 kHz, `768` dla 44.1 kHz). + +#### Use Thread +Po zaznaczeniu system dźwięku używa wątków do odtwarzania audio, aby zmniejszyć ryzyko zacięć, gdy główny wątek jest mocno obciążony. + +#### Stream Enabled +Po zaznaczeniu system dźwięku używa streamingu do ładowania plików źródłowych. -## Sprite (Obrazy) +#### Stream Cache Size +Maksymalny rozmiar cache fragmentów dźwięku zawierającego *wszystkie* fragmenty. Domyślnie `2097152` bajty. Ta wartość powinna być większa niż liczba załadowanych plików dźwiękowych pomnożona przez rozmiar fragmentu streamingu, w przeciwnym razie nowe fragmenty mogą być usuwane z cache w każdej klatce. + +#### Stream Chunk Size +Rozmiar w bajtach każdego fragmentu ładowanego strumieniowo. + +#### Stream Preload Size +Określa rozmiar w bajtach początkowego fragmentu plików dźwiękowych wczytywanych z archiwum. + +--- + +### Sprite #### Max Count -Maksymalna liczba sprite'ów w jednej kolekcji, domyślnie `128`. +Maksymalna liczba sprite'ów w jednej kolekcji. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). #### Subpixels -Zaznacz, aby pozwolić sprite'om pojawiać się nieprzylegając do pełnych pikseli, domyślnie zaznaczone. +Zaznacz, aby pozwolić sprite'om pojawiać się poza siatką pełnych pikseli. + +--- -## Tilemap (Mapy kafelków) +### Tilemap #### Max Count -Maksymalna liczba map kafelków w jednej kolekcji, domyślnie `16`. +Maksymalna liczba map kafelków w jednej kolekcji. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). #### Max Tile Count -Maksymalna liczba jednocześnie widocznych kafelków w jednej kolekcji, domyślnie `2048`. +Maksymalna liczba jednocześnie widocznych kafelków w jednej kolekcji. + +--- -## Spine +### Spine #### Max Count -Maksymalna liczba modeli szkieletowych Spine, domyślnie `128`. +Maksymalna liczba komponentów modelu Spine. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). -## GUI +--- + +### Mesh #### Max Count -Maksymalna liczba komponentów GUI, domyślnie `64`. +Maksymalna liczba komponentów Mesh w jednej kolekcji. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). -#### Max Particlefx Count -Maksymalna liczba jednocześnie istniejących emiterów cząsteczek w GUI, domyślnie `64`. +--- + +### Model + +#### Max Count +Maksymalna liczba komponentów Model w jednej kolekcji. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). + +#### Split Meshes +Podziel siatki mające więcej niż 65536 wierzchołków na nowe siatki. + +#### Max Bone Matrix Texture Width +Maksymalna szerokość tekstury macierzy kości. Używany jest tylko rozmiar potrzebny animacjom, zaokrąglany w górę do najbliższej potęgi dwójki. + +#### Max Bone Matrix Texture Height +Maksymalna wysokość tekstury macierzy kości. Używany jest tylko rozmiar potrzebny animacjom, zaokrąglany w górę do najbliższej potęgi dwójki. + +--- + +### GUI + +#### Max Count +Maksymalna liczba komponentów GUI. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). #### Max Particle Count -Maksymalna liczba jednocześnie istniejących cząsteczek w GUI, domyślnie `1024`. +Maksymalna liczba jednoczesnych cząsteczek w GUI. + +#### Max Animation Count +Maksymalna liczba aktywnych animacji w GUI. + +--- -## Label (Etykieta) +### Label #### Max Count -Maksymalna liczba etykiet z tekstem, domyślnie `64`. +Maksymalna liczba etykiet. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). #### Subpixels -Zaznacz, aby pozwolić etykietom pojawiać się nieprzylegając do pełnych pikseli, domyślnie zaznaczone. +Zaznacz, aby pozwolić etykietom pojawiać się poza siatką pełnych pikseli. + +--- -## Particle FX (Efekty cząsteczkowe) +### Particle FX #### Max Count -Maksymalna liczba jednocześnie istniejących emiterów cząsteczek, domyślnie `64`. +Maksymalna liczba jednoczesnych emiterów. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). #### Max Particle Count -Maksymalna liczba jednocześnie istniejących cząsteczek, domyślnie `1024`. +Maksymalna liczba jednoczesnych cząsteczek. + +--- + +### Box2D + +#### Velocity Iterations +Liczba iteracji prędkości dla solvera fizyki Box2D 2.2. -## Collection proxy (Pełnomocnicy kolekcji) +#### Position Iterations +Liczba iteracji pozycji dla solvera fizyki Box2D 2.2. + +#### Sub Step Count +Liczba podkroków dla solvera fizyki Box2D 3.x. + +--- + +### Collection proxy #### Max Count -Maksymalna liczba pełnomocników kolekcji, domyślnie `8`. +Maksymalna liczba pełnomocników kolekcji. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). + +--- -## Collection factory (Fabryki kolekcji) +### Collection factory #### Max Count -Maksymalna liczba fabryk kolekcji, domyślnie `128`. +Maksymalna liczba fabryk kolekcji. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). -## Factory (Fabryki) +--- + +### Factory #### Max Count -Maksymalna liczba fabryk, domyślnie `128`. +Maksymalna liczba fabryk obiektów gry. Zobacz też informacje o [optymalizacji liczników maksymalnych komponentów](#component-max-count-optimizations). + +--- -## iOS +### iOS #### App Icon 57x57--180x180 -Plik graficzny (.png) używany jako ikona aplikacji o podanych wymiarach `W` × `H`. +Plik obrazu `.png` używany jako ikona aplikacji dla podanych wymiarów `W` × `H`. #### Launch Screen -Plik Storyboard (.storyboard). Więcej szczegółów znajdziesz w [instrukcji do systemu iOS](/manuals/ios/#creating-a-storyboard). +Plik storyboard `.storyboard`. Więcej informacji o jego tworzeniu znajdziesz w [instrukcji iOS](/manuals/ios/#creating-a-storyboard). -#### Pre Rendered Icons -(Dotyczy iOS 6 i wcześniejszych wersji) Zaznacz, żeby ikony były pre-renderowane. Jeśli ta opcja nie jest zaznaczona ikony będą miały automatycznie dodany świetlistą poświatę. +#### Icons Asset +Plik zasobu ikon `.car` zawierający ikony aplikacji. + +#### Prerendered Icons +(iOS 6 i starsze) Zaznacz, jeśli ikony są prerenderowane. Gdy to pole nie jest zaznaczone, system automatycznie doda błyszczące podświetlenie. #### Bundle Identifier -Identyfikator paczki - pozwala systemowi iOS rozpoznawać Twoją aplikację przy aktualizacjach. ID Twojej paczki musi być zarejestrowane przez Apple i być dla niej unikalne. Nie można używać tego samego identyfikatora dla aplikacji iOS i macOS. +Identyfikator bundla pozwalający iOS rozpoznawać aktualizacje aplikacji. Musi być zarejestrowany w Apple i unikalny dla aplikacji. Nie można używać tego samego identyfikatora dla aplikacji iOS i macOS. Musi składać się z co najmniej dwóch segmentów oddzielonych kropką. Każdy segment musi zaczynać się literą i może zawierać tylko litery alfanumeryczne, znak podkreślenia lub myślnik (`-`). Zobacz [`CFBundleIdentifier`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430). + +#### Bundle Name +Krótka nazwa bundla, maksymalnie 15 znaków. Zobacz [`CFBundleName`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430). + +#### Bundle Version +Wersja bundla zapisana jako liczba albo `x.y.z`. Zobacz [`CFBundleVersion`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430). #### Info.plist -Jeśli podany - używany będzie określony plik info.plist podczas budowania paczki aplikacji. +Jeśli ustawiono, podczas bundlowania aplikacji zostanie użyty wskazany plik *`info.plist`*. -#### Entitlements -Uprawnienia - jeśli podane, mogą nadpisać domyślne uprawnienia określone w profilach nadzorujących (`.entitlements`, `.xcent`, `.plist`). +#### Privacy Manifest +Apple Privacy Manifest dla aplikacji. Domyślną wartością pola jest `/builtins/manifests/ios/PrivacyInfo.xcprivacy`. + +#### Custom Entitlements +Jeśli ustawiono, uprawnienia z dostarczonego profilu provisioning (`.entitlements`, `.xcent`, `.plist`) zostaną połączone z uprawnieniami z profilu provisioning podanego podczas bundlowania aplikacji. #### Default Language -Domyślny jeżyk aplikacji - używany, jeśli użytkownik nie posiada wybranego preferowanego języka domyślnego w liście `Localizations` (zobacz: [CFBundleDevelopmentRegion](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430)). Należy tutaj użyć dwuznakowego symbolu kraju zgodnego ze standardem ISO 639-1, jeśli preferowany język znajduje się w standardzie, w przeciwnym przypadku - trójznakowego symbolu ze standardu ISO 639-2. +Język używany, jeśli aplikacja nie zawiera preferowanego języka użytkownika na liście `Localizations`. Zobacz [`CFBundleDevelopmentRegion`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430). Użyj dwuliterowego standardu ISO 639-1, jeśli język jest tam dostępny, w przeciwnym razie trzy-literowego ISO 639-2. #### Localizations -Ustawienia regionalne - pole zawiera oddzielone przecinkami słowa (strings) identyfikujące nazwę języka lub oznaczenie języka ISO wspieranych lokalizacji (zobacz: [CFBundleLocalizations](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-109552)). +Pole zawierające oddzielone przecinkami ciągi identyfikujące nazwę języka lub oznaczenie ISO dla obsługiwanych lokalizacji. Zobacz [`CFBundleLocalizations`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-109552). + +--- -## Android +### Android #### App Icon 36x36--192x192 -Plik graficzny (.png) używany jako ikona aplikacji o podanych wymiarach `W` × `H`. +Plik obrazu `.png` używany jako ikona aplikacji dla podanych wymiarów `W` × `H`. #### Push Icon Small--LargeXxxhdpi -Plik graficzny (.png) używany jako ikona aplikacji w powiadomieniach *push* systemu Android. Ikony będą używane automatycznie zarówno do lokalnych i zdalnych powiadomień. Jeśli nie podano ikony, domyślna ikona aplikacji będzie używana. +Pliki obrazów `.png` używane jako własne ikony powiadomień push na Androidzie. Ikony będą automatycznie używane zarówno dla powiadomień lokalnych, jak i zdalnych. Jeśli nie są ustawione, domyślnie używana będzie ikona aplikacji. #### Push Field Title -Określa jakie pole z pliku JSON (payload) ma być użyte jako tytuł powiadomienia. Pozostawienie tego pola pustego sprawia, że domyślnie używana jest nazwa aplikacji. +Określa, które pole JSON z payloadu ma zostać użyte jako tytuł powiadomienia. Jeśli pole jest puste, jako tytuł używana jest nazwa aplikacji. #### Push Field Text -Określa jakie pole z pliku JSON (payload) ma być użyte jako treść powiadomienia. Pozostawienie tego pola pustego sprawia, że domyślnie używany jest tekst `alert`, tak jak dla iOS. +Określa, które pole JSON z payloadu ma zostać użyte jako treść powiadomienia. Jeśli pole jest puste, używana jest wartość z pola `alert`, tak jak na iOS. #### Version Code -Kod wersji - wartość numeryczna całkowita (integer) określająca wersję aplikacji. Zwiększaj tę wartość przy każdej aktualizacji. +Całkowita wartość liczbowa oznaczająca wersję aplikacji. Należy ją zwiększać przy każdej kolejnej aktualizacji. + +#### Minimum SDK Version +Minimalny poziom API wymagany do uruchomienia aplikacji (`android:minSdkVersion`). + +#### Target SDK Version +Poziom API, na który aplikacja jest targetowana (`android:targetSdkVersion`). #### Package -Identyfikator paczki. +Identyfikator pakietu. Musi składać się z co najmniej dwóch segmentów oddzielonych kropką. Każdy segment musi zaczynać się literą i może zawierać tylko litery alfanumeryczne oraz znak podkreślenia. + +#### GCM Sender Id +Google Cloud Messaging Sender Id. Ustaw tutaj ciąg znaków przypisany przez Google, aby włączyć powiadomienia push. -#### Gcm Sender Id -Google Cloud Messaging Sender Id. Podaj tutaj string przypisany przez Google, aby aktywować powiadomienia *push*. +#### FCM Application Id +Identyfikator aplikacji Firebase Cloud Messaging. #### Manifest -Plik XML - jeśli podany, będzie używany podczas budowania paczki. +Jeśli ustawiono, podczas bundlowania zostanie użyty wskazany plik Android Manifest XML. #### Iap Provider -Określa jakiego sklepu używać do zakupów wewnątrz aplikacji (ang. In App Purchases). Możliwe opcje to `Amazon` i `GooglePlay` (domyślnie). +Określa, którego sklepu używać. Poprawne wartości to `Amazon` i `GooglePlay`. Więcej informacji znajdziesz w [extension-iap](/extension-iap/). #### Input Method -Określa jakich sposobów obsługi klawiatury na urządzeniach z Androidem używać. Możliwe opcje to `KeyEvent` (stara metoda, domyślna) i `HiddenInputField` (nowa). +Określa metodę pobierania wejścia z klawiatury na urządzeniach z Androidem. Poprawne wartości to `KeyEvent` (stara metoda) oraz `HiddenInputField` (nowa). #### Immersive Mode -Tryb imersyjny. Jeśli ustawiony, ukrywa przyciski nawigacji i górny pasek statusu systemu Android oraz pozwala aplikacji na wykrywanie i przechwytywanie dotyku na powierzchni całego ekranu. +Po włączeniu ukrywa pasek nawigacji i pasek statusu oraz pozwala aplikacji przechwytywać wszystkie zdarzenia dotyku na ekranie. + +#### Display Cutout +Pozwala rozszerzyć obraz na obszar wycięcia ekranu. #### Debuggable -Określa czy aplikacja może być debugowana używając takich narzędzi jak [GAPID](https://github.com/google/gapid) lub [Android Studio](https://developer.android.com/studio/profile/android-profiler). Ustawia flagę `android:debuggable` w manifeście systemu Android. +Określa, czy aplikację można debugować narzędziami takimi jak [GAPID](https://github.com/google/gapid) albo [Android Studio](https://developer.android.com/studio/profile/android-profiler). Ustawia flagę `android:debuggable` w Android Manifest. Zobacz [oficjalną dokumentację](https://developer.android.com/guide/topics/manifest/application-element#debug). + +#### ProGuard config +Własny plik ProGuard pomagający usunąć zbędne klasy Java z końcowego APK. + +#### Extract Native Libraries +Określa, czy instalator pakietu ma rozpakowywać biblioteki natywne z APK do systemu plików. Jeśli ustawisz `false`, biblioteki będą przechowywane nieskompresowane wewnątrz APK. APK może być wtedy większy, ale aplikacja będzie ładować się szybciej, bo biblioteki będą ładowane bezpośrednio z APK w czasie działania. To ustawienie ustawia flagę `android:extractNativeLibs` w Android Manifest. Zobacz [oficjalną dokumentację](https://developer.android.com/guide/topics/manifest/application-element#extractNativeLibs). -## macOS +--- + +### macOS #### App Icon -Plik graficzny (.png) używany jako ikona aplikacji w systemie macOS. +Plik ikony bundla `.icns` używany jako ikona aplikacji w macOS. #### Info.plist -Jeśli podany - używany będzie określony plik info.plist podczas budowania paczki aplikacji. +Jeśli ustawiono, podczas bundlowania zostanie użyty wskazany plik `info.plist`. + +#### Privacy Manifest +Apple Privacy Manifest dla aplikacji. Domyślną wartością pola jest `/builtins/manifests/osx/PrivacyInfo.xcprivacy`. #### Bundle Identifier -Identyfikator paczki - pozwala systemowi iOS rozpoznawać Twoją aplikację przy aktualizacjach. ID Twojej paczki musi być zarejestrowane przez Apple i być dla niej unikalne. Nie można używać tego samego identyfikatora dla aplikacji iOS i macOS. +Identyfikator bundla pozwalający macOS rozpoznawać aktualizacje aplikacji. Musi być zarejestrowany w Apple i unikalny dla aplikacji. Nie można używać tego samego identyfikatora dla aplikacji iOS i macOS. Musi składać się z co najmniej dwóch segmentów oddzielonych kropką. Każdy segment musi zaczynać się literą i może zawierać tylko litery alfanumeryczne, znak podkreślenia lub myślnik (`-`). #### Default Language -Domyślny jeżyk aplikacji - używany, jeśli użytkownik nie posiada wybranego preferowanego języka domyślnego w liście `Localizations` (zobacz: [CFBundleDevelopmentRegion](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430)). Należy tutaj użyć dwuznakowego symbolu kraju zgodnego ze standardem ISO 639-1, jeśli preferowany język znajduje się w standardzie, w przeciwnym przypadku - trójznakowego symbolu ze standardu ISO 639-2. +Język używany, jeśli aplikacja nie zawiera preferowanego języka użytkownika na liście `Localizations`. Zobacz [`CFBundleDevelopmentRegion`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430). Użyj dwuliterowego standardu ISO 639-1, jeśli język jest tam dostępny, w przeciwnym razie trzy-literowego ISO 639-2. #### Localizations -Ustawienia regionalne - pole zawiera oddzielone przecinkami słowa (strings) identyfikujące nazwę języka lub oznaczenie języka ISO wspieranych lokalizacji (zobacz: [CFBundleLocalizations](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-109552)). +Pole zawierające oddzielone przecinkami ciągi identyfikujące nazwę języka lub oznaczenie ISO dla obsługiwanych lokalizacji. Zobacz [`CFBundleLocalizations`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-109552). -## Windows +--- + +### Windows #### App Icon -Plik graficzny (.ico) używany jako ikona aplikacji w systemie Windows. Więcej szczegółów na temat tworzenia plików .ico znajdziesz w [instrukcji do systemu Windows](/manuals/windows). +Plik obrazu `.ico` używany jako ikona aplikacji w Windows. Więcej informacji o tworzeniu plików `.ico` znajdziesz w [instrukcji Windows](/manuals/windows). -#### Iap Provider -Określa jakiego sklepu używać do zakupów wewnątrz aplikacji (ang. In App Purchases). Możliwe opcje to `None`(domyślnie) i `Gameroom`. +--- + +### HTML5 -## HTML5 +Więcej informacji o wielu z tych opcji znajdziesz w [instrukcji platformy HTML5](/manuals/html5/). #### Heap Size -Rozmiar sterty (liczba megabajtów) dla użycia przez Emscripten. Domyślnie 256MB. +Rozmiar sterty w megabajtach używanej przez Emscripten. #### .html Shell -Używaj określonego szablonu HTML podczas budowania paczki aplikacji, domyślnie: `/builtins/manifests/web/engine_template.html`. +Podczas bundlowania używaj wskazanego szablonu HTML. Domyślnie `/builtins/manifests/web/engine_template.html`. #### Custom .css -Używaj określonego pliku z motywem CSS podczas budowania paczki aplikacji, domyślnie: `/builtins/manifests/web/light_theme.css`. +Podczas bundlowania używaj wskazanego pliku motywu CSS. Domyślnie `/builtins/manifests/web/light_theme.css`. #### Splash Image -Jeśli określony, użyj podanej grafiki jako ekranu startowego podczas budowania paczki aplikacji zamiast domyślnego logo Defold. +Jeśli ustawiono, podczas bundlowania użyj wskazanego obrazu startowego zamiast logo Defold. #### Archive Location Prefix -Podczas budowania paczki aplikacji dane gry HTML5 są rozdzielane na jeden lub więcej plików archiwów. Kiedy silnik uruchamia aplikację, archiwa te są ładowane do pamięci. Użyj tego pola, aby określić lokalizację danych, domyślnie: `archive`. +Podczas bundlowania dla HTML5 dane gry są dzielone na jeden lub więcej plików archiwum. Gdy silnik uruchamia grę, pliki te są wczytywane do pamięci. To ustawienie określa lokalizację tych danych. #### Archive Location Suffix -Przyrostek dodawany do plików archiwów. Użyteczny na przykład przy wymuszaniu nie-buforowanych (non-cache) zawartości z CDN (na przykład: `?version2`). +Sufiks dodawany do plików archiwum. Przydaje się na przykład do wymuszania pobierania niebuforowanej zawartości z CDN, jak `?version2`. #### Engine Arguments -Lista argumentów, które zostaną przekazane do silnika. +Lista argumentów przekazywanych do silnika. + +#### Wasm Streaming +Włącza streaming pliku wasm. Jest szybszy i zużywa mniej pamięci, ale wymaga typu MIME `application/wasm`. #### Show Fullscreen Button -Dodaje przycisk trybu pełnoekranowego do pliku `index.html`. Domyślnie `true`. +Włącza przycisk Fullscreen w pliku `index.html`. #### Show Made With Defold -Dodaje link Made With Defold link do pliku `index.html`. Domyślnie `true`. +Włącza link Made With Defold w pliku `index.html`. + +#### Show Console Banner +Po włączeniu ta opcja wypisuje informacje o silniku i jego wersji w konsoli przeglądarki za pomocą `console.log()` podczas startu silnika. #### Scale Mode -Określa jakiego sposobu skalowania kanwy (obszaru wyświetlania) gry używać. Domyślnie `Downscale Fit`. +Określa metodę skalowania kanwy gry. + +#### Retry Count +Liczba prób pobrania pliku przy uruchamianiu silnika. Zobacz także `Retry Time`. -## IAP (Zakupy wewnątrz aplikacji) +#### Retry Time +Liczba sekund oczekiwania między kolejnymi próbami pobrania pliku po nieudanym pobraniu. Zobacz także `Retry Count`. + +#### Transparent Graphics Context +Zaznacz, jeśli kontekst grafiki ma mieć przezroczyste tło. + +--- + +### IAP #### Auto Finish Transactions -Zaznacz, żeby automatycznie kończyć proces transakcji zakupów IAP. Jeśli odznaczony, musisz jawnie wywołać `iap.finish()` po udanej transakcji, domyślnie zaznaczony. +Zaznacz, aby automatycznie finalizować transakcje IAP. Jeśli pole jest odznaczone, po udanej transakcji trzeba jawnie wywołać `iap.finish()`. -## Live update (Aktualizacje na żywo) +--- -#### Private Key -Jeśli zaznaczone, użyj podanego klucza prywatnego podczas budowania paczki aplikacji z zawartością do aktualizacji *live update*. Jeśli nie podany, zostanie automatycznie wygenerowany. +### Live update -#### Public Key -Jeśli zaznaczone, użyj podanego klucza publicznego podczas budowania paczki aplikacji z zawartością do aktualizacji *live update*. Jeśli nie podany, zostanie automatycznie wygenerowany. +#### Settings +Plik zasobu ustawień Liveupdate używany podczas bundlowania. -## Native extension (Rozszerzenia natywne) +#### Mount On Start +Włącza automatyczne montowanie wcześniej zamontowanych zasobów przy starcie aplikacji. + +--- + +### Native extension #### _App Manifest_ -Jeśli zaznaczone, użyj manifestu aplikacji do personalizacji wersji silnika (engine build). Pozwala to na usunięcie zbędnych części z silnika umożliwiając zmniejszenie ostatecznej wagi aplikacji. Funkcjonalność ta jest w wersji alpha. Odwiedź porszę [ten post na forum](https://forum.defold.com/t/native-extensions/4946/142), aby dowiedzieć się więcej. +Jeśli ustawiono, użyj manifestu aplikacji do dostosowania builda silnika. Pozwala to usunąć nieużywane części silnika i zmniejszyć rozmiar końcowego pliku binarnego. Jak wykluczać nieużywane funkcje opisano w [instrukcji Application Manifest](/manuals/app-manifest). + +--- + +### Profiler -## Profiler +#### Enabled +Włącza profiler w grze. #### Track Cpu -Jeśli zaznaczone, aktywowane będzie profilowanie CPU w wersji release. Normalnie można profilować tylko w wersji debug. +Po zaznaczeniu włącza profilowanie CPU w buildach release. Normalnie informacje profilujące są dostępne tylko w buildach debug. -## Format pliku +#### Sleep Between Server Updates +Liczba milisekund uśpienia pomiędzy aktualizacjami serwera. -Format pliku z ustawieniami jest plikiem tekstowym (INI format) i może być dowolnie modyfikowany przez każdy edytor tekstu. Format wygląda następująco: +#### Performance Timeline Enabled +Włącza przeglądarkową oś czasu wydajności. Dotyczy tylko HTML5. -```ini -[category1] -setting1 = value -setting2 = value -[category2] +--- + +## Setting config values on engine startup + +Podczas uruchamiania silnika można przekazać z linii poleceń wartości konfiguracji, które nadpiszą ustawienia z *game.project*: + +```bash +# Określ kolekcję bootstrapową +$ dmengine --config=bootstrap.main_collection=/my.collectionc + +# Ustaw dwie własne wartości konfiguracyjne +$ dmengine --config=test.my_value=4711 --config=test2.my_value2=foobar +``` + +Własne wartości można odczytywać tak samo jak każdą inną wartość konfiguracyjną, za pomocą [`sys.get_config_string()`](/ref/sys/#sys.get_config_string) albo [`sys.get_config_number()`](/ref/sys/#sys.get_config_number): + +```lua +local my_value = sys.get_config_number("test.my_value") +local my_value2 = sys.get_config_string("test.my_value2") +``` + +## Component max count optimizations + +Plik ustawień *game.project* zawiera wiele wartości określających maksymalną liczbę określonego zasobu, który może istnieć jednocześnie, najczęściej w przeliczeniu na załadowaną kolekcję, nazywaną też światem. Silnik Defold używa tych wartości maksymalnych do wstępnej alokacji pamięci, aby ograniczyć dynamiczne alokacje i fragmentację pamięci podczas działania gry. + +Struktury danych Defold używane do reprezentowania komponentów i innych zasobów są zoptymalizowane pod kątem jak najmniejszego zużycia pamięci, ale przy ustawianiu tych wartości nadal trzeba zachować ostrożność, aby nie przydzielać więcej pamięci, niż naprawdę potrzeba. + +Aby dodatkowo zoptymalizować zużycie pamięci, proces builda Defold analizuje zawartość gry i nadpisuje wartości maksymalne tam, gdzie można z całkowitą pewnością określić dokładną liczbę: + +* Jeśli kolekcja nie zawiera żadnych komponentów Factory, zostanie zaalokowana dokładna liczba każdego komponentu i obiektu gry, a wartości maksymalne zostaną zignorowane. +* Jeśli kolekcja zawiera komponent Factory, obiekty tworzone przez tę fabrykę zostaną przeanalizowane i dla komponentów możliwych do utworzenia przez Factory oraz dla obiektów gry zostaną użyte wartości max count. +* Jeśli kolekcja zawiera komponent Factory albo Collection factory z włączoną opcją `Dynamic Prototype`, ta kolekcja będzie używać liczników maksymalnych. + +## Custom project settings + +Można definiować własne ustawienia dla głównego projektu albo dla [native extension](/manuals/extensions/). Własne ustawienia dla głównego projektu należy zdefiniować w pliku `game.properties` w katalogu głównym projektu. W przypadku rozszerzenia natywnego należy je zdefiniować w pliku `ext.properties` obok pliku `ext.manifest`. + +Plik ustawień używa tego samego formatu INI co *game.project*, a atrybuty właściwości zapisuje się notacją z kropką i sufiksem: + +``` +[my_category] +my_property.private = 1 ... ``` -Przykład: +Domyślny plik meta, który jest zawsze stosowany, jest dostępny [tutaj](https://github.com/defold/defold/blob/dev/com.dynamo.cr/com.dynamo.cr.bob/src/com/dynamo/bob/meta.properties). + +Obecnie dostępne są następujące atrybuty: -```ini -[bootstrap] -main_collection = /main/main.collectionc ``` +[my_extension] +// `type` - używany przy parsowaniu łańcucha wartości +my_property.type = string // jedna z wartości: bool, string, number, integer, string_array, resource -co oznacza, że ustawienie *main_collection* należy do kategorii *bootstrap*. -Kiedy używana jest referencja do pliku, jak w powyższym przykładzie, ścieżka musi być zakończona znakiem 'c', co oznacza, że odnosisz się do skompilowanej wersji pliku. -Zauważ również, że folder zawieracjący plik *game.project* będzie folderem głównym projektu (root), stąd początkowy znak '/' w ścieżce do pliku. +// `help` - używany jako podpowiedź pomocy w edytorze (na razie nieużywany) +my_property.help = string -## Ustawianie wartości przy starcie silnika +// `default` - wartość domyślna używana, jeśli użytkownik nie ustawił wartości ręcznie +my_property.default = string -Kiedy silnik zostaje uruchomiony jest możliwe podanie wartości konfiguracji z lini wiersza poleceń, które nadpiszą wartości w pliku *game.project*: +// `private` - wartość prywatna używana podczas bundlowania, ale usuwana z samego bundla +my_property.private = 1 // wartość logiczna 1 albo 0 -```bash -# Określ kolekcę główną/bootstrapową -$ dmengine --config=bootstrap.main_collection=/my.collectionc +// `label` - etykieta pola w edytorze +my_property.label = My Awesome Property + +// `minimum` i/lub `maximum` - prawidłowy zakres dla właściwości liczbowych, walidowany w UI edytora +my_property.minimum = 0 +my_property.maximum = 255 + +// `options` - opcje listy rozwijanej w UI edytora, zapisane jako oddzielone przecinkami pary value[:label] +my_property.options = android: Android, ios: iOS -# Ustaw dwie wartości: -$ dmengine --config=test.my_value=4711 --config=test2.my_value2=1234 +// tylko dla typu `resource`: +my_property.filter = jpg,png // dozwolone rozszerzenia plików w selektorze zasobu +my_property.preserve-extension = 1 // użyj oryginalnego rozszerzenia zasobu zamiast rozszerzenia builda + +// oznaczanie jako przestarzałe +my_property.deprecated = 1 // oznacz właściwość jako przestarzałą +my_property.severity-default = warning // gdy przestarzała właściwość jest ustawiona, ale ma wartość domyślną +my_property.severity-override = error // gdy przestarzała właściwość jest ustawiona i ma wartość inną niż domyślna ``` -Twoje wartości mogą ---tak jak każde inne wartości konfiguracji--- być odczytane w trakcie działania aplikacji dzięki funkcji [`sys.get_config()`](/ref/sys/#sys.get_config): +Dodatkowo na kategorii ustawień można ustawić następujące atrybuty: -```lua -local my_value = tonumber(sys.get_config("test.my_value")) +``` +[my_extension] +// `group` - grupa kategorii w game.project, np. Main, Platforms, Components, Runtime, Distribution +group = Runtime +// `title` - wyświetlany tytuł kategorii +title = My Awesome Extension +// `help` - wyświetlana pomoc kategorii +help = Settings for My Awesome Extension ``` -## Vsync, frame cap, i swap interval -Po pierwsze na komputerach osobistych opcja `Vsync` (synchronizacja pionowa) może być kontrolowana globalnie przez ustawienia karty graficznej. Jeśli przykładowo opcja vsync jest wymuszona jako ustawiona w panelu kontrolnym karty graficznej, nie jest już możliwe zmienienie jej z poziomu użytkownika, czyli Defold nie może mieć do niej dostępu ani jej zmodyfikować. Większość urządzeń ma opcję vsync uruchomioną domyślnie. - -Kiedy opcja `Vsync` jest zaznaczona w pliku *game.project* silnik będzie polegał na sprzętowym wsparciu synchronizacji pionowej i używał stałej wartości długości ramki `dt` bazującej na wartości częstotliwości odświeżania monitora. Jest to domyślne ustawienie. Kiedy opcja `Vsync` jest zaznaczona, a `Frame cap` > 0, wartość długości będzie zmniejszona do interwału przejścia odpowiadającego częstotliwości odświeżania głównego wykrytego monitora. Kiedy opcja `Vsync` jest odznaczona, a `Frame cap` = 0, wartość długości ramki nie jest stała, tylko używa aktualnej przyblizonej wartości różnicy czasowej dla wartości `dt`. Kiedy opcja `Vsync` jest odznaczona, a `Frame cap` > 0, używane są timery, aby dostosować się do podanej wartości frame cap. Nie ma niestety gwarancji, że wartość frame cap zostanie osiągnięta na różnych platformach i w zależności od różnych ustawień sprzętowych. - -Interwał zmiany (Swap interval) jest przedziałem czasowym określającym kiedy zamienić przedni i tylni bufor podczas synchronizacji z pionowymi pustkami (vertical blanks - v-blank), sprzętowe wydarzenie, gdzie ekran jest aktualizowany danymi z przedniego bufora. Wartość 1 pozwala na zamianę buforów przy każdym v-blanku, wartość 2 zamienia bufory przy co drugim v-blanku itd. Wartość 0 wyłącza oczekiwanie na v-blank przed zamianą buforów\*. Ustawienie `swap_interval` można zmienić dzięki funkcji [```set_vsync_swap_interval```](/ref/sys/#sys.set_vsync_swap_interval:swap_interval). - -### Zastrzeżenie -Obecnie, Defold odpytuje o częstotliwość odświeżania monitora podczas inicjalizacji silnika i używa tej wartości jako bazy przy wyborze stałej wartości `dt`. Jeśli chcesz wspierać monitory ze zmienną wartością częstotliwości odświeżania (np. GSync albo FreeSync) lub w innych scenariuszach gdzie wartość częstotliwości odświeżania nie jest trywialna do ustalenia, odznacz opcję `Vsync`, żeby pozwolić silnikowi dobrać `dt` podczas każdej ramki, zamiast polegać na stałej wartości. - -### Vsync i frame cap w Defoldzie* - - - - - - - - - - - - - - - - - -
Frame cap 0 (default)Frame cap > 0
Vsync checked (default)Relies on hardware vsync. Fixed dt of 1/(detected monitor refresh rate).Fixed dt of (swap interval)/(detected monitor refresh rate) where swap interval is clamped to the closest matching monitor refresh rate frame cap multiple.
Vsync uncheckedCalculates dt each frame based on elapsed system time. Vsync might still be enabled in driver settings.Uses a fixed dt of 1 / (Frame cap). Uses timers and sleeps to respect the set frame cap.
+Obecnie właściwości meta są używane tylko w `bob.jar` podczas bundlowania aplikacji, ale w przyszłości będą też parsowane przez edytor i prezentowane w widoku *game.project*. diff --git a/docs/pl/manuals/script.md b/docs/pl/manuals/script.md index 8de3c5a6..e9525505 100644 --- a/docs/pl/manuals/script.md +++ b/docs/pl/manuals/script.md @@ -1,145 +1,155 @@ --- title: Pisanie logiki gry w skryptach -brief: Ta instrukcja opisuje szczegóły pisania logiki gry w komponentach typu skrypt. +brief: Ta instrukcja opisuje, jak dodawać logikę gry za pomocą komponentów Script. --- # Skrypty -Komponent typu skrypt (ang. script) pozwala na tworzenie logiki gry przy użyciu języka programowania Lua. Skrypty dodawane są do obiektów gry dokładnie tak samo jak każdy inny [komponent](/manuals/components), a Defold wykona kod Lua w ramach funkcji cyklu życia silnika. +Komponenty Script pozwalają tworzyć logikę gry przy użyciu [języka Lua](/manuals/lua). ## Typy skryptów -W Defoldzie występują trzy rodzaje skryptów Lua, z dostępem do różnych bibliotek Defolda. +W Defold występują trzy typy skryptów Lua. Każdy z nich ma dostęp do innego zestawu bibliotek Defold. -Skrypty logiczne (.script) -: Uruchamiane przez komponenty skryptu w obiektach gry. Skrypty logiczne są zazwyczaj używane do kontrolowania obiektów gry i logiki łączącej grę z ładowaniem poziomów, zasadami gry itp. Skrypty logiczne mają dostęp do wszystkich funkcji bibliotek Defold, z wyjątkiem funkcji [GUI](/ref/gui) i [Render](/ref/render). +Skrypty obiektów gry +: Rozszerzenie _.script_. Te skrypty dodaje się do obiektów gry dokładnie tak samo jak każdy inny [komponent](/manuals/components), a Defold wykonuje kod Lua w ramach funkcji cyklu życia silnika. Skrypty obiektów gry są zwykle używane do sterowania obiektami gry oraz logiką spajającą całą grę, taką jak ładowanie poziomów, reguły gry i podobne elementy. Skrypty obiektów gry mają dostęp do funkcji [GO](/ref/go) oraz do wszystkich bibliotek Defold poza [GUI](/ref/gui) i [Render](/ref/render). -Skrypty GUI (.gui_script) -: Uruchamiane przez komponenty GUI i zazwyczaj zawierają logikę wymaganą do wyświetlania elementów interfejsu użytkownika, takich jak wyświetlacze informacji, menu itp. Skrypty GUI mają dostęp do funkcji biblioteki [GUI](/ref/gui). +Skrypty GUI +: Rozszerzenie _.gui_script_. Są uruchamiane przez komponenty GUI i zwykle zawierają logikę potrzebną do wyświetlania elementów interfejsu, takich jak HUD-y, menu i podobne elementy. Defold wykonuje kod Lua w ramach funkcji cyklu życia silnika. Skrypty GUI mają dostęp do funkcji [GUI](/ref/gui) oraz do wszystkich bibliotek Defold poza [GO](/ref/go) i [Render](/ref/render). -Skrypty renderowania (.render_script) -: Uruchamiane przez potok renderowania (rendering pipeline) i zawierają logikę wymaganą do renderowania grafiki aplikacji/gry w każdej klatce. Skrypty renderowania mają dostęp do funkcji biblioteki [Render](/ref/render). +Skrypty renderowania +: Rozszerzenie _.render_script_. Są uruchamiane przez potok renderowania i zawierają logikę potrzebną do renderowania całej grafiki aplikacji lub gry w każdej klatce. Skrypt renderowania zajmuje szczególne miejsce w cyklu życia gry. Szczegóły znajdziesz w [dokumentacji cyklu życia aplikacji](/manuals/application-lifecycle). Skrypty renderowania mają dostęp do funkcji [Render](/ref/render) oraz do wszystkich bibliotek Defold poza [GO](/ref/go) i [GUI](/ref/gui). -## Wykonywanie skryptów, wywołania zwrotne i "self" +## Wykonywanie skryptów, callbacki i `self` -Defold wykonuje skrypty Lua jako część cyklu życia silnika i ujawnia cykl życia przez zestaw predefiniowanych funkcji wywołania zwrotnego. Gdy dodasz komponent skryptu do obiektu gry, skrypt staje się częścią cyklu życia obiektu gry i jego komponentu (lub komponentów). Skrypt jest oceniany w kontekście Lua, gdy jest wczytywany, a następnie silnik wykonuje następujące funkcje i przekazuje odniesienie do bieżącej instancji komponentu skryptu. Możesz użyć tego odniesienia "self" do przechowywania stanu w instancji komponentu. +Defold wykonuje skrypty Lua jako część cyklu życia silnika i udostępnia ten cykl przez zestaw predefiniowanych funkcji callback. Gdy dodasz komponent skryptu do obiektu gry, skrypt staje się częścią cyklu życia tego obiektu i jego komponentów. Skrypt jest interpretowany w kontekście Lua podczas wczytywania, a następnie silnik wywołuje poniższe funkcje, przekazując referencję do bieżącej instancji komponentu skryptu. Możesz używać tej referencji `self` do przechowywania stanu instancji komponentu. -::: ważne -"Self" to obiekt typu userdata, który działa jak tabela Lua, ale nie można go przeglądać za pomocą pairs() ani ipairs(), ani drukować za pomocą pprint(). +::: important +`self` jest obiektem userdata, który zachowuje się podobnie do tabeli Lua, ale nie można po nim iterować za pomocą `pairs()` ani `ipairs()` i nie można go wypisać przez `pprint()`. ::: -init(self) -: Wywoływane, gdy komponent jest inicjowany. +#### `init(self)` +Wywoływana podczas inicjalizacji komponentu. - ```lua - function init(self) - -- These variables are available through the lifetime of the component instance - self.my_var = "something" - self.age = 0 - end - ``` +```lua +function init(self) + -- Te zmienne są dostępne przez cały czas życia instancji komponentu + self.my_var = "something" + self.age = 0 +end +``` -final(self) -: Wywoływane, gdy komponent jest usuwany. Przydatne do celów sprzątania, na przykład, jeśli utworzyłeś obiekty gry, które powinny być usunięte, gdy komponent jest usuwany. +#### `final(self)` +Wywoływana podczas usuwania komponentu. Przydaje się do porządkowania zasobów, na przykład jeśli utworzono obiekty gry, które powinny zostać usunięte razem z komponentem. - ```lua - function final(self) - if self.my_var == "something" then - -- wykonaj jakiś kod - end +```lua +function final(self) + if self.my_var == "something" then + -- wykonaj czynności porządkowe end +end +``` -update(self, dt) -: Wywoływane raz w każdej klatce. dt zawiera czas delta od ostatniej klatki. +#### `fixed_update(self, dt)` +Aktualizacja niezależna od liczby klatek. Parametr `dt` zawiera czas, jaki upłynął od poprzedniej aktualizacji. Ta funkcja jest wywoływana `0-N` razy, zależnie od czasu trwania klatki i częstotliwości aktualizacji stałokrokowej. Jest wywoływana tylko wtedy, gdy w *game.project* włączone jest Physics ▸ Use Fixed Timestep, a Engine ▸ Fixed Update Frequency ma wartość większą od 0. Jest przydatna, gdy chcesz manipulować obiektami fizycznymi w regularnych odstępach, aby uzyskać stabilną symulację fizyki. - ```lua - function update(self, dt) - self.age = self.age + dt -- increase age with the timestep - end - ``` +```lua +function fixed_update(self, dt) + msg.post("#co", "apply_force", {force = vmath.vector3(1, 0, 0), position = go.get_world_position()}) +end +``` -fixed_update(self, dt) -: Aktualizacja niezależna od liczby klatek. dt zawiera czas delta od ostatniej aktualizacji. Ta funkcja jest wywoływana, gdy engine.fixed_update_frequency jest włączony (!= 0) i jest przydatna, gdy chcesz manipulować obiektami fizycznymi w regularnych odstępach czasu, aby uzyskać stabilną symulację fizyki, gdy physics.use_fixed_timestep jest włączone w *game.project*. +#### `update(self, dt)` +Wywoływana raz na każdą klatkę po callbacku `fixed_update` wszystkich skryptów, jeśli włączony jest Fixed Timestep. Parametr `dt` zawiera czas, jaki upłynął od poprzedniej klatki. - ```lua - function fixed_update(self, dt) - msg.post("#co", "apply_force", {force = vmath.vector3(1, 0, 0), position = go.get_world_position()}) - end - ``` +```lua +function update(self, dt) + self.age = self.age + dt -- zwiększ wiek o krok czasu +end +``` -on_message(self, message_id, message, sender) -: Gdy wiadomości są wysyłane do komponentu skryptu za pomocą msg.post(), silnik wywołuje tę funkcję komponentu odbiorczego. Dowiedz się więcej na temat przekazywania wiadomości. +#### `late_update(self, dt)` +Wywoływana raz na każdą klatkę po callbacku `update` wszystkich skryptów, ale tuż przed renderowaniem. Parametr `dt` zawiera czas, jaki upłynął od poprzedniej klatki. - ```lua - function on_message(self, message_id, message, sender) - if message_id == hash("increase_score") then - self.total_score = self.total_score + message.score - end - end +```lua +function late_update(self, dt) + go.set_position("/camera", self.final_camera_position) +end ``` -on_input(self, action_id, action) -: Jeśli ten komponent uzyskał fokus wejścia (zobacz acquire_input_focus), silnik wywołuje tę funkcję, gdy zostanie zarejestrowane wejście. Dowiedz się więcej na temat obsługi wejścia.' +#### `on_message(self, message_id, message, sender)` +Gdy wiadomości są wysyłane do komponentu skryptu przez [`msg.post()`](/ref/msg#msg.post), silnik wywołuje tę funkcję w komponencie odbiorcy. Więcej informacji znajdziesz w [instrukcji o przesyłaniu wiadomości](/manuals/message-passing). - ```lua - function on_input(self, action_id, action) - if action_id == hash("touch") and action.pressed then - print("Touch", action.x, action.y) - end - end - ``` +```lua +function on_message(self, message_id, message, sender) + if message_id == hash("increase_score") then + self.total_score = self.total_score + message.score + end +end +``` -on_reload(self) -: Ta funkcja jest wywoływana, gdy skrypt jest ponownie wczytywany za pomocą funkcji edytora "hot reload" (Edytuj ▸ Ponownie załaduj zasób). Jest bardzo przydatna do celów debugowania, testowania i dostrojenia. Dowiedz się więcej na temat ponownego ładowania na gorąco. +#### `on_input(self, action_id, action)` +Jeśli komponent przejął fokus wejścia, zobacz [`acquire_input_focus`](/ref/go/#acquire_input_focus), silnik wywołuje tę funkcję po zarejestrowaniu wejścia. Więcej informacji znajdziesz w [instrukcji o obsłudze wejścia](/manuals/input). - ```lua - function on_reload(self) - print(self.age) -- wyświetl wartość zmiennej self.age - end - ``` +```lua +function on_input(self, action_id, action) + if action_id == hash("touch") and action.pressed then + print("Touch", action.x, action.y) + end +end +``` + +#### `on_reload(self)` +Ta funkcja jest wywoływana, gdy skrypt zostaje przeładowany przez funkcję hot reload edytora (Edit ▸ Reload Resource). Jest bardzo przydatna podczas debugowania, testowania i strojenia. Więcej informacji znajdziesz w [instrukcji o szybkim przeładowaniu](/manuals/hot-reload). + +```lua +function on_reload(self) + print(self.age) -- wypisz wiek tego obiektu gry +end +``` ## Logika reaktywna -Obiekt gry z komponentem skryptu implementuje pewną logikę. Często zależy ona od pewnego czynnika zewnętrznego. Przykładowo sztuczna inteligencja przeciwnika może reagować na gracza znajdującego się w określonym promieniu od przeciwnika, drzwi mogą odblokować się i otworzyć w wyniku interakcji gracza itp. +Obiekt gry z komponentem skryptu implementuje pewną logikę. Często zależy ona od zewnętrznych czynników. Sztuczna inteligencja przeciwnika może reagować na gracza znajdującego się w określonym promieniu od niej, drzwi mogą się odblokować i otworzyć w wyniku interakcji gracza itd. -Funkcja `update()` pozwala na implementację złożonych zachowań zdefiniowanych jako automat stanów, który działa w każdej klatce - czasami jest to odpowiednie podejście. Jednak z każdym wywołaniem `update()` wiąże się pewien koszt. Jeśli naprawdę nie potrzebujesz tej funkcji, powinieneś ją usunąć i spróbować budować swoją logikę w sposób reaktywny. Oczekiwanie biernie na jakąś wiadomość, która wyzwoli reakcję, jest "tańsze" niż aktywne przeszukiwanie świata gry w poszukiwaniu danych do analizy. Ponadto rozwiązanie danego problemu w sposób reaktywny zazwyczaj prowadzi do czystszego i bardziej stabilnego projektu i jego implementacji. +Funkcja `update()` pozwala implementować złożone zachowania zdefiniowane jako automat stanów wykonywany w każdej klatce. Czasami jest to właściwe podejście. Każde wywołanie `update()` ma jednak swój koszt. Jeśli naprawdę nie potrzebujesz tej funkcji, usuń ją i spróbuj budować logikę w sposób _reaktywny_. Taniej jest biernie czekać na wiadomość, która wywoła reakcję, niż aktywnie sondować świat gry w poszukiwaniu danych do obsługi. Dodatkowo reaktywne rozwiązanie problemu projektowego często prowadzi do czytelniejszego i stabilniejszego projektu oraz implementacji. -Przyjrzyjmy się konkretnemu przykładowi. Załóżmy, że chcesz, aby komponent skryptu wysłał wiadomość 2 sekundy po inicjalizacji. Następnie powinien oczekiwać na określoną wiadomość odpowiedzi i po jej otrzymaniu, wysłać inną wiadomość 5 sekund później. Niereaktywny kod dla tego wyglądałby mniej więcej tak: +Spójrzmy na konkretny przykład. Załóżmy, że chcesz, aby komponent skryptu wysłał wiadomość 2 sekundy po inicjalizacji. Następnie powinien zaczekać na określoną wiadomość odpowiedzi i po jej otrzymaniu wysłać kolejną wiadomość 5 sekund później. Kod niereaktywny wyglądałby mniej więcej tak: ```lua function init(self) - -- Licznik czasu. + -- Licznik do śledzenia czasu self.counter = 0 - -- Potrzebujemy tego do śledzenia naszego stanu. + -- Potrzebujemy tego do śledzenia stanu self.state = "first" end function update(self, dt) self.counter = self.counter + dt if self.counter >= 2.0 and self.state == "first" then - -- wysłanie wiadomości po 2 sekundach + -- wyślij wiadomość po 2 sekundach msg.post("some_object", "some_message") self.state = "waiting" end if self.counter >= 5.0 and self.state == "second" then - -- wysłanie wiadomości 5 sekund po otrzymaniu "response" + -- wyślij wiadomość 5 sekund po otrzymaniu "response" msg.post("another_object", "another_message") - -- Wyczyszczenie stanu, aby nie wykonać tego bloku stanu ponownie. + -- Ustaw stan na nil, aby nie wejść w ten blok ponownie. self.state = nil end end function on_message(self, message_id, message, sender) if message_id == hash("response") then - -- Stan "pierwszy" zakończony, wchodzi kolejny + -- Zakończono stan "first", przejdź do następnego self.state = "second" - -- Wyzerowanie licznika + -- Wyzeruj licznik self.counter = 0 end end ``` -Even in this quite simple case we get fairly tangled up logic. It's possible to make this look better with the help of coroutines in a module (see below), but let's instead try to make this reactive and use a built-in timing mechanism. +Nawet w tak prostym przypadku logika dość szybko się komplikuje. Można ją uporządkować przy pomocy korutyn w module, zobacz niżej, ale spróbujmy zamiast tego podejścia reaktywnego i użyjmy wbudowanego mechanizmu odmierzania czasu. ```lua local function send_first() @@ -147,7 +157,7 @@ local function send_first() end function init(self) - -- Poczekaj 2 s, a następnie wywołaj send_first() + -- Poczekaj 2 s, a potem wywołaj send_first() timer.delay(2, false, send_first) end @@ -157,30 +167,31 @@ end function on_message(self, message_id, message, sender) if message_id == hash("response") then - -- Poczekaj 5 s, a następnie wywołaj send_second() + -- Poczekaj 5 s, a potem wywołaj send_second() timer.delay(5, false, send_second) end end ``` -To jest bardziej przejrzyste i łatwiejsze do śledzenia. Pozbywamy się wewnętrznych zmiennych stanu, które często są trudne do śledzenia przez logikę - i które mogą prowadzić do subtelnych błędów. Dodatkowo całkowicie rezygnujemy z funkcji `update()`. Zwalnia to silnik z wywoływania naszego skryptu 60 razy na sekundę. +To podejście jest czytelniejsze i łatwiejsze do śledzenia. Pozbywamy się wewnętrznych zmiennych stanu, które często trudno przeanalizować w toku logiki i które mogą prowadzić do subtelnych błędów. Dodatkowo całkowicie usuwamy funkcję `update()`. Dzięki temu silnik nie musi wywoływać naszego skryptu 60 razy na sekundę, nawet jeśli nic się w nim nie dzieje. ## Preprocessing -Przetwarzanie wstępne, czyli preprocessing wykrozystuje preprocesor Lua i specjalne znaczniki, aby warunkowo dołączać kod w zależności od wariantu budowy. Przykład: + +Można używać preprocesora Lua i specjalnych znaczników, aby warunkowo dołączać kod zależnie od wariantu builda. Przykład: ```lua --- Użyj jednego z tych słów kluczowych: RELEASE, DEBUG lub HEADLESS +-- Użyj jednego z następujących słów kluczowych: RELEASE, DEBUG lub HEADLESS --#IF DEBUG local lives_num = 999 ---#ELSE +--#ELSE local lives_num = 3 --#ENDIF ``` -Preprocesor jest dostępny jako rozszerzenie budowania. Dowiedz się więcej na temat sposobu instalacji i użycia na [stronie rozszerzenia na GitHubie](https://github.com/defold/extension-lua-preprocessor). +Preprocesor jest dostępny jako rozszerzenie builda. Więcej informacji o instalacji i użyciu znajdziesz na [stronie rozszerzenia w GitHub](https://github.com/defold/extension-lua-preprocessor). -## Wsparcie Edytora +## Wsparcie edytora -Edytor Defold obsługuje edycję skryptów Lua z kolorowaniem składni i autouzupełnianiem. Aby wyświetlić nazwy funkcji Defold, naciśnij Ctrl+Spacja, aby wyświetlić listę funkcji pasujących do tego, co wpisujesz. +Edytor Defold obsługuje edycję skryptów Lua z kolorowaniem składni i autouzupełnianiem. Aby uzupełnić nazwy funkcji Defold, naciśnij Ctrl+Space, by wyświetlić listę funkcji pasujących do wpisywanego tekstu. -![Automatyczne uzupełnianie](images/script/completion.png) +![Auto completion](images/script/completion.png) diff --git a/docs/pl/manuals/sprite.md b/docs/pl/manuals/sprite.md index 1dcda973..d698a8e9 100644 --- a/docs/pl/manuals/sprite.md +++ b/docs/pl/manuals/sprite.md @@ -1,89 +1,129 @@ --- -title: Sprite - reprezentacja graficzna 2D -brief: Instrukcja ta opisuje jak pokazywać dwuwymiarowe grafiki używając komponentu typu Sprite. +title: Wyświetlanie obrazów 2D +brief: Ta instrukcja opisuje, jak wyświetlać obrazy 2D i animacje przy użyciu komponentu Sprite. --- -# Sprite +# Sprite -Komponent typu Sprite (z ang. dosłownie: chochlik/duszek/krasnoludek - popularna w gamedevie od lat nazwa obrazków 2D w grach - przyp.tłum.) to dwuwymiarowa reprezentacja wizualna w grafice komputerowej wyświetlana jako pojedynczy obrazek lub animacja poklatkowa (flipbook animation). +Komponent Sprite to prosty obraz lub animacja poklatkowa (flipbook), która jest wyświetlana na ekranie. ![sprite](images/graphics/sprite.png) -Komponent typu Sprite może wykorzystywać jako teksturę galerię obrazów, tzw. [Atlas](/manuals/atlas) lub [Źródło kafelków - Tile Source](/manuals/tilesource). +Komponent Sprite może korzystać jako źródła grafiki z [Atlasu](/manuals/atlas) albo [Tile source (Źródła kafelków)](/manuals/tilesource). -## Właściwości Sprite'ów +## Właściwości komponentu Sprite -Poza właściwościami takimi jak *Id*, *Position* i *Rotation* komponenty te posiadają swoje specyficzne właściwości (properties): +Poza właściwościami *Id*, *Position* i *Rotation* komponent ma następujące właściwości specyficzne dla Sprite: *Image* -: Obraz/tekstura dwuwymiarowa - może nią być Galeria - `Atlas` lub Źródło kafelków - `Tile Source`. +: Jeśli shader ma pojedynczy sampler, to pole nosi nazwę `Image`. W przeciwnym razie każde pole jest nazwane zgodnie z samplerem tekstury w materiale. Każde pole określa zasób atlasu albo źródła kafelków używany przez sprite na danym samplerze tekstury. *Default Animation* -: Domyślna animacja używana przy wyświetlaniu obrazu. +: Animacja używana przez sprite. Informacje o animacji są pobierane z pierwszego atlasu albo źródła kafelków. *Material* -: Materiał służący do renderowania. +: Materiał używany do renderowania sprite'a. *Blend Mode* -: Tryb "mieszania"/blendowania używany również przy renderowaniu. Więcej szczegółów poniżej. +: Tryb mieszania używany podczas renderowania sprite'a. *Size Mode* -: Tryb rozmiaru - jeśli ustawiony na `Automatic`, to Edytor będzie ustawiał rozmiar sprite'a. Jeśli ustawiony na `Manual`, to możesz dopasować rozmiar sprite'a. +: Jeśli ustawisz `Automatic`, edytor sam ustawi rozmiar sprite'a. Jeśli ustawisz `Manual`, możesz ustawić rozmiar ręcznie. *Slice 9* -: Przekrój na 9 części - ustaw tę właściwość aby zachować prawidłowość pikseli na rogach sprite'a, kiedy jego rozmiar jest zmieniany. +: Ustaw tę opcję, aby zachować rozmiar pikseli tekstury przy krawędziach sprite'a podczas zmiany jego rozmiaru. -:[Więcej o funkcjonalności Slice-9 tutaj.](../shared/slice-9-texturing.md) +:[Slice-9](../shared/slice-9-texturing.md) -### Blend modes - tryby blendowania +### Tryby mieszania :[blend-modes](../shared/blend-modes.md) -## Manipulacja w trakcie działania programu +## Manipulacja w czasie działania -Możesz manipulować właściwościami Sprite'ów w trakcie działania programu dzięki wielu funkcjom i zmiennym właściwościom (szukaj przykładów użycia w [API](/ref/sprite/)). Funkcje: +Możesz modyfikować sprite'y w czasie działania za pomocą różnych funkcji i właściwości. Sposób użycia znajdziesz w [dokumentacji API](/ref/sprite/). Funkcje: -* `sprite.play_flipbook()` - Odtwarzaj animację sprite'a. -* `sprite.set_hflip()` and `sprite.set_vflip()` - Odwróć w pionie lub poziomie animację/obraz sprite'a. +* `sprite.play_flipbook()` - Odtwarza animację na komponencie Sprite. +* `sprite.set_hflip()` i `sprite.set_vflip()` - Ustawiają poziome i pionowe odbicie animacji sprite'a. -Sprite posiada również różne właściwości, którymi można manipulować przy użyciu funkcji `go.get()` i `go.set()`: +Sprite ma też kilka właściwości, którymi można manipulować przy użyciu `go.get()` i `go.set()`: `cursor` -: Znormalizowany (czyli w przedziale 0-1) kursor animacji, czyli wskaźnik na klatki danej animacji poklatkowej (liczba - `number`). +: Znormalizowany kursor animacji (`number`). `image` -: Obraz sprite'a (`hash`). Możesz użyć tej właściwości do podmiany tekstury sprite'a na inną galerią lub źródło kafelków, które mogą być właściwościami zasobu (resource property) i ustawić używając `go.set()`. Sprawdź szczegóły i przykłady w [API](/ref/sprite/#image). +: Obraz sprite'a (`hash`). Możesz go zmienić za pomocą właściwości zasobu wskazującej atlas albo źródło kafelków i funkcji `go.set()`. Przykład znajdziesz w [referencji API](/ref/sprite/#image). `material` -: Materiał sprite'a (`hash`). Możesz podmienić materiał korzystając z właściwości zasobu (resource property) i ustawić używając `go.set()`. Sprawdź szczegóły i przykłady w [API](/ref/sprite/#material). +: Materiał sprite'a (`hash`). Możesz go zmienić za pomocą właściwości zasobu materiału i funkcji `go.set()`. Przykład znajdziesz w [referencji API](/ref/sprite/#material). `playback_rate` -: Wskaźnik odtwarzania animacji, czyli prędkość z jaką odtwarzana jest animacja (`number`). +: Tempo odtwarzania animacji (`number`). `scale` -: Skala obrazka (wektor - `vector3`). +: Niejednorodna skala sprite'a (`vector3`). `size` -: Rozmiar obrazka (`vector3`) (Wartość tylko do odczytu - pokazuje rozmiar tekstury). +: Rozmiar sprite'a (`vector3`). Tę właściwość można zmienić tylko wtedy, gdy tryb rozmiaru sprite'a jest ustawiony na ręczny. ## Stałe materiału {% include shared/material-constants.md component='sprite' variable='tint' %} `tint` -: Kolor zabarwienia/odcienia obrazka (`vector4`). Wektor czterech komponentów reprezentuje zabarwienie, gdzie komponenty x, y, z, w odpowiadają składowym: czerwony, zielony, niebieski i przezroczystość (red, green, blue, alpha). +: Odcień koloru sprite'a (`vector4`). `vector4` reprezentuje zabarwienie, gdzie składowe x, y, z i w odpowiadają kolejno kanałom czerwieni, zieleni, błękitu i alfa. ## Atrybuty materiału -Sprite może nadpisywać atrybuty wierzchołków (vertex attributes) aktualnie przypisanego materiały i przekazywać je do shadera wierzchołków (vertex shader) z komponentu (szczegóły znajdziesz w [instrukcji do materiałów](/manuals/material/#attributes)). +Sprite może nadpisywać atrybuty wierzchołków z aktualnie przypisanego materiału. Zostaną one przekazane z komponentu do vertex shadera. Więcej informacji znajdziesz w [instrukcji do materiałów](/manuals/material/#attributes). -Atrybuty określone w materiale pokażą się jako zwykłe właściwości w widoku inspekcyjnym i mogą być ustawione na indywidualne komponenty sprite. Jeśli jakikolwiek atrybut jest nadpisany, zostanie on zaznaczony jako nadpisana właściwość i przechowana w pliku komponenty sprite na dysku. +Atrybuty określone w materiale pojawią się w inspectorze jako zwykłe właściwości i można je ustawiać osobno dla każdego komponentu Sprite. Jeśli którykolwiek atrybut zostanie nadpisany, będzie widoczny jako nadpisana właściwość i zostanie zapisany w pliku sprite'a na dysku: ![sprite-attributes](../images/graphics/sprite-attributes.png) -::: sidenote -Niestandardowe atrybuty są dostępne od wersji Defold 1.4.8! -::: - ## Konfiguracja projektu -Plik *game.project* zawiera [te ustawienia](/manuals/project-settings#sprite) dotyczące sprite'ów. +Plik *game.project* zawiera kilka [ustawień projektu](/manuals/project-settings#sprite) związanych ze sprite'ami. + +## Sprite'y z wieloma teksturami + +Gdy sprite korzysta z wielu tekstur, warto pamiętać o kilku rzeczach. + +### Animacje + +Dane animacji, takie jak fps i nazwy klatek, są obecnie pobierane z pierwszej tekstury. Nazwijmy ją „animacją sterującą”. + +Id obrazów z animacji sterującej są używane do wyszukiwania obrazów w kolejnej teksturze. Dlatego ważne jest, aby id klatek były zgodne pomiędzy teksturami. + +Na przykład, jeśli `diffuse.atlas` ma animację `run` w takiej postaci: + +``` +run: + /main/images/hero_run_color_1.png + /main/images/hero_run_color_2.png + ... +``` + +to id klatek będą wyglądały tak: `run/hero_run_color_1`. Taki identyfikator prawdopodobnie nie zostanie znaleziony na przykład w `normal.atlas`: + +``` +run: + /main/images/hero_run_normal_1.png + /main/images/hero_run_normal_2.png + ... +``` + +Dlatego używamy `Rename patterns` w [instrukcji do atlasów](/manuals/atlas/), aby zmienić te nazwy. Ustaw `_color=` i `_normal=` w odpowiednich atlasach, a w obu atlasach otrzymasz nazwy klatek w tej postaci: + +``` +run/hero_run_1 +run/hero_run_2 +... +``` + +### UVs + +Współrzędne UV są pobierane z pierwszej tekstury. Ponieważ istnieje tylko jeden zestaw wierzchołków, nie da się zagwarantować dobrego dopasowania, jeśli dodatkowe tekstury mają więcej współrzędnych UV albo inny kształt. + +Warto o tym pamiętać i zadbać, aby obrazy miały wystarczająco podobne kształty, bo w przeciwnym razie może pojawić się bleeding tekstur. + +Wymiary obrazów w poszczególnych teksturach mogą się różnić. From c5ff54ff1684be7a0e9fec037621811dc255c5e5 Mon Sep 17 00:00:00 2001 From: AGulev Date: Fri, 13 Mar 2026 13:22:00 +0100 Subject: [PATCH 3/8] tiny fixes --- docs/pl/manuals/collection-factory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pl/manuals/collection-factory.md b/docs/pl/manuals/collection-factory.md index bc1f9cbd..99e76012 100644 --- a/docs/pl/manuals/collection-factory.md +++ b/docs/pl/manuals/collection-factory.md @@ -3,7 +3,7 @@ title: Fabryki kolekcji brief: Ta instrukcja wyjaśnia, jak używać komponentów Collection factory do tworzenia hierarchii obiektów gry. --- -# Fabryki kolekcji +# Fabryki kolekcji (Collection factory) Komponent Collection factory służy do tworzenia grup i hierarchii obiektów gry zapisanych w plikach kolekcji w działającej grze. From 6f250c482fb5d72f90747bdb7cacc39596053d37 Mon Sep 17 00:00:00 2001 From: AGulev Date: Sun, 22 Mar 2026 09:59:17 +0100 Subject: [PATCH 4/8] big iteration --- docs/pl/faq/faq.md | 313 +++ docs/pl/glossary.txt | 2122 +++++++++++++++++ docs/pl/manuals/app-manifest.md | 119 + docs/pl/manuals/application-security.md | 109 + docs/pl/manuals/bob.md | 225 ++ docs/pl/manuals/buffer.md | 33 + docs/pl/manuals/bundling.md | 89 + docs/pl/manuals/compute.md | 234 ++ .../manuals/debugging-game-and-system-logs.md | 112 + .../manuals/debugging-native-code-android.md | 85 + docs/pl/manuals/debugging-native-code-ios.md | 154 ++ docs/pl/manuals/debugging-native-code.md | 161 ++ docs/pl/manuals/debugging.md | 11 + docs/pl/manuals/design.md | 24 + docs/pl/manuals/dev-app.md | 67 + docs/pl/manuals/editor-scripts-ui.md | 370 +++ docs/pl/manuals/extender-docker-images.md | 46 + docs/pl/manuals/extender-local-setup.md | 133 ++ docs/pl/manuals/extensions-best-practices.md | 127 + docs/pl/manuals/extensions-cocoapods.md | 27 + .../manuals/extensions-debugging-android.md | 6 + docs/pl/manuals/extensions-debugging-ios.md | 6 + docs/pl/manuals/extensions-debugging.md | 6 + docs/pl/manuals/extensions-defold-sdk.md | 16 + docs/pl/manuals/extensions-ext-manifests.md | 75 + docs/pl/manuals/extensions-gradle.md | 31 + .../manuals/extensions-manifest-merge-tool.md | 359 +++ docs/pl/manuals/extensions-script-api.md | 53 + docs/pl/manuals/extensions.md | 249 ++ docs/pl/manuals/facebook.md | 6 + docs/pl/manuals/file-access.md | 138 ++ docs/pl/manuals/gpgs.md | 6 + docs/pl/manuals/graphics.md | 12 + docs/pl/manuals/hot-reload.md | 122 + docs/pl/manuals/html5.md | 334 +++ docs/pl/manuals/http-requests.md | 54 + docs/pl/manuals/iac.md | 44 + docs/pl/manuals/iap.md | 6 + docs/pl/manuals/instant-games.md | 6 + docs/pl/manuals/ios.md | 263 ++ docs/pl/manuals/linux.md | 11 + docs/pl/manuals/live-update-aws.md | 127 + docs/pl/manuals/live-update-scripting.md | 133 ++ docs/pl/manuals/macos.md | 127 + docs/pl/manuals/material.md | 333 +++ docs/pl/manuals/microsoft-xbox.md | 8 + docs/pl/manuals/models.md | 12 + docs/pl/manuals/networking.md | 26 + docs/pl/manuals/nintendo-switch.md | 31 + docs/pl/manuals/online-services.md | 26 + docs/pl/manuals/optimization-battery.md | 18 + docs/pl/manuals/optimization-memory.md | 27 + docs/pl/manuals/optimization-size.md | 100 + docs/pl/manuals/optimization-speed.md | 89 + docs/pl/manuals/optimization.md | 12 + docs/pl/manuals/physically-based-rendering.md | 392 +++ docs/pl/manuals/physics-events.md | 141 ++ docs/pl/manuals/porting-guidelines.md | 108 + docs/pl/manuals/profiling.md | 145 ++ docs/pl/manuals/project-defignore.md | 32 + docs/pl/manuals/push.md | 6 + docs/pl/manuals/render.md | 445 ++++ docs/pl/manuals/scene-editing.md | 8 + docs/pl/manuals/shader.md | 454 ++++ docs/pl/manuals/socket-connections.md | 22 + docs/pl/manuals/sony-playstation.md | 23 + docs/pl/manuals/sound-streaming.md | 119 + docs/pl/manuals/spinemodel.md | 6 + docs/pl/manuals/unity.md | 591 +++++ docs/pl/manuals/version-control.md | 30 + docs/pl/manuals/websocket-connections.md | 6 + docs/pl/manuals/webview.md | 6 + docs/pl/manuals/windows.md | 43 + docs/pl/manuals/working-offline.md | 55 + docs/pl/manuals/zerobrane.md | 99 + docs/pl/shared/android-adb.md | 33 + docs/pl/shared/android-faq.md | 30 + docs/pl/shared/apple-privacy-manifest.md | 7 + docs/pl/shared/build-variants.md | 37 + docs/pl/shared/bundle-resources.md | 20 + .../component-max-count-optimizations.md | 11 + docs/pl/shared/consoles-faq.md | 8 + docs/pl/shared/custom-resources.md | 3 + docs/pl/shared/editor-faq.md | 26 + docs/pl/shared/editor-versions.md | 11 + docs/pl/shared/editor-views.md | 0 docs/pl/shared/graphics-api.md | 8 + docs/pl/shared/html5-faq.md | 12 + docs/pl/shared/ios-faq.md | 16 + docs/pl/shared/linux-faq.md | 147 ++ docs/pl/shared/optimization-memory-html5.md | 21 + docs/pl/shared/platforms.md | 3 + docs/pl/shared/slice-9-texturing.md | 41 + docs/pl/shared/test.md | 5 + docs/pl/shared/windows-faq.md | 27 + docs/pl/translation-guidelines.txt | 4 +- docs/pl/tutorials/15-puzzle.md | 394 +++ docs/pl/tutorials/astronaut.md | 27 + docs/pl/tutorials/car.md | 438 ++++ docs/pl/tutorials/colorslide.md | 27 + docs/pl/tutorials/getting-started.md | 35 + docs/pl/tutorials/grading.md | 456 ++++ docs/pl/tutorials/hud.md | 164 ++ docs/pl/tutorials/level-complete.md | 226 ++ docs/pl/tutorials/magic-link.md | 1249 ++++++++++ docs/pl/tutorials/main-menu.md | 92 + docs/pl/tutorials/movement.md | 26 + docs/pl/tutorials/parallax.md | 82 + docs/pl/tutorials/platformer.md | 416 ++++ docs/pl/tutorials/rpgmap.md | 80 + docs/pl/tutorials/runner.md | 941 ++++++++ docs/pl/tutorials/shadertoy.md | 257 ++ docs/pl/tutorials/side-scroller.md | 25 + docs/pl/tutorials/snake.md | 481 ++++ docs/pl/tutorials/texture-scrolling.md | 113 + docs/pl/tutorials/war-battles.md | 28 + 116 files changed, 16190 insertions(+), 1 deletion(-) create mode 100644 docs/pl/faq/faq.md create mode 100644 docs/pl/glossary.txt create mode 100644 docs/pl/manuals/app-manifest.md create mode 100644 docs/pl/manuals/application-security.md create mode 100644 docs/pl/manuals/bob.md create mode 100644 docs/pl/manuals/buffer.md create mode 100644 docs/pl/manuals/bundling.md create mode 100644 docs/pl/manuals/compute.md create mode 100644 docs/pl/manuals/debugging-game-and-system-logs.md create mode 100644 docs/pl/manuals/debugging-native-code-android.md create mode 100644 docs/pl/manuals/debugging-native-code-ios.md create mode 100644 docs/pl/manuals/debugging-native-code.md create mode 100644 docs/pl/manuals/debugging.md create mode 100644 docs/pl/manuals/design.md create mode 100644 docs/pl/manuals/dev-app.md create mode 100644 docs/pl/manuals/editor-scripts-ui.md create mode 100644 docs/pl/manuals/extender-docker-images.md create mode 100644 docs/pl/manuals/extender-local-setup.md create mode 100644 docs/pl/manuals/extensions-best-practices.md create mode 100644 docs/pl/manuals/extensions-cocoapods.md create mode 100644 docs/pl/manuals/extensions-debugging-android.md create mode 100644 docs/pl/manuals/extensions-debugging-ios.md create mode 100644 docs/pl/manuals/extensions-debugging.md create mode 100644 docs/pl/manuals/extensions-defold-sdk.md create mode 100644 docs/pl/manuals/extensions-ext-manifests.md create mode 100644 docs/pl/manuals/extensions-gradle.md create mode 100644 docs/pl/manuals/extensions-manifest-merge-tool.md create mode 100644 docs/pl/manuals/extensions-script-api.md create mode 100644 docs/pl/manuals/extensions.md create mode 100644 docs/pl/manuals/facebook.md create mode 100644 docs/pl/manuals/file-access.md create mode 100644 docs/pl/manuals/gpgs.md create mode 100644 docs/pl/manuals/graphics.md create mode 100644 docs/pl/manuals/hot-reload.md create mode 100644 docs/pl/manuals/html5.md create mode 100644 docs/pl/manuals/http-requests.md create mode 100644 docs/pl/manuals/iac.md create mode 100644 docs/pl/manuals/iap.md create mode 100644 docs/pl/manuals/instant-games.md create mode 100644 docs/pl/manuals/ios.md create mode 100644 docs/pl/manuals/linux.md create mode 100644 docs/pl/manuals/live-update-aws.md create mode 100644 docs/pl/manuals/live-update-scripting.md create mode 100644 docs/pl/manuals/macos.md create mode 100644 docs/pl/manuals/material.md create mode 100644 docs/pl/manuals/microsoft-xbox.md create mode 100644 docs/pl/manuals/models.md create mode 100644 docs/pl/manuals/networking.md create mode 100644 docs/pl/manuals/nintendo-switch.md create mode 100644 docs/pl/manuals/online-services.md create mode 100644 docs/pl/manuals/optimization-battery.md create mode 100644 docs/pl/manuals/optimization-memory.md create mode 100644 docs/pl/manuals/optimization-size.md create mode 100644 docs/pl/manuals/optimization-speed.md create mode 100644 docs/pl/manuals/optimization.md create mode 100644 docs/pl/manuals/physically-based-rendering.md create mode 100644 docs/pl/manuals/physics-events.md create mode 100644 docs/pl/manuals/porting-guidelines.md create mode 100644 docs/pl/manuals/profiling.md create mode 100644 docs/pl/manuals/project-defignore.md create mode 100644 docs/pl/manuals/push.md create mode 100644 docs/pl/manuals/render.md create mode 100644 docs/pl/manuals/scene-editing.md create mode 100644 docs/pl/manuals/shader.md create mode 100644 docs/pl/manuals/socket-connections.md create mode 100644 docs/pl/manuals/sony-playstation.md create mode 100644 docs/pl/manuals/sound-streaming.md create mode 100644 docs/pl/manuals/spinemodel.md create mode 100644 docs/pl/manuals/unity.md create mode 100644 docs/pl/manuals/version-control.md create mode 100644 docs/pl/manuals/websocket-connections.md create mode 100644 docs/pl/manuals/webview.md create mode 100644 docs/pl/manuals/windows.md create mode 100644 docs/pl/manuals/working-offline.md create mode 100644 docs/pl/manuals/zerobrane.md create mode 100644 docs/pl/shared/android-adb.md create mode 100644 docs/pl/shared/android-faq.md create mode 100644 docs/pl/shared/apple-privacy-manifest.md create mode 100644 docs/pl/shared/build-variants.md create mode 100644 docs/pl/shared/bundle-resources.md create mode 100644 docs/pl/shared/component-max-count-optimizations.md create mode 100644 docs/pl/shared/consoles-faq.md create mode 100644 docs/pl/shared/custom-resources.md create mode 100644 docs/pl/shared/editor-faq.md create mode 100644 docs/pl/shared/editor-versions.md create mode 100644 docs/pl/shared/editor-views.md create mode 100644 docs/pl/shared/graphics-api.md create mode 100644 docs/pl/shared/html5-faq.md create mode 100644 docs/pl/shared/ios-faq.md create mode 100644 docs/pl/shared/linux-faq.md create mode 100644 docs/pl/shared/optimization-memory-html5.md create mode 100644 docs/pl/shared/platforms.md create mode 100644 docs/pl/shared/slice-9-texturing.md create mode 100644 docs/pl/shared/test.md create mode 100644 docs/pl/shared/windows-faq.md create mode 100644 docs/pl/tutorials/15-puzzle.md create mode 100644 docs/pl/tutorials/astronaut.md create mode 100644 docs/pl/tutorials/car.md create mode 100644 docs/pl/tutorials/colorslide.md create mode 100644 docs/pl/tutorials/getting-started.md create mode 100644 docs/pl/tutorials/grading.md create mode 100644 docs/pl/tutorials/hud.md create mode 100644 docs/pl/tutorials/level-complete.md create mode 100644 docs/pl/tutorials/magic-link.md create mode 100644 docs/pl/tutorials/main-menu.md create mode 100644 docs/pl/tutorials/movement.md create mode 100644 docs/pl/tutorials/parallax.md create mode 100644 docs/pl/tutorials/platformer.md create mode 100644 docs/pl/tutorials/rpgmap.md create mode 100644 docs/pl/tutorials/runner.md create mode 100644 docs/pl/tutorials/shadertoy.md create mode 100644 docs/pl/tutorials/side-scroller.md create mode 100644 docs/pl/tutorials/snake.md create mode 100644 docs/pl/tutorials/texture-scrolling.md create mode 100644 docs/pl/tutorials/war-battles.md diff --git a/docs/pl/faq/faq.md b/docs/pl/faq/faq.md new file mode 100644 index 00000000..6a21cb55 --- /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 i edytor Defold z pełną funkcjonalnością są całkowicie bezpłatne. Bez ukrytych kosztów, opłat ani tantiem. Po prostu za darmo. + + +#### P: Dlaczego Defold Foundation miałaby udostępniać 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, aby przez wiele kolejnych lat pozostawać odpowiedzialnym właścicielem silnika Defold. Nie zniknie. + + +#### P: Czy mogę zaufać Defold w profesjonalnej produkcji? + +A: Oczywiście. 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 nawiązało współpracę z Defold, a w 2014 roku przejęło 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 dodanie 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ń, czyli przy niskim nakładzie 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/). API skryptu renderowania w 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ę Help ▸ 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 dotyczące edytora](../shared/editor-faq.md) + + +## Pytania o Linuksa +:[FAQ dotyczące Linuksa](../shared/linux-faq.md) + + +## Pytania o Androida +:[FAQ dotyczące Androida](../shared/android-faq.md) + + +## Pytania o HTML5 +:[FAQ dotyczące HTML5](../shared/html5-faq.md) + + +## Pytania o iOS +:[FAQ dotyczące iOS](../shared/ios-faq.md) + + +## Pytania o Windows +:[FAQ dotyczące Windows](../shared/windows-faq.md) + + +## Pytania o konsole +:[FAQ dotyczące 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 podczas korzystania z 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ść 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ę, jakich obiektów 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. ParticleFX, który nie jest odtwarzany, nie ma żadnego 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 rezerwowana 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/app-manifest.md b/docs/pl/manuals/app-manifest.md new file mode 100644 index 00000000..c6fe13f0 --- /dev/null +++ b/docs/pl/manuals/app-manifest.md @@ -0,0 +1,119 @@ +--- +title: Manifest aplikacji +brief: Ta instrukcja opisuje, jak manifest aplikacji może służyć do wykluczania funkcji z silnika. +--- + +# Manifest aplikacji + +Manifest aplikacji służy do wykluczania funkcji z silnika albo określania, które funkcje 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 czy ustawienia pamięci. Te ustawienia 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 polu 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 [instrukcji 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 [instrukcji 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 wspierana 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 wspierana 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 wspierana 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, z której może korzystać aplikacja webowa. 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 wartość musi 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ść opcji `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-security.md b/docs/pl/manuals/application-security.md new file mode 100644 index 00000000..4afb0330 --- /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 osadza je w kontekście bezpieczeństwa aplikacji podczas korzystania z silnika, narzędzi i usług Defold: + +* 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ć zawartość gry stanowiącą efekt pracy twórczej. Trzeba jednak pamiętać, że gdy gra trafi już w ręce gracza, da się znaleźć sposoby na wyodrębnienie zasobów. Można to osiągnąć przez inżynierię wsteczną aplikacji i plików gry, ale też przy użyciu narzędzi do wyodrębniania tekstur i modeli w momencie, gdy są wysyłane do GPU albo gdy inne zasoby są ładowane do pamięci. + +Z tego powodu zakładamy, że jeśli użytkownicy są zdeterminowani, by wyodrębnić zasoby gry, ostatecznie będą w stanie to zrobić. + +Twórcy mogą dodać własne zabezpieczenia, aby utrudnić wyodrębnienie zasobów, __ale nie uczynić go 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ę proces budowania w Defold. + +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 +W trakcie procesu budowania w Defold zasoby gry są przetwarzane i przekształcane do formatów odpowiednich do użycia przez silnik Defold 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 dostępu do 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 pliku binarnym 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łasne nadpisania mechanizmu pobierania wartości konfiguracji używanego 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 do cheatów 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 pamięci w celu modyfikowania wyników, żyć, amunicji itd. + +Ochrona przed oszustami jest trudna, wręcz graniczy z niemożliwością. 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; takie kwestie pozostawia 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 przejrzeć 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 (application manifest), aby usunąć z silnika niewykorzystywane komponenty. + +Chmurowe serwery budowania są hostowane w AWS i zaprojektowane zgodnie z najlepszymi praktykami bezpieczeństwa. Defold Foundation nie gwarantuje jednak, że spełnią Twoje wymagania, będą wolne od wad i wirusów, bezpieczne lub pozbawione błędów 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/bob.md b/docs/pl/manuals/bob.md new file mode 100644 index 00000000..7afc97e6 --- /dev/null +++ b/docs/pl/manuals/bob.md @@ -0,0 +1,225 @@ +--- +title: Podręcznik narzędzia Bob do budowania projektów w Defold +brief: Bob to narzędzie wiersza poleceń do budowania projektów w Defold. Ta instrukcja wyjaśnia, jak korzystać z tego narzędzia. +--- + +# Bob, narzędzie do budowania + +Bob to narzędzie wiersza poleceń służące do budowania projektów w Defold poza standardowym przepływem pracy w edytorze. + +Bob potrafi budować dane projektu (co odpowiada działaniu Project ▸ Build w edytorze), tworzyć archiwa danych oraz tworzyć samodzielne, gotowe do dystrybucji pakiety aplikacji (co odpowiada opcjom z menu edytora Project ▸ Bundle ▸ ...). + +Bob jest dystrybuowany jako archiwum Java _JAR_ zawierające wszystko, co potrzebne 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. Dla 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` dla 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 pliki wygenerowane w 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 obecności 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 opcją `--bundle-output`. Nazwa pakietu wynika 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/bundling.md b/docs/pl/manuals/bundling.md new file mode 100644 index 00000000..44c787a7 --- /dev/null +++ b/docs/pl/manuals/bundling.md @@ -0,0 +1,89 @@ +--- +title: Tworzenie pakietu aplikacji +brief: Ta instrukcja opisuje, jak utworzyć pakiet aplikacji. +--- + +# Tworzenie pakietu aplikacji + +Podczas pracy nad aplikacją warto wyrobić sobie nawyk jak najczęstszego testowania gry na platformach docelowych. Pomaga to wcześnie wykrywać problemy z wydajnością, gdy są jeszcze znacznie łatwiejsze do naprawienia. Zalecamy też testowanie na wszystkich platformach docelowych, aby znaleźć rozbieżności, na przykład w shaderach. Podczas tworzenia wersji mobilnych 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 korzystania z zewnętrznych narzędzi. Możesz też tworzyć pakiety z wiersza poleceń za pomocą naszego narzędzia wiersza poleceń [Bob](/manuals/bob/). Utworzenie 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 wybranej platformy. + +### Raporty budowania + +Podczas tworzenia pakietu gry możesz utworzyć raport budowania. Jest to bardzo przydatne, jeśli chcesz zorientować się w rozmiarze 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 [pliku ustawień projektu *game.project*](/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 aplikacji bezpośrednio w edytorze Defold. W innych sytuacjach możesz chcieć automatycznie generować pakiety aplikacji, 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 aplikacji można wykonywać poza normalnym 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 folder ten może zostać także 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 w niezmienionej postaci. +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ą. +Do tych zasobów można uzyskać dostęp za pomocą funkcji [`sys.load_resource()`](https://defold.com/ref/sys/#sys.load_resource). + +## Wersje `release` i `debug` + +Podczas tworzenia pakietu aplikacji możesz wybrać wariant `debug` lub `release`. Różnice między nimi są niewielkie, ale warto o nich pamiętać: + +* 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 generowanych przez natywne rozszerzenia +* 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/compute.md b/docs/pl/manuals/compute.md new file mode 100644 index 00000000..50c7c535 --- /dev/null +++ b/docs/pl/manuals/compute.md @@ -0,0 +1,234 @@ +--- +title: Programy 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 części funkcji jeszcze brakuje, a API może w przyszłości ulec zmianie. +::: + +Shadery obliczeniowe (ang. compute shaders) są potężnym narzędziem do wykonywania obliczeń ogólnego przeznaczenia na GPU. Pozwalają wykorzystać moc przetwarzania równoległego 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. To 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). + +## Co można zrobić za pomocą shaderów obliczeniowych? + +Ponieważ shadery obliczeniowe są przeznaczone 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 barwna: dostosowywanie przestrzeni kolorów obrazu. + +Fizyka + - Systemy cząsteczek: symulacja dużej liczby cząsteczek dla efektów takich jak dym, ogień czy dynamika płynów. + - Fizyka ciał miękkich: symulacja odkształcalnych obiektów, takich jak tkanina czy 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 (Work Groups) +: Shader obliczeniowy działa na siatce `work groups`. Każda grupa robocza zawiera stałą liczbę wywołań (`invocations`, czyli wątków). Rozmiar grup roboczych i liczba wywołań są definiowane w kodzie shadera. + +Wywołania (Invocations) +: Każde wywołanie (`invocation`, czyli 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, kliknij prawym przyciskiem myszy 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 edytorze *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 istnieje stała definicja 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 odniesienie do programu compute. Obecnie jedynym sposobem, aby skrypt do renderowania wiedział o programie compute, jest dodanie go do pliku `.render`, który przechowuje odniesienie 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") +-- Do compute work here, call render.set_compute() to unbind +render.set_compute() +``` + +Choć stałe compute zostaną automatycznie zastosowane podczas wywołania 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 ustalonej przez siebie przestrzeni roboczej, musisz go wywołać: + +```lua +render.dispatch_compute(128, 128, 1) +-- dispatch_compute also accepts an options table as the last argument +-- you can use this argument table to pass in render constants to the dispatch call +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 dowolnego 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 opcji konfiguracji. Jak sugeruje nazwa, `storage textures` 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 +-- In a .script file: +function init(self) + -- Create a texture resource like usual, but add the "storage" flag + -- so it can be used as the backing storage for compute programs + 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, + }) + + -- get the texture handle from the resource + local t_backing_handle = resource.get_texture_info(t_backing).handle + + -- notify the renderer of the backing texture, so it can be bound with render.enable_texture + msg.post("@render:", "set_backing_texture", { handle = t_backing_handle }) +end +``` + +## Kompletny przykład + +### Program shadera + +```glsl +// compute.cp +#version 450 + +layout (local_size_x = 1, local_size_y = 1, local_size_z = 1) in; + +// specify the input resources +uniform vec4 color; +uniform sampler2D texture_in; + +// specify the output image +layout(rgba32f) uniform image2D texture_out; + +void main() +{ + // This isn't a particularly interesting shader, but it demonstrates + // how to read from a texture and constant buffer and write to a storage texture + + 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; + + // Write the output value to the storage texture + imageStore(texture_out, tex_coord, output_value); +} +``` + +### Komponent skryptu +```lua +-- In a .script file + +-- Here we specify the input texture that we later will bind to the +-- compute program. We can assign this texture to a model component, +-- or enable it to the render context in the render script. +go.property("texture_in", resource.texture()) + +function init(self) + -- Create a texture resource like usual, but add the "storage" flag + -- so it can be used as the backing storage for compute programs + 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 + } + + -- notify the renderer of the input and output textures + msg.post("@render:", "set_backing_texture", textures) +end +``` + +### Skrypt do renderowania +```lua +-- respond to the message "set_backing_texture" +-- to set the backing texture for the compute program +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") + -- We can bind textures to specific named constants + 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)) + -- Dispatch the compute program as many times as we have pixels. + -- This constitutes our "working group". The shader will be invoked + -- 128 x 128 x 1 times, or once per pixel. + render.dispatch_compute(128, 128, 1) + -- when we are done with the compute program, we need to unbind it + 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ć backendu 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..42083554 --- /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 odczytywać logi gry i systemu. +--- + +# Log gry i systemu + +Log gry (ang. game log) pokazuje całe wyjście z silnika, rozszerzeń natywnych i logiki gry. Funkcji [print()](/ref/stable/base/#print:...) oraz [pprint()](/ref/stable/builtins/?q=pprint#pprint:v) można używać w skryptach i modułach Lua, aby wyświetlać informacje w logu gry. Możesz też używać funkcji z przestrzeni nazw [`dmLog`](/ref/stable/dmLog/), aby zapisywać do logu gry z poziomu rozszerzeń natywnych. Log gry można odczytywać 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ą dostarczać dodatkowych informacji pomagających ustalić źródło problemu. Logi systemowe mogą zawierać ślady stosu po awariach oraz ostrzeżenia o małej ilości 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 [development app](/manuals/dev-app), całe wyjście będzie widoczne w panelu konsoli (console pane) 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 wyświetlania 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 wypisywanymi przez grę. + +Jeśli chcesz widzieć tylko 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 możliwości odczytywania logów gry i systemu w iOS: + +1. Możesz użyć narzędzia [Console](https://support.apple.com/guide/console/welcome/mac), aby odczytywać logi gry i systemu. +2. Możesz użyć debuggera LLDB, aby podłączyć się 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 w macOS). + +Aby uruchomić grę i podłą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 podłą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-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..967ee5c4 --- /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ć kompilację 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 + +* Zbundluj aplikację 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 nie używasz 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/). Wymagane jest tylko 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) + +* To jest 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, wykonywanie 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 (job folder) 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..d06dd52f --- /dev/null +++ b/docs/pl/manuals/debugging-native-code.md @@ -0,0 +1,161 @@ +--- +title: Debugowanie kodu natywnego w silniku Defold +brief: Ta instrukcja wyjaśnia, jak debugować kod natywny w silniku Defold. +--- + +# Debugowanie kodu natywnego + +Defold jest dobrze przetestowany i w normalnych warunkach bardzo rzadko powinien ulegać awarii. Nie da się jednak zagwarantować, że nigdy się nie zawiesi, zwłaszcza jeśli Twoja gra korzysta z rozszerzeń natywnych (ang. native extensions). Jeśli napotkasz problemy z awariami albo kod natywny nie zachowuje się zgodnie z oczekiwaniami, możesz obrać kilka różnych dróg: + +* Użyj debuggera, aby prześledzić kod krok po kroku +* Użyj debugowania za pomocą wydruków +* Przeanalizuj log awarii +* Zsymbolikuj stos wywołań + + +## Użyj debuggera + +Najczęstszym sposobem jest uruchomienie kodu przez `debugger`. Pozwala on przechodzić przez kod krok po kroku, ustawiać punkty przerwania (`breakpoints`) i zatrzyma wykonanie, jeśli dojdzie do awarii. + +Dla każdej platformy dostępnych jest kilka debuggerów. + +* 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 narzędzie 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 za pomocą wydruków + +Najprostszym sposobem debugowania kodu natywnego jest [debugowanie za pomocą wydruków](http://en.wikipedia.org/wiki/Debugging#Techniques). Użyj funkcji z przestrzeni nazw [`dmLog`](/ref/stable/dmLog/), aby śledzić zmienne albo wskazywać przebieg wykonania. Użycie dowolnej funkcji logującej 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 krytycznej 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 (miejsce to 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 podczas 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 swój 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. + + +## Zsymbolikuj stos wywołań + +Jeśli uzyskasz stos wywołań (ang. callstack) 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 dopasowanie właściwego silnika do danego 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 pole wyboru "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 dla każdego publicznego wydania gry zachować gdzieś symbole debugowe i wiedzieć, do którego wydania należą. Bez symboli debugowych nie da się debugować natywnych awarii. Dodatkowo warto przechowywać wersję silnika bez stripowania (unstripped). 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) tak, 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 z nazwami architektur, takimi 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 stack trace 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 pliku 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 +``` + + # Również bezpośrednie podanie adresu załadowania nie działa + +```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..aa5161db --- /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 umieścić development app na urządzeniu, aby iteracyjnie tworzyć i testować projekt bezpośrednio na nim. +--- + +# Development app na urządzeniu mobilnym + +Development app (aplikacja do tworzenia i testowania gry na urządzeniu) pozwala przesyłać do niej zawartość przez Wi-Fi. Znacznie skraca to czas iteracji, ponieważ nie trzeba za każdym razem tworzyć paczki aplikacji i jej instalować, gdy chcesz sprawdzić swoje zmiany. Instalujesz development app na urządzeniu lub urządzeniach, uruchamiasz aplikację, a następnie wybierasz urządzenie jako cel builda w edytorze. + +## Instalowanie development app + +Każda aplikacja na iOS lub Androida zbudowana w wariancie Debug może działać jako development app. Jest to wręcz zalecane rozwiązanie, ponieważ taka development app będzie miała poprawne ustawienia projektu i będzie używać 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. + +![bundle 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ć na urządzeniu iOS funkcję [Personal Hotspot](https://support.apple.com/en-us/HT204023) 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ć na urządzeniu funkcję Personal Hotspot 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ć na urządzeniu funkcję Personal Hotspot 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-scripts-ui.md b/docs/pl/manuals/editor-scripts-ui.md new file mode 100644 index 00000000..ac7312cb --- /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 interfejsu użytkownika (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, ale 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 Hello world](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 obiektami `userdata`** wykorzystywanymi 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 pewien 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` w `props`. + +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 stałe `small`, `medium` i `large` dla `padding` i `spacing`. W przypadku `spacing` 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 `padding` 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 (jeszcze niezaimplementowane). + +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, -- add padding around dialog edges + columns = {{}, {grow = true}}, -- make 2nd column grow + 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 np. 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 w razie potrzeby skrócony do `"..."`, jeśli nadal nie zmieści się w widoku. + +### 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ść](#reaktywność). + +Na przykład można tak utworzyć proste, statyczne okno dialogowe tworzenia nowego pliku: +```lua +-- initial file name, will be replaced by the dialog +local file_name = "" +local create_file = editor.ui.show_dialog(editor.ui.dialog({ + title = "Create New File", + content = editor.ui.horizontal({ + padding = editor.ui.PADDING.LARGE, + spacing = editor.ui.SPACING.MEDIUM, + children = { + editor.ui.label({ + text = "New File Name", + alignment = editor.ui.ALIGNMENT.CENTER + }), + editor.ui.string_field({ + grow = true, + text = file_name, + -- Typing callback: + on_value_changed = function(new_text) + file_name = new_text + end + }) + } + }), + buttons = { + editor.ui.dialog_button({ text = "Cancel", cancel = true, result = false }), + editor.ui.dialog_button({ text = "Create File", 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 opcji 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 (albo `editor.ui.ISSUE_SEVERITY.ERROR`, albo `editor.ui.ISSUE_SEVERITY.WARNING`), na przykład: +```lua +issue = {severity = editor.ui.ISSUE_SEVERITY.WARNING, message = "This value is deprecated"} +``` +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ę okien dialogowych 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 obiektami `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 hakach Reacta będzie pomocna. +::: + +Najprościej mówiąc, komponent reaktywny to komponent z funkcją Lua, która otrzymuje dane (`props`) i zwraca widok (inny komponent). Funkcja komponentu reaktywnego może używać haków: specjalnych funkcji w module `editor.ui`, które dodają komponentom cechy reaktywne. Zgodnie z konwencją wszystkie haki 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 is a reactive component +local dialog = editor.ui.component(function(props) + -- 2. the component defines a local state (file name) that defaults to empty string + 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. typing + Enter updates the local state + on_value_changed = set_name + }) + } + }), + buttons = { + editor.ui.dialog_button({ + text = "Cancel", + cancel = true + }), + editor.ui.dialog_button({ + text = "Create File", + -- 4. creation is enabled when the name exists + enabled = name ~= "", + default = true, + -- 5. result is the name + result = name + }) + } + }) +end) + +-- 6. show_dialog will either return non-empty file name or nil on cancel +local file_name = editor.ui.show_dialog(dialog({ title = "New File Name" })) +if file_name then + print("create " .. file_name) +else + print("cancelled") +end +``` + +Gdy uruchomisz polecenie menu wykonujące ten kod, edytor pokaże okno dialogowe z wyłączonym na początku przyciskiem dialogowym `"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 hak `use_state` tworzy lokalny stan powiązany z komponentem i zwraca go razem z setterem tego stanu. Gdy funkcja settera zostaje 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 i jak często funkcja komponentu zostanie wywołana. Wszystkie efekty uboczne powinny znajdować się poza renderowaniem, np. w callbackach +2. Propsy 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 haki w tej samej kolejności przy każdym wywołaniu. Nie wywołuj haków wewnątrz pętli, w blokach warunkowych, po wcześniejszych `return` itd. Dobrą praktyką jest wywoływanie haków na początku funkcji komponentu, przed jakimkolwiek innym kodem. +4. Wywołuj haki tylko z funkcji komponentów. Haki działają w kontekście komponentu reaktywnego, dlatego wolno je wywoływać wyłącznie w funkcji komponentu (albo innej funkcji wywoływanej bezpośrednio przez funkcję komponentu). + +### Haki + +::: sidenote +Jeśli znasz [React](https://react.dev/), zauważysz, że haki w edytorze mają nieco inną semantykę, jeśli chodzi o zależności haków. +::: + +Edytor definiuje 2 haki: **`use_memo`** i **`use_state`**. + +### **`use_state`** + +Stan lokalny można utworzyć na 2 sposoby: z wartością domyślną albo z funkcją inicjalizującą: +```lua +-- default value +local enabled, set_enabled = editor.ui.use_state(true) +-- initializer function + args +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 +-- updater function +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 +-- ❌ BAD: literal table initializer causes state reset on every re-render +local user, set_user = editor.ui.use_state({ first_name = props.first_name, last_name = props.last_name}) + +-- ✅ GOOD: use initializer function outside of component function to create table state +local function create_user(first_name, last_name) + return { first_name = first_name, last_name = last_name} +end +-- ...later, in component function: +local user, set_user = editor.ui.use_state(create_user, props.first_name, props.last_name) + + +-- ❌ BAD: literal initializer function causes state reset on every re-render +local id, set_id = editor.ui.use_state(function() return string.lower(props.name) end) + +-- ✅ GOOD: use referenced initializer function to create the state +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. Hak `use_memo` przydaje się 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 +-- validation function outside of component function +local function validate_password(password) + if #password < 8 then + return false, "Password must be at least 8 characters long." + elseif not password:match("%l") then + return false, "Password must include at least one lowercase letter." + elseif not password:match("%u") then + return false, "Password must include at least one uppercase letter." + elseif not password:match("%d") then + return false, "Password must include at least one number." + else + return true, "Password is valid." + end +end + +-- ...later, in component function +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 (np. podczas wpisywania w polu hasła), ale nie wtedy, gdy zmieni się nazwa użytkownika. + +Innym zastosowaniem `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ść w `props` innego komponentu; zapobiega to niepotrzebnym ponownym renderowaniom. 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..d5c6d40f --- /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 + +Lokalny serwer budowania (ang. build server, znany też jako Extender) można uruchomić na dwa sposoby: +1. Uruchomić lokalny serwer budowania ze wstępnie skonfigurowanymi artefaktami. +2. Uruchomić lokalny serwer 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ć chmurowe serwery budowania na lokalnej 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 serwerami budowania dla poszczególnych platform. + +Gdy zainstalujesz powyższe oprogramowanie, 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 użytkowanie i tymczasowo zawieszać konta, które pobierają obrazy w nadmiernej liczbie. + + ```sh + gcloud auth login + ``` +2. __Skonfiguruj Docker do używania rejestrów 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, prawie wszystko jest gotowe 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 narzędzia 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 "Download prebuild jars to ${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 + zdalne instancje do budowania wersji na Androida +* **web** - uruchamia instancję frontendu + zdalne instancje do budowania wersji Web +* **linux** - uruchamia instancję frontendu + zdalne instancje do budowania wersji Linux +* **windows** - uruchamia instancję frontendu + zdalne instancje do budowania wersji Windows +* **consoles** - uruchamia instancję frontendu + zdalne instancje do budowania wersji na Nintendo Switch/PS4/PS5 +* **nintendo** - uruchamia instancję frontendu + zdalne instancje do budowania wersji na Nintendo Switch +* **playstation** - uruchamia instancję frontendu + zdalne instancje do budowania wersji na PS4/PS5 +* **metrics** - uruchamia VictoriaMetrics + Grafana jako backend metryk i 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 w ustawieniu `Build Server` w preferencjach edytora albo jako wartości `--build-server`, jeśli do budowania projektu używasz narzędzia Bob. + +W wierszu poleceń 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 bez odłączenia od terminala, albo +```sh +docker compose -p extender down +``` +jeśli `docker compose` uruchomiono w trybie odłączonym (na przykład przekazano 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ć 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 rzeczywistym 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..936198ff --- /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 może być trudne, ale istnieją sposoby, aby ułatwić zarówno jego tworzenie, jak i utrzymanie. + + +## Struktura projektu + +Podczas tworzenia rozszerzenia warto zadbać o kilka rzeczy, które pomagają zarówno przy jego rozwijaniu, jak i późniejszym utrzymaniu. + +### API Lua + +Powinno istnieć tylko jedno API Lua i jedna jego implementacja. Dzięki temu znacznie łatwiej zachować 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żesz wykryć obsługę, sprawdzając `nil`: + +```lua + if myextension ~= nil then + myextension.do_something() + end +``` + +### Struktura folderów + +Poniższa struktura folderów jest często używana w rozszerzeniach: + +``` + /root + /input + /main -- All the files for the actual example project + /... + /myextension -- The actual root folder of the extension + ext.manifest + /include -- External includes, used by other extensions + /libs + / -- External libraries for all supported platforms + /src + myextension.cpp -- The extension Lua api and the extension life cycle functions + Also contains generic implementations of your Lua api functions. + myextension_private.h -- Your internal api that each platform will implement (I.e. `myextension_Init` etc) + myextension.mm -- If native calls are needed for iOS/macOS. Implements `myextension_Init` etc for iOS/macOS + myextension_android.cpp -- If JNI calls are needed for Android. Implements `myextension_Init` etc for Android + /java + / -- Any java files needed for Android + /res -- Any resources needed for a platform + /external + README.md -- Notes/scripts on how to build or package any external libraries + /bundleres -- Resources that should be bundles for (see game.project and the [bundle_resources setting]([physics scale setting](/manuals/project-settings/#project)) + / + game.project + game.appmanifest -- Any extra app configuration info +``` + +Pamiętaj, że `myextension.mm` i `myextension_android.cpp` są potrzebne tylko wtedy, gdy wykonujesz natywne wywołania specyficzne 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/dołączania aplikacji do bundla. 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 i większość kodu ma charakter zbliżony do C. Szablony praktycznie nie występują, 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++ dla każdego kompilatora. Sam kod źródłowy Defold nie używa wersji C++ wyższej niż C++98. Chociaż można użyć nowszej wersji do zbudowania rozszerzenia, może się to wiązać ze zmianami ABI. Może to uniemożliwić używanie jednego rozszerzenia razem z 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 nowe funkcje nie są konieczne, ale też dlatego, że śledzenie najnowszych możliwości C++ jest czasochłonne, a ich pełne opanowanie wymaga dużo cennego czasu. + +Daje to również dodatkową korzyść twórcom rozszerzeń, ponieważ Defold utrzymuje stabilne ABI. Warto też podkreślić, że używanie najnowszych funkcji C++ może uniemożliwić kompilację kodu na różnych platformach z powodu różnic w poziomie wsparcia. + +### Bez wyjątków C++ + +Defold nie używa wyjątków w silniku. Wyjątków z reguły unika się w silnikach gier, ponieważ dane są w większości znane z góry, już 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 być dla ciebie dopuszczalne. + +Pamiętaj jednak, że niezgodności ABI mogą utrudnić używanie twojego rozszerzenia razem z innymi rozszerzeniami lub bibliotekami firm trzecich. + +Unikanie bibliotek STL (silnie opartych na szablonach) poprawia także czasy budowania, a co ważniejsze, zmniejsza rozmiar pliku wykonywalnego. + +#### Ciągi znaków + +W silniku Defold używa się `const char*` zamiast `std::string`. Używanie `std::string` jest częstą pułapką przy mieszaniu różnych wersji C++ lub 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 dla danej jednostki kompilacji. Pozwala to kompilatorowi wykonać pewne optymalizacje, co może zarówno poprawić wydajność, jak i zmniejszyć rozmiar pliku wykonywalnego. + +## Biblioteki firm trzecich + +Wybierając bibliotekę firmy trzeciej 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ś w GitHub, nic nie stoi na przeszkodzie, aby dane 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..90b4e3f6 --- /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 oraz to, jak odnosi się on do manifestu aplikacji i manifestu silnika. +--- + +# Pliki manifestów rozszerzenia, aplikacji i silnika + +Manifest rozszerzenia to plik konfiguracyjny zawierający flagi i definicje używane podczas budowania pojedynczego rozszerzenia. Ta konfiguracja jest łączona z konfiguracją na poziomie aplikacji oraz konfiguracją bazową samego silnika Defold. + +## Manifest aplikacji + +Manifest aplikacji (z rozszerzeniem pliku `.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 builda (`build.yml`), który jest dołączany do każdej wersji silnika i pakietu Defold SDK. Manifest kontroluje, których wersji SDK używać, jakie kompilatory, linkery i inne narzędzia uruchamiać 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 danego rozszerzenia. Manifest rozszerzenia kontroluje sposób kompilacji i linkowania kodu źródłowego rozszerzenia oraz określa, 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 Defold: + + 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 paczkę, nadal zostanie zbudowana, 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. Ma to zapobiegać nieprawidłowej obsłudze ścieżek i dostępowi 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..c370e35d --- /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ć część `AndroidManifest.xml`, `Info.plist` albo `engine_template.html`. + +Każdy fragment manifestu rozszerzenia będzie stosowany jeden po drugim, zaczynając od bazowego manifestu aplikacji. +Manifest bazowy jest albo domyślny (w `builtins\manifests\\...`), albo niestandardowy, dostarczony 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 scalania manifestów. +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 nazwaliś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..fb64291e --- /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ł podpowiadać 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 udostępniać 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 następująco: + +```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: + +* [Rozszerzenie Facebook](https://github.com/defold/extension-facebook/tree/master/facebook/api) +* [Rozszerzenie WebView](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..47704899 --- /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 chmurowego serwera buildów bez konfiguracji. +--- + +# Rozszerzenia natywne + +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 telefonach komórkowych. +- Integracja z zewnętrznymi niskopoziomowymi API, na przykład z API sieci reklamowych, które nie pozwalają na komunikację przez sieć w sposób, w jaki można by użyć Luasocket. +- Obliczenia o wysokiej wydajności i przetwarzanie danych. + +## Serwer buildów + +Defold udostępnia możliwość korzystania z natywnych rozszerzeń bez konfiguracji dzięki chmurowemu systemowi budowania. Każde natywne rozszerzenie, które zostanie dodane do projektu gry, bezpośrednio lub przez [projekt biblioteki](/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 specyficzny dla projektu plik wykonywalny silnika ze wszystkimi natywnymi rozszerzeniami wbudowanymi na stałe. + +![Budowanie w chmurze](images/extensions/cloud_build.png) + +Defold udostępnia serwer buildów 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, dodaj 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 buildów 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 +# C++ symbol in your extension +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 +// Extension lib defines +#define LIB_NAME "MyExtension" +#define MODULE_NAME "myextension" + +// include the Defold SDK +#include + +static int Reverse(lua_State* L) +{ + // The number of expected items to be on the Lua stack + // once this struct goes out of scope + DM_LUA_STACK_CHECK(L, 1); + + // Check and get parameter string from stack + char* str = (char*)luaL_checkstring(L, 1); + + // Reverse the string + 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; + } + + // Put the reverse string on the stack + lua_pushstring(L, str); + + // Return 1 item + return 1; +} + +// Functions exposed to Lua +static const luaL_reg Module_methods[] = +{ + {"reverse", Reverse}, + {0, 0} +}; + +static void LuaInit(lua_State* L) +{ + int top = lua_gettop(L); + + // Register lua names + 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) +{ + // Init 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 uses a macro for setting up extension entry points: +// +// DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final) + +// MyExtension is the C++ symbol that holds all relevant extension data. +// It must match the name field in the `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 buildów, który wygeneruje własny silnik z nowym rozszerzeniem wbudowanym na stałe. Jeśli serwer buildów 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: + +* Uruchamianie 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 buildów 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 buildów + +Dzienniki serwera buildów są dostępne, gdy projekt korzysta z natywnych rozszerzeń. Dziennik serwera buildów (`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ń + +* [Przykład podstawowego 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/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/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..3fffdff4 --- /dev/null +++ b/docs/pl/manuals/graphics.md @@ -0,0 +1,12 @@ +--- +title: Podręcznik grafiki w silniku Defold +brief: Ten podręcznik opisuje obsługę elementów graficznych w Defold. +--- + +# Grafika + +Ten podręcznik jest przestarzały. + +* Przeczytaj więcej o [importowaniu i używaniu 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/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..9320835a --- /dev/null +++ b/docs/pl/manuals/html5.md @@ -0,0 +1,334 @@ +--- +title: Tworzenie gier HTML5 +brief: Ta instrukcja opisuje proces tworzenia gry HTML5 wraz ze znanymi problemami i ograniczeniami. +--- + +# Tworzenie gier HTML5 + +Defold obsługuje tworzenie 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 bundel HTML5 (zobacz poniżej). + +## Testowanie buildu HTML5 + +Do testowania bundla 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 bundle, po prostu wgraj go na zdalny serwer HTTP albo utwórz lokalny serwer, na przykład używając Pythona w folderze bundla. +Python 2: + +```sh +python -m SimpleHTTPServer +``` + +Python 3: + +```sh +python -m http.server +``` + +lub + +```sh +python3 -m http.server +``` + +::: important +Nie możesz przetestować bundla 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 bundla 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.... + +![Create HTML5 bundle](images/html5/html5_bundle.png) + +Możesz zdecydować, czy chcesz dołączyć do bundla 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 + +* 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. + * Full screen - tryb pełnoekranowy jest w przeglądarce zawodny. +* Chrome + * 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`. +* Gamepad support - [Dokumentacja Gamepad](/manuals/input-gamepads/#gamepads-in-html5) zawiera szczególne uwagi i kroki, które mogą być potrzebne w HTML5. + +## Dostosowywanie bundla 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*: + +![HTML5 Section](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. + +![HTML5 Section](images/html5/html5_fit.png) + +### Stretch + +W trybie `Stretch` rozmiar canvasu zostanie zmieniony tak, aby całkowicie wypełnić wewnętrzny rozmiar strony WWW. + +![HTML5 Section](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]`. + +![HTML5 Section](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 bundla 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`: + +![Display section](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}}}`. + +![Display section](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 umieszcza się inline zawartość pliku CSS określonego w ustawieniach *game.project*. + + +```html + +``` + +::: important +Ważne jest, aby ten blok inline 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ć na nowo 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, gdy silnik jest konfigurowany i wczytywany. 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`: + + +``` +