diff --git a/docs/.vitepress/config/index.ts b/docs/.vitepress/config/index.ts index 0a55fb5c3..19c13a75e 100644 --- a/docs/.vitepress/config/index.ts +++ b/docs/.vitepress/config/index.ts @@ -1,7 +1,8 @@ -import { defineConfig } from 'vitepress' -import { enConfig } from './en' -import { esConfig } from './es' -import { sharedConfig } from './shared' +import { defineConfig } from "vitepress"; +import { enConfig } from "./en"; +import { esConfig } from "./es"; +import { plConfig } from "./es"; +import { sharedConfig } from "./shared"; /* import { zhConfig } from './zh' */ @@ -9,8 +10,9 @@ export default defineConfig({ ...sharedConfig, locales: { - root: { label: 'English', lang: 'en-US', link: '/', ...enConfig }, - es: { label: 'Español', lang: 'es-ES', link: '/es/', ...esConfig }, + root: { label: "English", lang: "en-US", link: "/", ...enConfig }, + es: { label: "Español", lang: "es-ES", link: "/es/", ...esConfig }, + pl: { label: "Polish", lang: "pl-PL", link: "/pl/", ...plConfig }, /* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */ }, -}) \ No newline at end of file +}); diff --git a/docs/.vitepress/config/pl.ts b/docs/.vitepress/config/pl.ts new file mode 100644 index 000000000..8ba0eb247 --- /dev/null +++ b/docs/.vitepress/config/pl.ts @@ -0,0 +1,153 @@ +import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; + +export const plConfig: LocaleSpecificConfig = { + themeConfig: { + editLink: { + pattern: "https://github.com/tresjs/tres/edit/main/packages/docs/:path", + text: "Zaproponuj zmiany na tej stronie", + }, + sidebar: [ + { + text: "Przewodnik", + items: [ + // Esto muestra la página `/guide/index.md`. + { text: "Wstęp", link: "/pl/guide/" }, + { text: "Pierwsze kroki", link: "/pl/guide/getting-started" }, + { text: "Twoja pierwsza scena", link: "/pl/guide/your-first-scene" }, + { text: "Nuxt", link: "/pl/guide/nuxt" }, + { + text: "Rozwiązywanie problemów", + link: "/pl/guide/troubleshooting", + }, + { text: "Migracja z v1", link: "/pl/guide/migration-guide" }, + ], + }, + { + text: "API", + items: [ + { text: "TresCanvas", link: "/pl/api/tres-canvas" }, + { + text: "Instancje, argumenty i właściwości", + link: "/pl/api/instances-arguments-and-props", + }, + { + text: "Komponowalne", + link: "/pl/api/composables", + }, + { + text: "Wydarzenia", + link: "/pl/api/events", + }, + ], + }, + + { + text: "Zaawansowany", + + items: [ + { text: "Rozszerzanie", link: "/pl/advanced/extending" }, + { text: "Prymitywny", link: "/pl/advanced/primitive" }, + { + text: "Zastrzeżenia", + link: "/pl/advanced/caveats", + }, + ], + }, + { + text: "Znajdowanie", + items: [ + { text: "Narzędzia deweloperskie", link: "/pl/debug/devtools" }, + ], + }, + { + text: "Książka kucharska 🍳🧑‍🍳", + collapsed: true, + items: [ + { text: "Sterowanie orbitą", link: "/pl/cookbook/orbit-controls" }, + { + text: "Podstawowe animacje", + link: "/pl/cookbook/basic-animations", + }, + { text: "Grupy", link: "/pl/cookbook/groups" }, + { text: "Ładowanie tekstur", link: "/pl/cookbook/load-textures" }, + { text: "Ładowanie modelu", link: "/pl/cookbook/load-models" }, + { text: "Ładowanie tekstu", link: "/pl/cookbook/text-3d" }, + { text: "Światła i cienie", link: "/pl/cookbook/lights-shadows" }, + { text: "Shadery", link: "/pl/cookbook/shaders" }, + ], + }, + { + text: "Dyrektywy", + collapsed: true, + items: [ + { text: "v-log", link: "/pl/directives/v-log" }, + { text: "v-light-helper", link: "/pl/directives/v-light-helper" }, + { text: "v-always-look-at", link: "/pl/directives/v-always-look-at" }, + { text: "v-distance-to", link: "/pl/directives/v-distance-to" }, + ], + }, + { + text: "Ekosystem", + items: [ + { + text: "Cientos 💛", + link: "https://cientos.tresjs.org/", + }, + { + text: "Nuxt module", + link: "https://github.com/Tresjs/nuxt", + }, + { + text: "TresLeches 🍰", + link: "https://tresleches.tresjs.org/", + }, + { + text: "Post-processing (wkrótce)", + }, + ], + }, + ], + nav: [ + { text: "Przewodnik", link: "/pl/guide/" }, + { text: "API", link: "/pl/api/tres-canvas" }, + /* { text: 'API', link: '/pl/api/' }, + { text: 'Konfiguracja', link: '/pl/config/' }, */ + { + text: "Zasoby", + items: [ + { text: "Zespół", link: "/pl/team" }, + { text: "Wydania", link: "https://github.com/Tresjs/tres/releases" }, + { + text: "Plac zabaw", + link: "https://playground.tresjs.org/", + }, + { + text: "Github", + link: "https://github.com/Tresjs/tres/", + }, + { + text: "Problemy", + link: "https://github.com/Tresjs/tres/issues", + }, + { + text: "Ekosystem", + items: [ + { + text: "Cientos 💛", + link: "https://cientos.tresjs.org/", + }, + { + text: "Módulo Nuxt", + link: "https://github.com/Tresjs/nuxt", + }, + { + text: "TresLeches 🍰", + link: "https://tresleches.tresjs.org/", + }, + ], + }, + ], + }, + ], + }, +}; diff --git a/docs/es/examples/load-textures.md b/docs/es/examples/load-textures.md index 888e52936..c20808927 100644 --- a/docs/es/examples/load-textures.md +++ b/docs/es/examples/load-textures.md @@ -15,10 +15,10 @@ El composable `useLoader` te permite pasar cualquier tipo de cargador de three.j Para obtener una explicación detallada de cómo usar `useLoader`, consulta la documentación de [useLoader](/api/composables#use-loader). ```ts -import { useLoader } from '@tresjs/core' -import { TextureLoader } from 'three' +import { useLoader } from "@tresjs/core"; +import { TextureLoader } from "three"; -const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg') +const texture = useLoader(TextureLoader, "/Rock035_2K_Color.jpg"); ``` Luego puedes pasar la textura a un material: @@ -43,20 +43,19 @@ Una forma más conveniente de cargar texturas es utilizando el composable `useTe Para obtener más información sobre `useTexture`, consulta la documentación de [useTexture](/api/composables#use-texture). ```ts -import { useTexture } from '@tresjs/core' +import { useTexture } from "@tresjs/core"; const pbrTexture = await useTexture({ - map: '/textures/black-rock/Rock035_2K_Displacement.jpg', - displacementMap: '/textures/black-rock/Rock035_2K_Displacement.jpg', - roughnessMap: '/textures/black-rock/Rock035_2K_Roughness.jpg', - normalMap: '/textures/black-rock/Rock035_2K_NormalDX.jpg', - aoMap: '/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg', - metalnessMap: '/textures/black-rock/myMetalnessTexture.jpg', - matcap: '/textures/black-rock/myMatcapTexture.jpg', - alphaMap: '/textures/black-rock/myAlphaMapTexture.jpg' -}) + map: "/textures/black-rock/Rock035_2K_Displacement.jpg", + displacementMap: "/textures/black-rock/Rock035_2K_Displacement.jpg", + roughnessMap: "/textures/black-rock/Rock035_2K_Roughness.jpg", + normalMap: "/textures/black-rock/Rock035_2K_NormalDX.jpg", + aoMap: "/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg", + metalnessMap: "/textures/black-rock/myMetalnessTexture.jpg", + matcap: "/textures/black-rock/myMatcapTexture.jpg", + alphaMap: "/textures/black-rock/myAlphaMapTexture.jpg", +}); ``` -Similar to the previous example, we can pass all the textures to a material via props: Al igual que en el ejemplo anterior, podemos pasar todas las texturas a un material a través de props: diff --git a/docs/guide/index.md b/docs/guide/index.md index 37bb6f63c..268af95bb 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -9,15 +9,15 @@ ::: code-group ```bash [npm] -npm install @tresjs/core three +npm install @tresjs/core three ``` ```bash [yarn] -yarn add @tresjs/core three +yarn add @tresjs/core three ``` ```bash [pnpm] -pnpm add @tresjs/core three +pnpm add @tresjs/core three ``` ::: @@ -59,7 +59,7 @@ export default defineConfig({ }), ``` -This is required to make the template compiler work with the custom renderer and not throw warnings on the console. For more info check [here](/guide/troubleshooting.html). +This is required to make the template compiler work with the custom renderer and not throw warnings on the console. For more info check [here](/es/guide/troubleshooting.html). ## Try it online @@ -95,20 +95,19 @@ The only problem is, mixing compilers renderers in Vue 3 is something the Vue co ```ts // Example Vite setup -import { createApp } from 'vue' -import { createApp as createLunchboxApp } from 'lunchboxjs' -import App from './App.vue' -import LunchboxApp from './LunchboxApp.vue' +import { createApp } from "vue"; +import { createApp as createLunchboxApp } from "lunchboxjs"; +import App from "./App.vue"; +import LunchboxApp from "./LunchboxApp.vue"; // html app -const app = createApp(App) -app.mount('#app') +const app = createApp(App); +app.mount("#app"); // lunchbox app -const lunchboxApp = createLunchboxApp(LunchboxApp) +const lunchboxApp = createLunchboxApp(LunchboxApp); // assuming there's an element with ID `lunchbox` in your HTML app -lunchboxApp.mount('#lunchbox') +lunchboxApp.mount("#lunchbox"); ``` So I was inspired by both libraries to create a Vue custom renderer for ThreeJS. That's **TresJS v2**. - diff --git a/docs/pl/advanced/caveats.md b/docs/pl/advanced/caveats.md new file mode 100644 index 000000000..cecbccf4b --- /dev/null +++ b/docs/pl/advanced/caveats.md @@ -0,0 +1,109 @@ +# Ostrzeżenia 😱 + +Naszym celem jest dostarczenie prostego sposobu korzystania z ThreeJS w VueJS z najlepszym możliwym doświadczeniem programistycznym. Niemniej jednak istnieją pewne ostrzeżenia, o których powinieneś być świadomy. + +## ~~HMR y ThreeJS~~ + +:::info + +To zostało rozwiązane w **TresJS** v1.7.0 🎉. Teraz możesz używać HMR bez konieczności przeładowywania strony 🥹. + +::: + +Hot Module Replacement (HMR) to funkcja, która pozwala na aktualizowanie kodu bez ponownego ładowania strony. To świetna cecha, która znacznie przyspiesza proces developmentu. **TresJS** korzysta z [Vite](https://vitejs.dev/). Jednakże, jest to naprawdę skomplikowane, aby zadziałało poprawnie z ThreeJS. + +Dlaczego? Ponieważ Tres buduje scenę deklaratywnie. Oznacza to, że tworzy instancję i dodaje ją do sceny podczas montowania komponentu. Złożoność polega na tym, kiedy usunąć instancję ze sceny i kiedy ponownie ją dodać. + +Chociaż został zaimplementowany minimalny proces usuwania, nie jest on idealny. Oznacza to, że czasami będziesz musiał przeładować stronę, aby zobaczyć zmiany poprawnie, zwłaszcza gdy odwołujesz się do instancji za pomocą [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html) + +```vue + + + +``` + +Jeśli dokonasz zmiany w `color` materiału `TresMeshStandardMaterial`, zauważysz, że zmiana ta zostanie zastosowana, ale rotacja już nie będzie działać. Dzieje się tak, ponieważ instancja jest usuwana i tworzona od nowa. + +:::tip +Więc, jako **regla general**, powinieneś przeładować stronę, gdy nie widzisz dokonanych zmian. +::: + +Mówiąc to, pracujemy nad lepszym rozwiązaniem na to 😁. Jeśli masz jakieś pomysły, jak to rozwiązać, daj nam znać. + +Możesz śledzić dyskusję na [HMR Disposal Discussion](https://github.com/Tresjs/tres/issues/23) + +## Reaktywność + +Wszyscy kochamy reaktywność 💚. Jest to jedna z najpotężniejszych cech VueJS. Jednak musimy być ostrożni podczas korzystania z ThreeJS. + +Reaktywność Vue opiera się na [Proxy](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Pozwala to Vue 3 śledzić automatycznie zmiany w obiektach danych i aktualizować odpowiednie elementy DOM za każdym razem, gdy dane się zmienią. + +Ponieważ renderujemy scenę i aktualizujemy ją w każdej klatce (60FPS), oznacza to, że aktualizujemy scenę 60 razy na sekundę. Jeśli obiekt do aktualizacji jest reaktywny, Vue spróbuje zaktualizować ten obiekt tyle razy. To nie jest dobry pomysł 😅 i będzie miało negatywny wpływ na wydajność. + +Oto test wydajności różnicy między użyciem obiektu Proxy a obiektem płaskim. + +
+ Proxy vs Plain +
Fig.1 - Ejecuciones por segundo Objeto Plano vs Proxy.
+
+ +Źródło: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter) + +Jeśli jesteś zmuszony do użycia reaktywności, użyj [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref) + +W przeciwieństwie do `ref()`, wewnętrzna wartość shallow ref jest przechowywana i ujawniana dokładnie tak, jak jest, i nie zachodzi reaktywność w głąb. Tylko dostęp do `.value` jest reaktywny. Źródło: [VueJS Docs](https://vuejs.org/api/reactivity-advanced.html#shallowref) + +### Przykład + +❌ Niepoprawne + +```vue + + + +``` + +✅ Poprawne + +```vue + + + +``` diff --git a/docs/pl/advanced/extending.md b/docs/pl/advanced/extending.md new file mode 100644 index 000000000..c6f49b143 --- /dev/null +++ b/docs/pl/advanced/extending.md @@ -0,0 +1,38 @@ +# Rozszerzania 🔌 + +Tres oferuje podstawową funkcjonalność, ale łatwo można dodać elementy zewnętrzne i rozszerzyć je do wewnętrznego katalogu. + +Większość doświadczeń 3D wykorzystuje `OrbitControls`, który nie jest częścią biblioteki głównej. Możesz dodać go do swojego projektu, importując go z modułu `three/addons/controls/OrbitControls`. + +```js +import { OrbitControls } from "three/addons/controls/OrbitControls"; +``` + +## Dynamiczne rozszerzanie elementu + +Możesz również dodawać go dynamicznie w swoich komponentach: + +```vue {2,3,4,7,13,15} + + + +``` diff --git a/docs/pl/advanced/primitive.md b/docs/pl/advanced/primitive.md new file mode 100644 index 000000000..294e0af1c --- /dev/null +++ b/docs/pl/advanced/primitive.md @@ -0,0 +1,47 @@ +# Prymitywy + +Komponent `` to wszechstronny, niskopoziomowy komponent w TresJS, który pozwala bezpośrednio używać dowolnego obiektu three.js w ramach Twojej aplikacji Vue bez abstrakcji. Działa jako most między systemem reaktywności Vue a grafem sceny three.js. + +## Użycie + +```html + + + +``` + +## Props + +`object`: Ten prop oczekuje obiektu three.js typu `Object3D` lub dowolnej z jego klas pochodnych. To główny obiekt, który komponent `` będzie renderować. W zaktualizowanym przykładzie do tego propa przekazywany jest obiekt `Mesh` z powiązanym `Material`. + +## Użycie z Modelami + +Komponent `` jest szczególnie przydatny do renderowania skomplikowanych obiektów, takich jak modele wczytywane z zewnętrznych źródeł. Poniższy przykład pokazuje, jak wczytać model z pliku GLTF i renderować go przy użyciu komponentu ``. + +```html + + + + + + + +``` diff --git a/docs/pl/api/composables.md b/docs/pl/api/composables.md new file mode 100644 index 000000000..a6e330464 --- /dev/null +++ b/docs/pl/api/composables.md @@ -0,0 +1,245 @@ +# Composables + +Vue 3 [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html#what-is-composition-api) pozwala na tworzenie wielokrotnie używalnej logiki, którą można udostępniać między komponentami. Pozwala również na tworzenie niestandardowych haków, które można używać w komponentach. + +**TresJS** w pełni korzysta z tego interfejsu API, aby stworzyć zestaw komponowalnych funkcji, które można wykorzystać do tworzenia animacji, interakcji ze sceną i więcej. Pozwala również na tworzenie bardziej skomplikowanych scen, które mogą nie być możliwe tylko przy użyciu komponentów Vue (tekstury, ładowarki, itp.). + +Jądro **TresJS** używa tych komponowalnych elementów wewnętrznie, więc korzystasz z tego samego interfejsu API, którego używa jądro. Na przykład, komponenty, które wymagają aktualizacji wewnętrznej pętli renderowania, używają komponowalnego elementu useRenderLoop do zarejestrowania zwrotu, który zostanie wywołany za każdym razem, gdy renderer zaktualizuje scenę + +## useRenderLoop + +Komponowalny element `useRenderLoop` stanowi rdzeń animacji w **TresJS**. Pozwala na zarejestrowanie zwrotu, który będzie wywoływany przy naturalnej częstotliwości odświeżania. To najważniejszy komponowalny element w**TresJS**. + +```ts +const { onLoop, resume } = useRenderLoop(); + +onLoop(({ delta, elapsed, clock, dt }) => { + // I will run at every frame ~60FPS (depending of your monitor) +}); +``` + +::: ostrzeżenie +Miej na uwadze konsekwencje wydajnościowe przy korzystaniu z tego komponowalnego elementu. Będzie on wykonywany w każdej klatce, więc jeśli masz dużo logiki w swoim zwrocie, może to wpłynąć na wydajność twojej aplikacji. Szczególnie, jeśli aktualizujesz stany lub referencje reaktywne. +::: + +Zwrot `onLoop` otrzymuje obiekt z następującymi właściwościami opartymi na [zegarze THREE](https://threejs.org/docs/?q=clock#api/en/core/Clock): + +- `delta`: Czas, który upłynął między bieżącą klatką a poprzednią. Jest to czas w sekundach od ostatniej klatki. +- `elapsed`: Czas, który upłynął od rozpoczęcia pętli renderowania. + +Ten komponowalny element opiera się na `useRafFn` z [vueuse](https://vueuse.org/core/useRafFn/). Dzięki [@wheatjs](https://github.com/orgs/Tresjs/people/wheatjs) za niesamowity wkład. + +### Przed i po renderowaniu + +Możesz również zarejestrować zwrot, który zostanie wywołany przed i po tym, jak renderownik zaktualizuje scenę. Jest to przydatne na przykład, gdy dodajesz profilator do pomiaru liczby klatek na sekundę (FPS). + +```ts +const { onBeforeLoop, onAfterLoop } = useRenderLoop(); + +onBeforeLoop(({ delta, elapsed }) => { + // Se ejecutara antes del renderizado de la escena + fps.begin(); +}); + +onAfterLoop(({ delta, elapsed }) => { + // Se ejecutara después del renderizado de la escena + fps.end(); +}); +``` + +### Pauzowanie i wznowienie + +Możesz wstrzymać i wznowić pętlę renderowania, korzystając z udostępnionych metod `pause` i `resume`. + +```ts +const { pause, resume } = useRenderLoop(); + +// Pausa el bucle de renderizado +pause(); + +// Reanuda el bucle de renderizado +resume(); +``` + +Także możesz uzyskać aktualny stan pętli renderowania, korzystając z właściwości `isActive`. + +```ts +const { resume, isActive } = useRenderLoop(); + +console.log(isActive); // false + +resume(); + +console.log(isActive); // true +``` + +## useLoader + +Kompozycja `useLoader` umożliwia ładowanie zasobów przy użyciu [ładowaczy THREE.js](https://threejs.org/docs/#manual/en/introduction/Loading-3D-models). Zwraca promise z załadowanym zasobem. + +```ts +import { GLTFLoader } from "three/addons/loaders/GLTFLoader"; + +const { scene } = await useLoader(THREE.GLTFLoader, "path/to/asset.gltf"); +``` + +Ponieważ kompozycja `useLoader` zwraca promise, możesz jej używać z `async/await` lub `then/catch`. . Jeśli używasz jej w komponencie, upewnij się, że otaczasz ją komponentem `Suspense`. Zobacz [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) po więcej informacji. + +```vue + +``` + +## useTexture + +Kompozycja `useTexture`umożliwia ładowanie tekstur przy użyciu [THREE.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader). Zwraca promise z załadowaną texturą lub texturami. + +```ts +const texture = await useTexture(["path/to/texture.png"]); +``` + +**useTexture** akceptuje również obiekt z następującymi właściwościami: + +- `map`: podstawowa tekstura stosowana na powierzchni obiektu +- `displacementMap`: tekstura używana do dodawania wypukłości lub wgłębień na powierzchni obiektu +- `normalMap`: tekstura używana do dodawania szczegółów powierzchni i wariacji w cieniowaniu obiektu +- `roughnessMap`: tekstura używana do dodawania chropowatości lub matowego wykończenia na powierzchni obiektu +- `metalnessMap`: tekstura używana do dodawania efektu metalicznego na powierzchni obiektu +- `aoMap`: tekstura używana do dodawania oksluzji otoczenia (cieniowanie w obszarach, gdzie światło jest blokowane przez inne obiekty) do obiektu. +- `alphaMap`: tekstura używana do dodawania przejrzystości (czarna część renderowana jako przeźroczysta) do obiektu. Konieczne jest ustawienie :transparent="true" w materiale, aby używać tej mapy. +- `matcap`: ta tekstura koduje kolor i cieniowanie materiału. + +W takim przypadku zostanie zwrócony obiekt z załadowanymi teksturami. + +```ts +const { + map, + displacementMap, + normalMap, + roughnessMap, + metalnessMap, + aoMap, + alphaMap, + matcap, +} = await useTexture({ + map: "path/to/albedo.png", + displacementMap: "path/to/height.png", + normalMap: "path/to/normal.png", + roughnessMap: "path/to/roughness.png", + metalnessMap: "path/to/metalness.png", + aoMap: "path/to/ambien-occlusion.png", + alphaMap: "path/to/alpha.png", + matcap: "path/to/matcap.png", +}); +``` + +Następnie możesz przypisać tekstury do materiału. + +```vue + +``` + +Podobnie jak poprzednia kompozycja, kompozycja `useTexture` zwraca obietnicę. Możesz jej używać z `async/await` lub `then/catch`. Jeśli używasz jej w komponencie, upewnij się, że otaczasz ją komponentem `Suspense`. + +## useSeek + +Kompozycja `useSeek` dostarcza narzędzi do łatwego przeszukiwania i nawigowania przez sceny oraz grafiki obiektów w ThreeJS. Eksportuje 4 funkcje, które umożliwiają znajdowanie obiektów podrzędnych na podstawie określonych właściwości. + +```ts +const { seek, seekByName, seekAll, seekAllByName } = useSeek(); +``` + +Funkcja `seek` przyjmuje trzy parametry: + +- `parent`: Scena ThreeJS lub Object3D. +- `property`: Właściwość, która będzie używana w warunku wyszukiwania. +- `value`: Wartość właściwości do dopasowania. + +Funkcje `seek` i `seekByName` przeszukują obiekt i zwracają obiekt podrzędny z określoną właściwością i wartością. Jeśli nie zostanie znaleziony żaden obiekt podrzędny z podaną właściwością i wartością, zwraca null i rejestruje ostrzeżenie. + +```ts +const carRef = ref(null); + +watch(carRef, ({ model }) => { + if (model) { + const car = model.children[0]; + + const body = seek(car, "name", "Octane_Octane_Body_0"); + body.color.set(new Color("blue")); + } +}); +``` + +Podobnie jak wcześniej, funkcje `seekAll` i `seekAllByName` zwracają tablicę obiektów podrzędnych, których właściwość zawiera podaną wartość. Jeśli nie zostaną znalezione żadne dopasowania, zwracają pustą tablicę i rejestrują ostrzeżenie. + +```ts +const character = ref(null); + +watch(character, ({ model }) => { + if (model) { + const bones = seekAll(character, type, "Bone"); + } +}); +``` + +## useTresContext + +Kompozycja ta ma na celu dostarczenie dostępu do modelu stanu, który zawiera wiele przydatnych właściwości. + +```ts +const { camera, renderer, camera, cameras } = useTresContext(); +``` + +::: warning +`useTresContext` może być używane tylko wewnątrz komponentu `TresCanvas`, ponieważ `TresCanvas` działa jako dostawca danych kontekstowych. Użyj [kontekstu udostępnionego przez TresCanvas](tres-canvas#propiedades-públicas-expuestas), jeśli musisz uzyskać do niego dostęp w komponentach wyższego rzędu niż TresCanvas. +::: + +```vue + + + +``` + +```vue +// MyModel.vue + + +``` + +### Właściwości kontekstu + +| Właściwość | Opis | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| **camera** | aktualnie aktywna kamera | +| **cameras** | kamery istniejące w scenie | +| **controls** | kontrolki Twojej sceny | +| **deregisterCamera** | metoda do wyrejestrowania kamery. Jest to konieczne tylko wtedy, gdy ręcznie tworzysz kamerę. Kamery w szablonie są rejestrowane automatycznie. | +| **extend** | Rozszerza katalog komponentów. Zobacz [rozszerzanie](/advanced/extending). | +| **raycaster** | globalny raycaster używany do zdarzeń wskaźnika | +| **registerCamera** | metoda do zarejestrowania kamery. Jest to konieczne tylko wtedy, gdy ręcznie tworzysz kamerę. Kamery w szablonie są rejestrowane automatycznie. | +| **renderer** | el [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer) Twojej sceny | +| **scene** | la [scena](https://threejs.org/docs/?q=sce#api/en/scenes/Scene) | +| **setCameraActive** | metoda do ustawiania aktywnej kamery | +| **sizes** | zawiera szerokość, wysokość i proporcję obrazu Twojego płótna | diff --git a/docs/pl/api/events.md b/docs/pl/api/events.md new file mode 100644 index 000000000..18c3e07d6 --- /dev/null +++ b/docs/pl/api/events.md @@ -0,0 +1,27 @@ +# Events + +Komponenty **TresJS** emitują zdarzenia wskaźnika podczas interakcji z nimi. Dotyczy to komponentów reprezentujących klasy three.js, które dziedziczą po [THREE.Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) (takich jak meshy, grupy,...). + + + +## Pointer Events + +```html + +``` + +| Zdarzenia | Wywoływane, gdy... cuando ... | Typ(y) parametru obsługi zdarzeń | +| ------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| click   | ... zdarzenia pointerdown i pointerup są wywoływane na tym samym obiekcie jeden po drugim | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) | +| pointer-move | .... wskaźnik porusza się po obiekcie | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) | +| pointer-enter | ... wskaźnik wchodzi do obiektu objeto | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) | +| pointer-leave | ... wskaźnik opuszcza obiekt objeto | [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) | + +[Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16) którą zwraca, obejmuje [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) który wywołał zdarzenie. Możesz uzyskać do niego dostęp za pomocą `intersection.object`. + +Domyślnie obiekty umieszczone przed innymi z obsługą zdarzeń nie powodują zapobiegania wywołaniu tych zdarzeń. To zachowanie można osiągnąć, używając właściwości `blocks-pointer-events`. diff --git a/docs/pl/api/instances-arguments-and-props.md b/docs/pl/api/instances-arguments-and-props.md new file mode 100644 index 000000000..410e4aba3 --- /dev/null +++ b/docs/pl/api/instances-arguments-and-props.md @@ -0,0 +1,145 @@ +# Instancje + +Główną ideą **Tres** jest _samogenerujący się katalog_ wszystkich elementów ThreeJS. Katalog ten jest generowany na podstawie kodu źródłowego ThreeJS, dzięki czemu zawsze jest aktualny. + +Kiedy korzystasz z ThreeJS, musisz importować elementy, które chcesz używać. Na przykład, jeśli chcesz użyć `PerspectiveCamera`, musisz go zaimportować z pakietu `three`: + +```js +import { PerspectiveCamera } from "three"; + +const camera = new PerspectiveCamera(45, width / height, 1, 1000); +``` + +W przypadku **Tres** nie musisz nic importować, ponieważ **Tres** automatycznie generuje **Komponent Vue oparty na obiekcie Three, który chcesz użyć w CamelCase z prefiksem Tres**. Na przykład, jeśli chcesz użyć `PerspectiveCamera`, możesz skorzystać z komponentu ``. + +```vue + +``` + +Oznacza to, że możesz korzystać z tej samej [dokumentacji](https://threejs.org/docs/), której używałbyś przy korzystaniu z podstawowego ThreeJS, ale z siłą Vue. + +## Deklarowanie obiektów + +Jeśli pójdziemy tym tokiem, powinieneś być w stanie zdefiniować instancję w ten sposób: ❌ + +```vue + +``` + +Jednak dzięki **Tres** to nie jest konieczne, możesz zdefiniować właściwości deklaratywnie w następujący sposób: ✅ + +```vue + +``` + +## Argumenty + +Niektóre obiekty w ThreeJS posiadają argumenty, na przykład konstruktor `PerspectiveCamera` ma następujące argumenty: + +- `fov` - Pionowy kąt widzenia kamery. +- `aspect` - Współczynnik proporcji frustum kamery. +- `near` - Bliski plan frustum kamery. +- `far` - Daleki plan frustum kamery. + +Aby przekazać te argumenty do komponentu `TresPerspectiveCamera`, możesz użyć właściwości `args`: + +```vue + +``` + +To samo co zrobienie tego: + +```ts +const camera = new PerspectiveCamera(45, 1, 0.1, 1000); +``` + +## Właściwości + +Możesz także przekazywać właściwości do komponentu, na przykład `TresAmbientLight` ma właściwość `intensity`, więc możesz ją przekazać do komponentu w następujący sposób: + +```html + +``` + +### Ustawianie + +Wszystkie właściwości, których zasadniczy obiekt ma metodę `.set()`, mają skrót do przyjęcia wartości jako tablicy. Na przykład `TresPerspectiveCamera` ma właściwość `position`, która jest obiektem `Vector3`, więc możesz ją przekazać do komponentu w ten sposób: + +```html + +``` + +Aby określić właściwości transformacji, takie jak pozycja, rotacja i skala, dostępna jest skrócona forma, która umożliwia bezpośrednie określenie osi, którą chcesz ustawić w ramach właściwości. Podobna forma skrócona jest także dostępna dla właściwości koloru. + + + +```html + + + +``` + +::: warning +Przy ustawianiu właściwości rotacji w [three.js](https://threejs.org/docs/index.html#api/en/math/Euler), używane jest domyślnie ustalone kolejność 'XYZ'. +Ważne jest, aby pamiętać, że przy ustawianiu właściwości rotacji za pomocą formy skróconej, kolejność, w której ustawiasz kąty, ma znaczenie. Aby uzyskać więcej informacji na ten temat, sprawdź [Kąty Eulera](https://es.wikipedia.org/wiki/%C3%81ngulos_de_Euler) +::: + +```vue + + + + + +``` + +### Skalowanie + +Innym skrótem, który można użyć, jest przekazanie wartości skali do właściwości oczekującej obiektu `Vector3`, używając tej samej wartości dla reszty wektora: + +```html + ✅ +``` + +```html + ✅ +``` + +### Kolory + +Możesz przekazywać kolory do komponentów, używając właściwości color, która akceptuje ciąg znaków z nazwą koloru lub wartość heksadecymalną: + +```html + ✅ +``` + +```html + ✅ +``` + +### Metody + +Niektóre właściwości bazowe są w rzeczywistości metodami, `TresPerspectiveCamera` posiada metodę `lookAt` dziedziczoną z [Object3d](https://threejs.org/docs/#api/en/core/Object3D.lookAt), więc możesz przekazać do komponentu współrzędne w ten sposób: + +```html + +``` diff --git a/docs/pl/api/tres-canvas.md b/docs/pl/api/tres-canvas.md new file mode 100644 index 000000000..5dbd40d58 --- /dev/null +++ b/docs/pl/api/tres-canvas.md @@ -0,0 +1,98 @@ +# TresCanvas + +Komponent `TresCanvas` to główny komponent w Tres. To on tworzy `WebGLRenderer` w ThreeJS. + +```vue{2,5} + +``` + +## Rozmiar płótna + +Komponent `TresCanvas` będzie używał rozmiaru elementu nadrzędnego jako rozmiaru płótna. Jeśli chcesz użyć rozmiaru okna jako rozmiaru płótna, możesz ustawić właściwość `window-size` na `true`. + +```vue + +``` + +Możesz także użyć CSS, aby ustawić rozmiar swojej kanwy. + +```css +html, +body { + margin: 0; + padding: 0; + height: 100%; + width: 100%; +} +#canvas { + height: 100%; + width: 100%; +} +``` + +## Presets + +Tres zawiera kilka presetów dla komponentu `TresCanvas`. Możesz ich użyć, ustawiając właściwość `preset`. + +### Realistyczny + +Preset `realista` ułatwia konfigurację renderera do renderowania bardziej realistycznych scen 3D. + +```vue + +``` + +Jest równoważne: + +```ts +renderer.shadows = true; +renderer.physicallyCorrectLights = true; +renderer.outputColorSpace = SRGBColorSpace; +renderer.toneMapping = ACESFilmicToneMapping; +renderer.toneMappingExposure = 3; +renderer.shadowMap.enabled = true; +renderer.shadowMap.type = PCFSoftShadowMap; +``` + +## Props + +| Prop | Opis | Domyślna wartość | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | +| **alpha** | Kontroluje domyślną wartość alfa. Gdy ustawione na true, wartość wynosi 0. W przeciwnym razie 1. | false | +| **antialias** | Wskazuje, czy ma być używane wygładzanie krawędzi. | `true` | +| **camera** | Ręczna kamera, która będzie używana przez render. | | +| **clearColor** | Kolor, który render użyje do wyczyszczenia płótna. | `#000000` | +| **context** | Można to użyć do dołączenia renderera do istniejącego [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext). | | +| **depth** | Wskazuje, czy bufor rysunku ma bufor [głębokości](https://en.wikipedia.org/wiki/Z-buffering) co najmniej 16 bitów. | `true` | +| **disableRender** | Wyłącza renderowanie w requestAnimationFrame, przydatne dla PostProcessing. | `false` | +| **failIfMajorPerformanceCaveat** | Wskazuje, czy utworzenie renderera zakończy się niepowodzeniem, jeśli zostanie wykryta niska wydajność. Zobacz [specyfikację WebGL](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2) dla więcej szczegółów. | `false` | +| **logarithmicDepthBuffer** | Wskazuje, czy powinien być używany bufor głębokości logarytmiczny. Może być konieczne użycie tego, jeśli obsługiwane są ogromne różnice skali w jednej scenie. Pamiętaj, że ta konfiguracja używa gl_FragDepth, jeśli jest dostępna, co wyłącza optymalizację [Early Fragment Test](https://www.khronos.org/opengl/wiki/Early_Fragment_Test) i może wpłynąć na wydajność. | `false` | +| **outputColorSpace** | Definiuje kodowanie kolorów wyjściowych. | `LinearEncoding` | +| **powerPreference** | Zapewnia sugestię dla agenta użytkownika, wskazującą, która konfiguracja GPU jest odpowiednia dla tego kontekstu WebGL. Może to być "high-performance", "low-power" lub "default". | `default` | +| **precision** | Precyzja shadera. Może to być "highp", "mediump" lub "lowp". | "highp" jeśli urządzenie to obsługuje | +| **premultipliedAlpha** | Wskazuje, czy renderer zakłada, że kolory mają [alfa wymnożoną](https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#premultiplied_alpha). | `true` | +| **preserveDrawingBuffer** | Wskazuje, czy bufory powinny być zachowane do momentu ręcznego wyczyszczenia lub nadpisania. | `false` | +| **shadows** | Włącza cienie w renderze. | `false` | +| **shadowMapType** | Ustawia typ mapy cieni. | `PCFSoftShadowMap` | +| **stencil** | Wskazuje, czy bufor rysunku ma bufor [stencil](https://en.wikipedia.org/wiki/Stencil_buffer) co najmniej 8 bitów. | `true` | +| **toneMapping** | Definiuje ekspozycję mapowania tonów używaną przez render. | `NoToneMapping` | +| **toneMappingExposure** | Ekspozycja mapowania tonów. | `1` | +| **useLegacyLights** | Wskazuje, czy należy używać trybu światła dziedziczonego. | `true` | +| **windowSize** | Wskazuje, czy należy używać rozmiaru okna jako rozmiaru płótna, czy też rodzica elementu. | `false` | + +### Domyślne wartości + +Tres stara się być możliwie mało dogmatyczne. Dlatego nie ustawia prawie żadnych domyślnych wartości dla komponentu `TresCanvas`. Używa diff --git a/docs/pl/cookbook/basic-animations.md b/docs/pl/cookbook/basic-animations.md new file mode 100644 index 000000000..5a201c3ab --- /dev/null +++ b/docs/pl/cookbook/basic-animations.md @@ -0,0 +1,93 @@ +--- +title: Podstawowe animacje +description: Jak używać kompozycji useRenderLoop do animowania swoich obiektów. +author: alvarosabu +thumbnail: /recipes/animations.png +difficulty: 0 +--- + +# Podstawowe animacje + +Ten przewodnik pomoże ci rozpocząć pracę z podstawowymi animacjami w TresJS. + +Zbudujemy prostą scenę z sześcianem. Następnie animujemy sześcian, aby obracał się wokół osi Y i Z. + + + +## useRenderLoop + +Kompozycja `useRenderLoop` to rdzeń animacji w TresJS. Pozwala ona zarejestrować funkcję zwrotną, która zostanie wywołana za każdym razem, gdy renderer zaktualizuje scenę z częstotliwością odświeżania przeglądarki. + +Aby uzyskać szczegółowe wyjaśnienie, jak to działa, zapoznaj się z dokumentacją [useRenderLoop](/api/composables#userenderloop). + +```ts +const { onLoop } = useRenderLoop(); + +onLoop(({ delta, elapsed }) => { + // Se ejecutará en cada fotograma ~ 60FPS (dependiendo de tu monitor) +}); +``` + +## Pobieranie odniesienia do sześcianu + +Aby animować sześcian, musimy uzyskać do niego odniesienie. Możemy to zrobić, przekazując [Template Ref](https://vuejs.org/guide/essentials/template-refs.html), używając atrybutu `ref` do komponentu `TresMesh`. Spowoduje to zwrócenie instancji THREE. + +Dla poprawy wydajności będziemy używać [Shallow Ref](https://v3.vuejs.org/guide/reactivity-fundamentals.html#shallow-reactivity) aby przechowywać odniesienie zamiast standardowego Ref. Zobacz dlaczego [tutaj](../advanced/caveats.md#reactivity) + +```vue + + + +``` + +## Animowanie sześcianu + +Teraz, gdy mamy odniesienie do sześcianu, możemy go animować. Skorzystamy z funkcji zwrotnej `onLoop`, aby aktualizować rotację sześcianu. + +```ts +onLoop(({ delta, elapsed }) => { + if (boxRef.value) { + boxRef.value.rotation.y += delta; + boxRef.value.rotation.z = elapsed * 0.2; + } +}); +``` + +Także możesz użyć `delta` z [wewnętrznego zegara THREE](https://threejs.org/docs/?q=clock#api/en/core/Clock) lub `elapsed`, aby animować sześcian. + +## Ale dlaczego nie używać reaktywności? + +Być może zastanawiasz się, dlaczego nie korzystamy z reaktywności do animowania sześcianu. Odpowiedź jest prosta: wydajność. + +```vue +// To jest złys pomysł ❌ + +``` + +Możemy być kuszeni do używania reaktywności do animowania sześcianu. Ale to byłby zły pomysł. Powodem jest to, że [reaktywność Vue opiera się na Proxy](https://vuejs.org/guide/extras/reactivity-in-depth.html#how-reactivity-works-in-vue) i nie jest przeznaczona do użycia w pętli renderującej, która aktualizuje się 60 razy lub częściej na sekundę. + +Zagnieżdżona strona poniżej przedstawia [prueba de rendimiento de un proxy frente a un objeto regular](https://measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter). Jak widać, proxy jest 5 razy wolniejsze niż zwykły obiekt. + + + +Możesz przeczytać więcej na ten temat w sekcji [Ostrożność](../advanced/caveats.md#reactivity). diff --git a/docs/pl/cookbook/groups.md b/docs/pl/cookbook/groups.md new file mode 100644 index 000000000..293a7597f --- /dev/null +++ b/docs/pl/cookbook/groups.md @@ -0,0 +1,40 @@ +--- +title: Grupa +description: Naucz się, jak grupować wiele obiektów na scenie. +author: alvarosabu +thumbnail: /recipes/groups.png +difficulty: 0 +--- + +# Grupa + +`` to instancja klasy [THREE.Group](https://threejs.org/docs/#api/en/objects/Group), która jest prawie taka sama jak [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D), ale pozwala na **grupowanie wielu obiektów w scenie**, aby mogły być manipulowane jako jednostka (przesuwanie, obracanie itp.). + +## Użycie + +```vue{13,22} + + +``` diff --git a/docs/pl/cookbook/index.md b/docs/pl/cookbook/index.md new file mode 100644 index 000000000..24579c299 --- /dev/null +++ b/docs/pl/cookbook/index.md @@ -0,0 +1,5 @@ +# Książka kucharska 🍳🧑‍🍳 + +Odkryj przewodniki po recepturach, które pomogą Ci rozpocząć korzystanie z podstaw Tres. Każda receptura została zaprojektowana, aby pomóc Ci zrozumieć główne koncepcje Tres i jak je wykorzystać w Twoich projektach. + + diff --git a/docs/pl/cookbook/lights-shadows.md b/docs/pl/cookbook/lights-shadows.md new file mode 100644 index 000000000..ee3c3c959 --- /dev/null +++ b/docs/pl/cookbook/lights-shadows.md @@ -0,0 +1,158 @@ +--- +title: Światła i Cienie +description: Naucz się, jak dodawać światła i cienie do swojej sceny. +author: alvarosabu +thumbnail: /recipes/lights-and-shadows.png +difficulty: 0 +--- + +# Światła i Cienie + +Ten przewodnik pomoże Ci rozpocząć pracę z prostym oświetleniem i cieniami w TresJS. + +Zbudujemy prostą scenę z trzema meshami i płaszczyzną, ale tylko dwa z nich będą miały cienie. + + + +## Konfiguracja sceny (opcjonalne) + +Konfiguracja sceny (opcjonalne) +Importujemy wszystkie moduły, których potrzebujemy, dla większej wygody możemy użyć orbit-controls z pakietu cientos, +[zobacz tutaj, aby dowiedzieć się jak](/cookbook/orbit-controls). + +Umieśćmy cztery obiekty w naszej scenie, jeden z nich będzie płaszczyzną, która odbierze cienie, dwa z nich będą rzutować cienie, a ostatni nie będzie rzutował żadnych cieni w ogóle. + +Skorzystam z [MeshToonMaterial](https://threejs.org/docs/index.html?q=toon#api/en/materials/MeshToonMaterial). Po prostu dlatego, że łatwo zauważymy "delikatne cieniowanie". + +```vue + + + +``` + +## Oświetlenie (wyjaśnienie) + +Jak wiesz, każda instancja w [ThreeJs](https://threejs.org/) jest dostępna w **TresJs**, więc wszystkie rodzaje świateł są również dostępne, wystarczy dodać prefiks `Tres`, aby ich używać. + +Ale nie wszystkie światła mogą generować cienie, to określenie pochodzi bezpośrednio z ThreeJs i ma sens. Na przykład, cel [ambientLight](https://threejs.org/docs/index.html?q=ambient#api/en/lights/AmbientLight) to oświetlenie wszystkich stron sceny, więc nie ma sensu, aby generowało cienie. Z drugiej strony, [DirectionalLight](https://threejs.org/docs/index.html?q=light#api/en/helpers/DirectionalLightHelper) który imituje słońce, może i powinien generować cienie. + +## Cienie (wyjaśnienie) + +Istnieje również wiele rodzajów cieni, na przykład "cienie miękkie" generują się automatycznie, gdy obiekt otrzymuje więcej światła z jednej strony, ale ogólnie rzecz biorąc, "domyślny cień ThreeJS", który kieruje się w stronę innej powierzchni, musi być rzutowany przez jedną siatkę, a druga siatka musi go odbierać. Jak widzimy w naszym przykładzie, `Plane` otrzymuje cień, ale go nie rzutuje. Należy pamiętać, że nie wszystkie materiały mogą rzutować lub odbierać cienie. + +Wewnętrznie ThreeJS automatycznie generuje nową siatkę z [ShadowMaterial](https://threejs.org/docs/index.html?q=shado#api/en/materials/ShadowMaterial) która jest aktualizowana w każdej klatce, dlatego jeśli zastosujesz animacje, cień również się animuje, ale to również dlatego, dlaczego należy ostrożnie korzystać z cieni, ponieważ mogą one wpływać na wydajność. + +::: Uwagi +Zbyt częste korzystanie z cieni w ten sposób może wpływać na wydajność. Jednak istnieją sposoby na poprawę wydajności. Aby uzyskać więcej informacji, zobacz [to video](https://youtu.be/WGNvVGrS0kY?si=q7XyL5eABKUh3gbS&t=1256) +::: + +## Włączanie cieni + +Możemy podzielić to na trzy kroki: + +### Włączanie cieni w renderowaniu + +```vue +//... + + +``` + +### Konfiguracja światła do rzucania cieni + +Możemy po prostu dodać boolean `cast-shadow`, Vue interpretuje to jako `prop` o wartości `true`. + +_Oświetlenie ambientalne nie generuje tutaj żadnych cieni_ + +```vue +//... + + +``` + +### Ustawianie obiektów do rzucania lub odbierania cieni + +Podobnie jak w poprzednim kroku, ustawiamy siatkę, którą chcemy, aby rzuciła cień (nasza sfera) za pomocą właściwości `cast-shadow`, a obiekt, który ma odbierać cień (nasza płaszczyzna) za pomocą właściwości `receive-shadow`. + +```vue +//... + + +``` + +eraz mamy wszystkie niezbędne kroki, aby dodać cienie do naszej sceny, a jeśli zastosujemy to, co się nauczyliśmy w [podstawowych animacjach](/cookbook/basic-animations), i dodamy ruch do naszego sześcianu, zauważysz, że cień również animuje się 🤩 + +```vue + + + +``` + +_Zauważ, że celowo nie zastosowałem `cast-shadow` do `Cone`, aby nie rzutował żadnych cieni._ diff --git a/docs/pl/cookbook/load-models.md b/docs/pl/cookbook/load-models.md new file mode 100644 index 000000000..f5874ebcd --- /dev/null +++ b/docs/pl/cookbook/load-models.md @@ -0,0 +1,153 @@ +--- +title: Wczytywanie Modeli +description: Wczytaj modele 3D do swoich scen w Tres. +author: alvarosabu +thumbnail: /recipes/gltf-model.png +difficulty: 1 +--- + +# Wczytywanie Modeli + +> Wszystkie modele używane w tej instrukcji pochodzą od [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c). + +Modele 3D są dostępne w setkach różnych formatów plików, z różnymi zastosowaniami, różnymi cechami i zmienną złożonością. + +W tej instrukcji skupimy się na wczytywaniu modeli w formacie gLTF (GL Transmission Format), który jest najbardziej powszechnym formatem dla modeli 3D w sieci. + + + +Istnieje kilka sposobów ładowania modeli w TresJS: + +::: warning +Proszę zauważyć, że w powyższych przykładach używamy oczekiwania na najwyższym poziomie (top level await), upewnij się, że owinięto to w komponent [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense). Zobacz Suspense po więcej informacji. +::: + +## Użycie `useLoader` + +Kompozycja `useLoader` pozwala przekazać dowolny rodzaj ładowacza three.js oraz URL do wczytania zasobu. Zwraca promise `Promise` z wczytanym zasobem. + +Dla szczegółowego wyjaśnienia, jak korzystać z `useLoader`, sprawdź dokumentację [useLoader](/api/composables#useloader). + +```ts +import { useLoader } from "@tresjs/core"; +import { GLTFLoader } from "three/addons/loaders/GLTFLoader"; + +const { scene } = await useLoader(GLTFLoader, "/models/AkuAku.gltf"); +``` + +Następnie możesz przekazać scenę modelu do komponentu [`primitive`](/advanced/primitive) w TresJS, aby go zrenderować: + +```html{2} + + + +``` + +> Komponent `` nie jest oddzielnym komponentem w źródle Tres. Zamiast tego jest częścią głównej funkcji Tres. Gdy używasz ``, tłumaczy się to na wywołanie `createElement`, które tworzy odpowiedni obiekt three.js na podstawie dostarczonej właściwości "object". + +Zauważ w powyższym przykładzie, że używamy komponentu `Suspense` do owinięcia komponentu `TresCanvas`. Wynika to z tego, że `useLoader` zwraca `Promise` i musimy poczekać, aż zostanie rozwiązana, zanim zrenderujemy scenę. + +## Użycie `useGLTF` + +Bardziej wygodnym sposobem ładowania modeli jest użycie kompozycji `useGLTF` dostępnej w pakiecie [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos). + +```ts +import { useGLTF } from "@tresjs/cientos"; + +const { scene, nodes, animations, materials } = await useGLTF( + "/models/AkuAku.gltf" +); +``` + +Zaletą korzystania z `useGLTF` jest możliwość przekazania właściwości `draco` aby włączyć [kompresję Draco](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) dla modelu. Spowoduje to zmniejszenie rozmiaru modelu i poprawi wydajność. + +```ts +import { useGLTF } from "@tresjs/cientos"; + +const { scene, nodes, animations, materials } = await useGLTF( + "/models/AkuAku.gltf", + { draco: true } +); +``` + +Alternatywnie, możesz łatwo wybierać obiekty wewnątrz modelu, korzystając z właściwości `nodes`. + +```vue + + + +``` + +## Użycie `GLTFModel` + +Komponent `GLTFModel` to opakowanie dla `useGLTF` dostępne w pakiecie [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos). + +```vue{2,9} + + +``` + +Ten podejście jest bardziej proste, ale oferuje mniej kontroli nad modelem. + +## useFBX + +Kompozycja `useFBX` jest dostępna w pakiecie [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos). + +```ts +import { useFBX } from "@tresjs/cientos"; + +const model = await useFBX("/models/AkuAku.fbx"); +``` + +W takim razie, to tak proste jak dodanie sceny do twojej sceny: + +```html{2} + + + +``` + +## FBXModel + +Komponent `FBXModel` to opakowanie dla `useFBX` dostępne w pakiecie [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos). Jego użycie jest podobne do `GLTFModel`: + +```vue{2,9} + + +``` diff --git a/docs/pl/cookbook/load-textures.md b/docs/pl/cookbook/load-textures.md new file mode 100644 index 000000000..f98ace590 --- /dev/null +++ b/docs/pl/cookbook/load-textures.md @@ -0,0 +1,85 @@ +--- +title: Ładowanie tekstur +description: Dodaj mapy tekstur do swoich obiektów w TresJS. +author: alvarosabu +thumbnail: /recipes/load-textures.png +difficulty: 1 +--- + +# Ładowanie tekstur + +> Wszystkie tekstury używane w tym przykładzie pochodzą z [ambientcg](https://ambientcg.com/). + +Tekstury trójwymiarowe (3D) to obrazy zawierające wiele warstw danych, co pozwala im reprezentować objętość lub symulować struktury trójwymiarowe. Te tekstury są powszechnie stosowane w grafice 3D i efektach wizualnych, aby poprawić realizm i złożoność scen i obiektów. + + + +Istnieją dwie metody ładowania tekstur 3D w TresJS: + +## Korzystając z `useLoader` + +Kompozycja `useLoader` pozwala przekazać dowolny rodzaj ładowacza three.js oraz adres URL do zasobu do wczytania. Zwraca obiekt `Promise` z wczytanym zasobem. + +Aby uzyskać szczegółowe wyjaśnienie korzystania z `useLoader`, sprawdź dokumentację[useLoader](/api/composables#use-loader). + +```ts +import { useLoader } from "@tresjs/core"; +import { TextureLoader } from "three"; + +const texture = useLoader(TextureLoader, "/Rock035_2K_Color.jpg"); +``` + +Następnie możesz przekazać teksturę do materiału: + +```html + + + + + + + + +``` + +Zauważ w powyższym przykładzie, że używamy komponentu `Suspense` aby otoczyć komponent `TresCanvas`. Dzieje się tak, ponieważ `useLoader` zwraca obiekt `Promise`, i musimy poczekać, aż zostanie rozwiązany, zanim zrenderujemy scenę. + +## Korzystanie z `useTexture` + +ardziej wygodnym sposobem ładowania tekstur jest używanie kompozycji `useTexture`. Akceptuje zarówno tablicę adresów URL, jak i pojedynczy obiekt z ścieżkami odnośników do tekstur. + +Aby uzyskać więcej informacji na temat `useTexture`, sprawdź dokumentację [useTexture](/api/composables#use-texture). + +```ts +import { useTexture } from "@tresjs/core"; + +const pbrTexture = await useTexture({ + map: "/textures/black-rock/Rock035_2K_Displacement.jpg", + displacementMap: "/textures/black-rock/Rock035_2K_Displacement.jpg", + roughnessMap: "/textures/black-rock/Rock035_2K_Roughness.jpg", + normalMap: "/textures/black-rock/Rock035_2K_NormalDX.jpg", + aoMap: "/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg", + metalnessMap: "/textures/black-rock/myMetalnessTexture.jpg", + matcap: "/textures/black-rock/myMatcapTexture.jpg", + alphaMap: "/textures/black-rock/myAlphaMapTexture.jpg", +}); +``` + +Podobnie jak w poprzednim przykładzie, możemy przekazać wszystkie tekstury do materiału za pomocą propsów: + +```html + + + + + + + + +``` diff --git a/docs/pl/cookbook/orbit-controls.md b/docs/pl/cookbook/orbit-controls.md new file mode 100644 index 000000000..55a847751 --- /dev/null +++ b/docs/pl/cookbook/orbit-controls.md @@ -0,0 +1,102 @@ +--- +title: OrbitControls +description: Jak korzystać z OrbitControls do interakcji ze sceną. +author: alvarosabu +thumbnail: /recipes/orbit-controls.png +difficulty: 1 +--- + +# OrbitControls + + + +[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) to kontroler kamery, który umożliwia obracanie się wokół celu. To doskonały sposób na eksplorację swojej sceny. + +Jednakże, nie jest to część rdzenia ThreeJS. Aby go używać, musisz go zaimportować z modułu `three/addons/controls/OrbitControls`. + +Powstaje problem, ponieważ **TresJS** automatycznie tworzy katalog rdzenia Three, abyś mógł używać ich jako komponentów. + +Na szczęście, **TresJS** dostarcza sposób na rozszerzanie katalogu komponentów. Możesz to zrobić, korzystając z metody `extend` z biblioteki rdzenia. + +Aby uzyskać więcej informacji na temat rozszerzania katalogu TresJS, zajrzyj do sekcji [extending](/advanced/extending.md). + +## Użycie OrbitControls + +Aby używać `OrbitControls`, musisz go zaimportować z modułu `three/addons/controls/OrbitControls`. + +```js +import { OrbitControls } from "three/addons/controls/OrbitControls"; +``` + +Następnie musisz rozszerzyć katalog komponentów, korzystając z metody `extend`. + +```js +import { extend } from "@tresjs/core"; +import { OrbitControls } from "three/addons/controls/OrbitControls"; + +extend({ OrbitControls }); +``` + +Teraz możesz używać komponentu `TresOrbitControls` w swojej scenie. + +```vue + +``` + +Ponieważ [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) wymaga odniesienia do kamery i renderera, musisz przekazać je jako argumenty. + +Możesz skorzystać z komponentu [useTres](/api/composables#usetres) aby uzyskać dostęp do kamery i renderera. + +```ts +import { useTres } from "@tresjs/core"; + +const { state } = useTres(); +``` + +Ostateczny kod wyglądałby mniej więcej tak: + +```vue + + + +``` + +## OrbitControls z `cientos` + +To jest moment, w którym zaczyna się część interesująca. ✨ +Pakiet `cientos` dostarcza komponentu o nazwie `` który jest opakowaniem dla `OrbitControls` z modułu [`three-stdlib`](https://github.com/pmndrs/three-stdlib). + +Najlepsze w tym wszystkim? Nie musisz rozszerzać katalogu ani przekazywać żadnych argumentów. +Po prostu działa. 💯 + +```vue + +``` diff --git a/docs/pl/cookbook/shaders.md b/docs/pl/cookbook/shaders.md new file mode 100644 index 000000000..0625ba7b4 --- /dev/null +++ b/docs/pl/cookbook/shaders.md @@ -0,0 +1,174 @@ +--- +title: Shadery +description: Shadery otwierają świat nieograniczonych możliwości. +author: alvarosabu +thumbnail: /recipes/shaders.png +difficulty: 2 +--- + +# Shadery + +To przewodnik pomoże Ci rozpocząć pracę ze shaderami w TresJS. + +Zbudujemy prostą scenę z blobem. Następnie animujemy bloba, aby delikatnie go zniekształcić. + +::: warning +_Wymagana jest podstawowa wiedza na temat działania shaderów_ +::: + + + +## Konfiguracja sceny (opcjonalnie) + +Importujemy wszystkie moduły, których potrzebujemy, dla wygody możemy użyć orbit-controls z cientos, +[zobacz tutaj, aby dowiedzieć się jak](/cookbook/orbit-controls). + +Teraz umieśćmy naszą kamerę w pozycji `[11,11,11]`. + +Na koniec, aby ułatwić nam orientację, dodajmy prostą płaszczyznę, obróconą wzdłuż osi X, o rozmiarze `[10, 10]`. + +```vue + + + +``` + +## ShaderMaterial + +Jak wiesz, każda instancja w [ThreeJs](https://threejs.org/) jest dostępna w **TresJs**, więc również `ShaderMaterial`, musimy tylko dodać przedrostek `Tres`, aby go użyć. + +Dla naszego bloba moglibyśmy użyć prostego `SphereGeometry` dodając kilka `widthSegments` i `heightSegments` aby stworzyć efekt gładkości, i umieścić naszego bloba 4 jednostki w osi Y dodatniej. + +```vue + + + + +``` + +`ShaderMaterial` przyjmuje specjalne właściwości, takie jak `uniforms`, `vertexShader` i `fragmentShader`, więc możemy go utworzyć w naszym skrypcie i dokonać powiązania z naszą instancją. + +Dla tego przykładu nasze uniforms wyglądają tak: + +```ts +import { Vector2 } from "three"; + +//... +const uniforms = { + uTime: { value: 0 }, + uAmplitude: { value: new Vector2(0.1, 0.1) }, + uFrequency: { value: new Vector2(20, 5) }, +}; +//.. +``` + +Nasz fragment shader wygląda tak: + +```ts +//... +const fragmentShader = ` +precision mediump float; +varying vec2 vUv; + +void main() { + gl_FragColor = vec4(1.0, vUv.y, 0.5, 1.0); +} +`; +//.. +``` + +A na koniec nasz `vertexShader`: + +```ts +const vertexShader = ` +uniform vec2 uAmplitude; +uniform vec2 uFrequency; +uniform float uTime; + +varying vec2 vUv; + +void main() { + vec4 modelPosition = modelMatrix * vec4(position, 1.0); + modelPosition.y += sin(modelPosition.x * uFrequency.x - uTime) * uAmplitude.x; + modelPosition.x += cos(modelPosition.y * uFrequency.y - uTime) * uAmplitude.y; + + vec4 viewPosition = viewMatrix * modelPosition; + gl_Position = projectionMatrix * viewPosition; + vUv = uv; +} +`; +//.. +``` + +## Animowanie bloba + +Podobnie jak w przypadku przykładu [Podstawowe animacje](/cookbook/basic-animations), zaczynamy od odwołania się do naszego bloba, używając [Template Ref](https://vuejs.org/guide/essentials/template-refs.html) + +```vue + + + +``` + +Gdy już to mamy, możemy użyć funkcji `onLoop`, aby animować nasz `uTime`. + +```ts +import { TresCanvas, useRenderLoop } from "@tresjs/core"; + +//... +const { onLoop } = useRenderLoop(); + +onLoop(({ elapsed }) => { + if (blobRef.value) { + blobRef.value.material.uniforms.uTime.value = elapsed; + } +}); +//... +``` + +I to wszystko, mamy nasz podstawowy shader działający płynnie. + +## Korzystanie z wtyczki GLSL vite (opcjonalnie) + +_Ten krok jest całkowicie opcjonalny i wychodzi poza zakres zespołu **TresJs**_ + +Definiowanie naszego shadera w jednym pliku nie zawsze jest najlepszym pomysłem, ale jeśli używasz [vite](https://vitejs.dev/), możesz umieścić swoje pliki `GLSL` w innym pliku, używając jedynie [vite-plugin-glsl](https://www.npmjs.com/package/vite-plugin-glsl) (sprawdź link do oficjalnej dokumentacji). + +A mogłbyś mieć strukturę podobną do tej: + +``` +├── src/ +│ ├── myTresJsComponent.vue +│ ├── shaders/ +│ ├── vertexShader.glsl +│ ├── fragmentShader.glsl +``` diff --git a/docs/pl/cookbook/text-3d.md b/docs/pl/cookbook/text-3d.md new file mode 100644 index 000000000..cb647549e --- /dev/null +++ b/docs/pl/cookbook/text-3d.md @@ -0,0 +1,189 @@ +--- +title: Text 3D +description: Dodaj tekst 3D z łatwością. +author: alvarosabu +thumbnail: /recipes/text-3d.png +difficulty: 1 +--- + +# Tekst 3D + +[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) to jedna z metod, dzięki której możemy dodać tekst w 3D do naszej sceny. + + + +ednak nie jest to część rdzenia ThreeJS. Aby go użyć, musisz zaimportować go z modułu `three/addons/controls/TextGeometry`. + +To tworzy problem, ponieważ **TresJS** automatycznie tworzy katalog rdzenia Three, abyś mógł używać ich jako komponentów. + +Na szczęście **TresJS** zapewnia sposób rozszerzania katalogu komponentów. Możesz to zrobić, używając metody `extend` z głównej biblioteki. + +Aby uzyskać więcej informacji na temat rozszerzania katalogu w TresJS, sprawdź sekcję [extending](/advanced/extending.md). + +## Użycie TextGeometry + +Aby używać `TextGeometry`, musisz go zaimportować z modułu `three/addons/geometries/TextGeometry`. + +```js +import { TextGeometry } from "three/addons/geometries/TextGeometry"; +``` + +Następnie musisz rozszerzyć katalog komponentów za pomocą metody `extend`. + +```js +import { extend } from "@tresjs/core"; +import { TextGeometry } from "three/addons/geometries/TextGeometry"; + +extend({ TextGeometry }); +``` + +[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) wymaga tylko jednego wymaganego argumentu, czyli źródła. Przykład użycia możesz zobaczyć poniżej. + +```js +const fontPath = + "https://raw.githubusercontent.com/Tresjs/assets/main/fonts/FiraCodeRegular.json"; + +const loader = new FontLoader(); + +const font = await new Promise((resolve, reject) => { + try { + loader.load(fontPath, (font) => { + resolve(font); + }); + } catch (error) { + reject(console.error("cientos", error)); + } +}); +``` + +Teraz możesz użyć komponentu `TresTextGeometry` wewnątrz TresMesh w swojej scenie. + +```vue + +``` + +Następnie, podobnie jak w przykładzie, możesz przekazać obiekt z pożądanymi konfiguracjami. + +```ts +const fontOptions = { + size: 0.5, + height: 0.2, + curveSegments: 5, + bevelEnabled: true, + bevelThickness: 0.05, + bevelSize: 0.02, + bevelOffset: 0, + bevelSegments: 4, +}; +``` + +Możemy również przekazać teksturę matcapTexture, aby dodać drobne detale, używając TresMeshNormalMaterial wewnątrz TresMesh. + +```ts +const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png']) + + + + + +``` + +W takim razie, końcowy kod wyglądałby mniej więcej tak: + +```vue + + + +``` + +Rozumiem, że może wydawać się to dużo pracy, ale mam dobre wieści, istnieje znacznie prostsze rozwiązanie. + +## TextGeometry z `cientos` + +Pakiet `cientos` dostarcza komponentu o nazwie `` który jest opakowaniem dla `TextGeometry` z modułu [`three-stdlib`](https://github.com/pmndrs/three-stdlib). + +Co najlepsze? Nie musisz rozszerzać katalogu, po prostu przekaż argument dla źródła. +Po prostu działa. 💯 (jeśli nie podano tekstu, tekst będzie TresJS) + +```vue + +``` + +Możemy przekazać opcje jako propsy + +```html + +``` + +w przypadku braku dostarczenia opcji, wartości domyślne to: + +```js +size: 0.5, +height: 0.2, +curveSegments: 5, +bevelEnabled: true, +bevelThickness: 0.05, +bevelSize: 0.02, +bevelOffset: 0, +bevelSegments: 4, +``` + +Domyślnie tekst w ThreeJS zaczyna się w pozycji początkowej meshu, więc jeśli jest to [0,0,0], tekst zacznie się tam, ale możemy go wyśrodkować, po prostu przekazując flagę "center". + +```vue + +``` diff --git a/docs/pl/debug/devtools.md b/docs/pl/debug/devtools.md new file mode 100644 index 000000000..51ac74b7f --- /dev/null +++ b/docs/pl/debug/devtools.md @@ -0,0 +1,26 @@ +# Narzędzia deweloperskie + +Jednym z najtrudniejszych wyzwań, przed którym stoi programista tworząc doświadczenia 3D w przeglądarce, jest debugowanie. Element `canvas` przeglądarki to czarna skrzynka, trudno jest zrozumieć, co się dzieje w środku. Imperatywny charakter [ThreeJS](https://threejs.org/) sprawia, że jest to niezwykle trudne do debugowania, trzeba polegać na `console.log` aby zobaczyć, co się dzieje, lub używać narzędzi zewnętrznych do dostrojenia i sprawdzenia sceny. + +Niech mnie nie zaczynają od sprawdzania wydajności twojej sceny. 😱 + +![deweloper debugujący 3D](/debug-3D.png) + +Jednym z naszych celów przy tworzeniu TresJS jest zaoferowanie **najlepszego DX (Developer Experience)** przy pracy ze scenami 3D w przeglądarce. Dzięki deklaratywnemu charakterowi ekosystemu, a także różnym rozwiązaniom oferowanym przez ekosystem Vue, takim jak Vue Devtools, Nuxt i Vite, możemy zapewnić lepsze narzędzia dla programistów do debugowania ich scen. + +## Przedstawiamy narzędzia deweloperskie + +Od wersji , wprowadzamy narzędzia deweloperskie TresJS, dostosowaną zakładkę inspektora dla [ Oficjalnych narzędzi deweloperskich Chrome dla Vue](https://devtools.vuejs.org/guide/installation.html), które umożliwiają inspekcję scen i komponentów TresJS. + +![Narzędzia deweloperskie TresJS](/vue-chrome-devtools.png) + +### Funkcje + +- **Inspektor Sceny**: Sprawdź bieżącą scenę i jej komponenty, korzystając z widoku drzewa podobnego do inspektora komponentów Vue Devtools. +- **Przydzielanie Pamięci**: Zobacz, ile pamięci zużywają komponenty. +- **Inspektor Obiektów**: Sprawdź właściwości wybranego obiektu w scenie, w tym jego dzieci. +- **Edytowalne właściwości**: I tak, możesz edytować właściwości wybranego obiektu i zobaczyć zmiany w czasie rzeczywistym. + +![](/devtools-scene-inspector.png) + +Ciesz się nowymi narzędziami deweloperskimi i daj nam znać, co o nich myślisz! 🎉 diff --git a/docs/pl/directives/v-always-look-at.md b/docs/pl/directives/v-always-look-at.md new file mode 100644 index 000000000..1e4f187fb --- /dev/null +++ b/docs/pl/directives/v-always-look-at.md @@ -0,0 +1,62 @@ +# v-always-look-at 👀 + +Dzięki nowej dyrektywie v-always-look-at dostarczonej przez **TresJS**, możesz łatwo zadbać o to, aby [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) zawsze patrzył na określoną pozycję, którą można przekazać jako Vector3 lub tablicę. + +## Użycie + +```vue{3,9} + + +``` + +Nie ważne, gdzie przeniesiesz Box, zawsze patrzy na pozycję [0,0,0]. + +### Dlaczego nie używać wbudowanej metody look-at? + +Możesz zapytać, dlaczego nie używać metody `:look-at` bezpośrednio w komponencie? Dlaczego potrzebuję tego? + +Odpowiedź brzmi, że za pomocą metody `:look-at` wskażesz, aby patrzył na tę pozycję tylko raz, gdy instancja jest zamontowana, a następnie, jeśli obiekt się zmieni, to nie zostanie zaktualizowany. + +### Możesz patrzeć na inne instancje też! + +Inną zaletą jest to, że możesz patrzeć na instancję w ruchu, na przykład z kamerą, tak: + +```vue{4,6,20,23} + + +``` diff --git a/docs/pl/directives/v-distance-to.md b/docs/pl/directives/v-distance-to.md new file mode 100644 index 000000000..fa64fe7e3 --- /dev/null +++ b/docs/pl/directives/v-distance-to.md @@ -0,0 +1,36 @@ +# v-distance-to + +Czy próbowałeś obliczyć odległość między dwoma Object3D? + +Dzięki nowej dyrektywie `v-distance-to` jest to łatwiejsze niż kiedykolwiek wcześniej. Wystarczy tylko wskazać obiekt docelowy do wykonania pomiaru, a wynik pojawi się w konsoli. + +Dodatkowo zostanie utworzona strzałka wskazująca, które obiekty są mierzone. + +```vue{2,8,13} + + +``` + +Użycie `v-distance-to` jest reaktywne, więc doskonale współpracuje z @tres/leches 🍰. + +::: Uwagi +`v-distance-to` nie zmierzy obiektu w ruchu w ramach renderLoop. +::: diff --git a/docs/pl/directives/v-light-helper.md b/docs/pl/directives/v-light-helper.md new file mode 100644 index 000000000..67d33b793 --- /dev/null +++ b/docs/pl/directives/v-light-helper.md @@ -0,0 +1,35 @@ +# v-light-helper 🔆 + +Dzięki nowej dyrektywie **TresJS**, dostarczanej przez TresJS, możesz szybko dodać odpowiedniego pomocnika do swoich świateł za pomocą zaledwie jednej linii kodu 😍. + +Obsługiwane są następujące światła: + +- DirectionalLight +- PointLight +- SpotLight +- HemisphereLight + +## Użycie + +```vue{2,8,11,14,17} + + +``` diff --git a/docs/pl/directives/v-log.md b/docs/pl/directives/v-log.md new file mode 100644 index 000000000..44cf38548 --- /dev/null +++ b/docs/pl/directives/v-log.md @@ -0,0 +1,50 @@ +# v-log + +### Problem + +Kiedy musisz zalogować swoją instancję, musisz użyć referencji szablonu, a następnie zalogować je: + +```vue + + + +``` + +I to jest DUŻO kodu tylko dla prostego loga, prawda? + +## Użycie + +Dzięki nowej dyrektywie v-log dostarczanej przez **TresJS**, możesz to zrobić, dodając `v-log` do instancji. + +```vue{2,10,12} + + +``` + +Zauważ, że możesz przekazać modyfikator o nazwie właściwości, na przykład `v-log:material` i zostanie bezpośrednio dodana właściwość `material` 😍 diff --git a/docs/pl/guide/getting-started.md b/docs/pl/guide/getting-started.md new file mode 100644 index 000000000..ea9fd247a --- /dev/null +++ b/docs/pl/guide/getting-started.md @@ -0,0 +1,93 @@ +# Instalacja + +Dowiedz się, jak zainstalować TresJS + +::: code-group + +```bash [pnpm] +pnpm add three @tresjs/core +``` + +```bash [npm] +npm install three @tresjs/core +``` + +```bash [yarn] +yarn add three @tresjs/core +``` + +::: + +> Zalecane do użytku z Vue 3.x i Composition API + +## Typescript + +TresJS zostało napisane w TypeScript i jest w pełni otypowane. Jeśli korzystasz z TypeScript, będziesz czerpać pełne korzyści z typowań. Upewnij się tylko, że zainstalujesz typy dla Three. + +::: code-group + +```bash [npm] +npm install @types/three -D +``` + +```bash [yarn] +yarn add @types/three -D +``` + +```bash [pnpm] +pnpm add @types/three -D +``` + +::: + +## Rozpoczęcie + +Możesz zainstalować TresJS tak samo, jak każdy inny plugin Vue + +```ts +import { createApp } from "vue"; +import Tres from "@tresjs/core"; +import App from "./App.vue"; + +export const app = createApp(App); + +app.use(Tres); +app.mount("#app"); +``` + +Możesz również używać go bezpośrednio w swoim komponencie + +```vue + + + +``` + +::: tip +Jest to zalecane ze względów wydajności i rozmiaru paczki. Działa to lepiej przy tree-shaking, importujesz tylko te komponenty, których używasz. +::: + +## Vite + +Ponieważ v2 to niestandardowy renderer, musimy poinformować `vue-compiler` twojej aplikacji, że komponenty Tres są dołączane, aby uniknąć ostrzeżenia `[Vue warn]: Failed to resolve component`. + +Wystarczy dodać to do swojego pliku `vite.config.ts` wewnątrz pluginu Vue: + +```ts +import { templateCompilerOptions } from "@tresjs/core"; + +export default defineConfig({ + plugins: [ + vue({ + // Other config + ...templateCompilerOptions, + }), + ], +}); +``` diff --git a/docs/pl/guide/index.md b/docs/pl/guide/index.md new file mode 100644 index 000000000..5bc55ec18 --- /dev/null +++ b/docs/pl/guide/index.md @@ -0,0 +1,113 @@ +# Wstęp + + +
+ +
+ + +::: code-group + +```bash [npm] +npm install @tresjs/core three +``` + +```bash [yarn] +yarn add @tresjs/core three +``` + +```bash [pnpm] +pnpm add @tresjs/core three +``` + +::: + +## Typescript + +TresJS jest napisane w języku TypeScript i jest w pełni otypowane. Jeśli używasz TypeScript, będziesz korzystać z pełnych korzyści z typowań. Po prostu upewnij się, że zainstalujesz typy dla Three. + +::: code-group + +```bash [npm] +npm install @types/three -D +``` + +```bash [yarn] +yarn add @types/three -D +``` + +```bash [pnpm] +pnpm add @types/three -D +``` + +::: + +## Vite + +Jeśli używasz Vite, musisz dodać następujący kod do swojego pliku `vite.config.ts`: + +```ts +import { templateCompilerOptions } from '@tresjs/core' + +export default defineConfig({ + plugins: [ + vue({ + // Other config + ...templateCompilerOptions + }), + ], +}), +``` + +To jest wymagane, aby kompilator szablonów działał z niestandardowym renderem i nie generował ostrzeżeń na konsoli. Aby uzyskać więcej informacji, sprawdź [tutaj](/pl/guide/troubleshooting.html). + +## Wypróbuj to online + +### Sandbox + +Możesz wypróbować TresJS online za pomocą oficjalnego [sandbox](https://play.tresjs.org/). Sprawdź to: + + + +### StackBlitz + +Mamy zupełnie nowy starter w [StackBlitz](https://stackblitz.com/) by wypróbować TresJS online. Sprawdź to: + +![](/stackblitz-starter.png) + + + +## Playground + +Mamy także plac zabaw, gdzie możesz wypróbować TresJS online. Sprawdź to [aquí](https://playground.tresjs.org/). + +![](/playground.png) + +## Motivación + +[ThreeJS](https://threejs.org/) to wspaniała biblioteka do tworzenia niesamowitych witryn 3D przy użyciu WebGL. Jest to także stale aktualizowana biblioteka, co sprawia, że utrudnia utrzymanie wrapperów, takich jak [TroisJS](https://troisjs.github.io/). + +W ekosystemie React mamy imponujące rozwiązanie custom render o nazwie **custom render** o nazwie [React-three-fiber](https://docs.pmnd.rs/react-three-fiber) które pozwala budować sceny deklaratywnie za pomocą komponentów wielokrotnego użytku, samodzielnych, reagujących na stan. + +W poszukiwaniu czegoś podobnego w ekosystemie VueJS natrafiłem na niesamowitą bibliotekę o nazwie [Lunchbox](https://github.com/breakfast-studio/lunchboxjs) która działa według tego samego konceptu co R3F. Oferuje [własny renderer Vue3](https://vuejs.org/api/custom-renderer.html). Przyczyniam się również do poprawy tej biblioteki, aby była równie dojrzała i bogata w funkcje co R3F. + +EJedynym problemem jest to, że mieszanie renderów kompilatorów w Vue 3 to coś, nad czym społeczność Vue wciąż pracuje - zobacz [tutaj](https://github.com/vuejs/vue-loader/pull/1645) po więcej informacji. + +```ts +// Example Vite setup +import { createApp } from "vue"; +import { createApp as createLunchboxApp } from "lunchboxjs"; +import App from "./App.vue"; +import LunchboxApp from "./LunchboxApp.vue"; + +// html app +const app = createApp(App); +app.mount("#app"); + +// lunchbox app +const lunchboxApp = createLunchboxApp(LunchboxApp); +// assuming there's an element with ID `lunchbox` in your HTML app +lunchboxApp.mount("#lunchbox"); +``` + +Tak więc zainspirowany obiema bibliotekami, postanowiłem stworzyć własny renderer Vue dla ThreeJS. Oto **TresJS v2**. diff --git a/docs/pl/guide/migration-guide.md b/docs/pl/guide/migration-guide.md new file mode 100644 index 000000000..c90b75a44 --- /dev/null +++ b/docs/pl/guide/migration-guide.md @@ -0,0 +1,226 @@ +# Przewodnik Migracyjny + +Ten przewodnik ma na celu pomoc w migracji z wersji 1 do najnowszych wersji TresJS 🤩✨. + +::: code-group + +```bash [pnpm] +pnpm update @tresjs/core +``` + +```bash [npm] +npm update @tresjs/core +``` + +```bash [yarn] +yarn upgrade @tresjs/core +``` + +::: + +## Nowości + +### Vue Custom Renderer + +**TresJS** to teraz [Vue Custom Renderer](https://vuejs.org/api/custom-renderer.html#createrenderer) 🎉 znajdujący się wewnątrz otaczającego go komponentu `TresCanvas`, który zajmuje się tworzeniem `WebGLRenderer` i `Scene` za ciebie oraz tworzy **nową instancję aplikacji Vue** do renderowania sceny. + +### Obsługa TypeScript i Intellisense 🦾 + +![TresJS Intellisense](/v2-intellisense.gif) + +To była prawdopodobnie najczęściej **żądana funkcja w TresJS**. Teraz komponenty Tres współpracują z Volar i zapewniają intellisense typów. + +**TresJS** generuje teraz deklaracje typów w czasie kompilacji dla wszystkich komponentów opartych na katalogu ThreeJS. Oznacza to, że możesz używać wszystkich komponentów ThreeJS i otrzymać intellisense typów dla nich. + +### Plugin Tres jest opcjonalny 👍 + +Plugin `TresPlugin` jest teraz opcjonalny. Możesz używać TresJS bez niego, importując komponenty bezpośrednio z `tresjs/core`: + +```vue + + + +``` + +::: info +To jest zalecane ze względów wydajności i rozmiaru paczki; tree-shaking będzie działał lepiej, a importujesz tylko te komponenty, których używasz. +::: + +### TresScene już nie jest potrzebny + +Komponent `` jest teraz przestarzały, ponieważ scena jest teraz tworzona przez ``. + +Na początku myślałem, że będzie to dobry pomysł, aby mieć osobny komponent dla sceny z uwagi na zwięzłość i zachowanie podobieństwa do czystego ThreeJS, ale okazało się, że to nie było naprawdę przydatne. + +Teraz możesz utworzyć scenę tak jak poniżej: + +```vue + +``` + +Aby zaktualizować swój kod, po prostu usuń komponent `` i przenieś dzieci do komponentu ``. + +### `useCatalog` jest teraz przestarzałe + +Funkcja `useCatalog` jest teraz przestarzała. Teraz możesz importować katalog bezpośrednio z `@tresjs/core`. + +Możesz przeczytać więcej na ten temat tutaj: [Rozszerzanie](/advanced/extending.md) + +Zmień to: + +```ts {2,5,7} +import { useCatalog } from "@tresjs/core"; +import { TextGeometry } from "three/addons/geometries/TextGeometry"; + +const { extend } = useCatalog(); + +extend({ TextGeometry }); +``` + +Na to: + +```ts {2,6} +// Correcto ✅ +import { extend } from "@tresjs/core"; +import { TextGeometry } from "three/addons/geometries/TextGeometry"; + +extend({ TextGeometry }); +``` + +### Wartość odniesienia modelu `getModel` jest teraz przestarzała + +Funkcja `getModel` jest teraz przestarzała. Teraz możesz używać bezpośrednio właściwości `model`. + +Zmień to: + +```vue {7,9-12} +// Incorrecto ❌ + + + +``` + +Na to: + +```vue {7,9-12} +// Poprawne ✅ + + + +``` + +### Kamery powinny być umieszczone przed jakimkolwiek kontrolerem 🎥 + +Komponent `TresOrbitControls` powinien znajdować się po kamery w drzewie komponentów. Wynika to z tego, że kontrolery muszą znać kamerę, aby działać. + +Zmień to: + +```vue {3,5} +// Niepoprawne ❌ + +``` + +Na to: + +```vue {3,5} +// Poprawne ✅ + +``` + +## UseTres teraz to useTresContext + +Dla wersji 3, przeorganizowaliśmy całą logikę stanu, aby była bardziej elastyczna i przyjazna dla autorów dodatków i pakietów ekosystemu. Zamiast korzystać ze sklepu, jak w wersji 2, teraz używamy dostawcy kontekstu opartego na `provide/inject`. + +Funkcja `useTres` teraz jest aliasem funkcji `useTresContext`, aby uniknąć psucia istniejących demo i eksperymentów, ale rozważ korzystanie z `useTresContext` od teraz. + +Zamiast uzyskiwać duży obiekt reaktywny, teraz bezpośrednio uzyskasz odniesienia do `scene` i `renderer`, między innymi właściwości. + +Zmień to: + +```ts {2} +// Incorrecto ❌ +import { useTres } from "@tresjs/core"; + +const { state, setState } = useTres(); + +console.log(state.scene); +``` + +Na to: + +```ts {2} +// Correcto ✅ +import { useTresContext } from "@tresjs/core"; + +const { scene, renderer } = useTresContext(); + +console.log(scene.value); +``` + +Aby uzyskać bardziej szczegółowe informacje na temat nowego systemu dostawcy kontekstu, możesz przeczytać sekcję [API DOCS](/api/composables.md). diff --git a/docs/pl/guide/nuxt.md b/docs/pl/guide/nuxt.md new file mode 100644 index 000000000..275d6cc48 --- /dev/null +++ b/docs/pl/guide/nuxt.md @@ -0,0 +1,58 @@ +# Nuxt module `@tresjs/nuxt` + +![TresJS Nuxt Module](/nuxt-stones.png) + +npm package + +Oficjalny moduł Nuxt dla TresJS jest już dostępny! 🎉. + +Repozytorium znajduje się [tutaj](https://github.com/Tresjs/nuxt) + +## Instalacja + +::: code-group + +```bash [pnpm] +pnpm add three @tresjs/nuxt +``` + +```bash [npm] +npm install three @tresjs/nuxt +``` + +```bash [yarn] +yarn add three @tresjs/nuxt +``` + +::: + +## Zalety + +- 🤓 Automatyczne importowanie komponentów i komponowalnych elementów z [ekosystemu TresJS](https://github.com/orgs/Tresjs/repositories) +- `TresCanvas` jest dostępny tylko po stronie klienta, nie trzeba dodawać .client do nazwy komponentu ani `` +- Automatyczna konfiguracja kompilatora Vue w celu obsługi komponentów TresJS, zobacz [dlaczego](/guide/troubleshooting.html#failed-resolve-component-trescomponent-%F0%9F%A4%94)? +- Cała magia związana z DX, która jest dostępna w Nuxt ✨ + +## Użycie + +Dodaj `@tresjs/nuxt` do sekcji `modules` w pliku `nuxt.config.ts` + +```js +export default defineNuxtConfig({ + modules: ["@tresjs/nuxt"], +}); +``` + +To wszystko! Teraz możesz korzystać z `@tresjs/nuxt` w swojej aplikacji Nuxt ✨ + +Jeśli chcesz używać pakietów z ekosystemu TresJS, możesz zainstalować wybrane pakiety, a moduł automatycznie je zaimportuje 🧙🏼‍♂️. + +| Package | Version | +| ------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------- | +| [Cientos](https://github.com/Tresjs/cientos) | ![cientos version](https://img.shields.io/npm/v/@tresjs/cientos/latest.svg?label=%20&color=%23f19b00) | +| [Post-processing](https://github.com/Tresjs/post-processing) | ![post-processing version](https://img.shields.io/npm/v/@tresjs/post-processing/latest.svg?label=%20&color=ff69b4) | + +```bash +# Usando pnpm +pnpm add @tresjs/cientos @tresjs/post-processing +``` diff --git a/docs/pl/guide/troubleshooting.md b/docs/pl/guide/troubleshooting.md new file mode 100644 index 000000000..8271beedf --- /dev/null +++ b/docs/pl/guide/troubleshooting.md @@ -0,0 +1,88 @@ +# Zabawny przewodnik po często spotykanych problemach i jak je rozwiązywać + +![Rozwiązywanie problemów](https://media.giphy.com/media/LHZyixOnHwDDy/giphy.gif) + +Witaj w przewodniku po rozwiązywaniu problemów z **TresJS v2**. Gdzie 3D oznacza _"Dumne, Rozkoszne Trudności"_! Wiemy, że 3D może być równie skomplikowane jak spleciona kłębówka wełny 🧶 albo nieprzewidywalne jak kot na klawiaturze 🐈 ⌨️, ale nie bój się! + +Ten przewodnik ma na celu pomóc ci rozwiązać najczęstsze problemy, z jakimi możesz się spotkać podczas korzystania z TresJS v2. + +## Nie widzę mojej sceny 3D 😭! + +Postępowałeś zgodnie z [przewodnikiem rozpoczęcia](/guide/getting-started.md), ale nadal nie widzisz renderowanej sceny. + +Oto najczęstsze powody, dla których możesz nie widzieć swojej sceny: + +### Sprawdź wysokość twojego płótna 📏 + +Innym częstym problemem jest to, że komponent `TresCanvas` domyślnie tworzy element `canvas`, który przyjmuje `width` i `height` od elementu nadrzędnego. Jeśli element nadrzędny nie ma wysokości, to kanwa również jej nie będzie miała. + +![Brak wysokości](/canvas-height.png) + +Zobaczysz także ten błąd w konsoli: + +![Ostrzeżenie o wysokości płótna](/canvas-height-warning.png) + +Łatwym sposobem na rozwiązanie tego problemu jest ustawienie wysokości elementu nadrzędnego na `100%`: + +```css +html, +body { + margin: 0; + padding: 0; + height: 100%; + width: 100%; +} +#app { + height: 100%; + width: 100%; + background-color: #000; +} +``` + +O także możesz ustawić właściwość `window-size` komponentu `TresCanvas`: + +```vue + + + + +``` + +## Błąd rozwiązania komponentu: TresComponent... + +![](/failed-to-resolve-component.png) + +Ponieważ **TresJS v2** używa niestandardowego renderera Vue w głównej instancji aplikacji Vue, główny renderer Vue, który działa jako rodzic, nie rozpozna komponentów wewnątrz komponentu `TresCanvas`. Chociaż nie wpływa to na renderowanie, spowoduje wyświetlenie ostrzeżenia w konsoli. + +![](/failed-to-resolve-component.png) + +Obecnie Vue nie obsługuje natywnie definiowania renderera używanego w znaczniku `