diff --git a/astro.config.mjs b/astro.config.mjs index 1da5e7a..0df68c8 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -3,6 +3,7 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; import coherentTheme from 'coherent-docs-theme'; import { content } from './src/data/content'; +import starlightAutoSidebar from 'starlight-auto-sidebar' export default defineConfig({ integrations: [ @@ -21,10 +22,12 @@ export default defineConfig({ }, ], plugins: [ - ...coherentTheme({ - documentationSearchTag: 'UI workflow guide', - showPageProgress: true, - })], + ...coherentTheme({ + documentationSearchTag: 'UI workflow guide', + showPageProgress: true, + }), + starlightAutoSidebar() + ], customCss: ['./src/styles/custom.css'], sidebar: content.map((topic) => { return { diff --git a/public/resources/phase-two/inventory-prototype-assets.zip b/public/resources/phase-two/inventory-prototype-assets.zip new file mode 100644 index 0000000..703fdb9 Binary files /dev/null and b/public/resources/phase-two/inventory-prototype-assets.zip differ diff --git a/src/assets/houston.webp b/src/assets/houston.webp deleted file mode 100644 index 930c164..0000000 Binary files a/src/assets/houston.webp and /dev/null differ diff --git a/src/assets/phase-2/prototyping-and-developing/HMR-preview.webm b/src/assets/phase-2/prototyping-and-developing/HMR-preview.webm new file mode 100644 index 0000000..f491513 Binary files /dev/null and b/src/assets/phase-2/prototyping-and-developing/HMR-preview.webm differ diff --git a/src/assets/phase-2/prototyping-and-developing/gameface-ui-menu-preview.webm b/src/assets/phase-2/prototyping-and-developing/gameface-ui-menu-preview.webm new file mode 100644 index 0000000..0cc0c23 Binary files /dev/null and b/src/assets/phase-2/prototyping-and-developing/gameface-ui-menu-preview.webm differ diff --git a/src/assets/phase-2/prototyping-and-developing/inventory-view.png b/src/assets/phase-2/prototyping-and-developing/inventory-view.png new file mode 100644 index 0000000..240a736 Binary files /dev/null and b/src/assets/phase-2/prototyping-and-developing/inventory-view.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/grid-finished-preview.png b/src/assets/phase-2/the-prototyping-workflow/grid-finished-preview.png new file mode 100644 index 0000000..6c62133 Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/grid-finished-preview.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/grid-preview.png b/src/assets/phase-2/the-prototyping-workflow/grid-preview.png new file mode 100644 index 0000000..6b47418 Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/grid-preview.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/inventory-finished.png b/src/assets/phase-2/the-prototyping-workflow/inventory-finished.png new file mode 100644 index 0000000..eae56f7 Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/inventory-finished.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/inventory-left-column-preview.webm b/src/assets/phase-2/the-prototyping-workflow/inventory-left-column-preview.webm new file mode 100644 index 0000000..2cd2e0c Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/inventory-left-column-preview.webm differ diff --git a/src/assets/phase-2/the-prototyping-workflow/inventory-wireframe.png b/src/assets/phase-2/the-prototyping-workflow/inventory-wireframe.png new file mode 100644 index 0000000..f669d2d Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/inventory-wireframe.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/item-inspector-1.png b/src/assets/phase-2/the-prototyping-workflow/item-inspector-1.png new file mode 100644 index 0000000..2f7ecac Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/item-inspector-1.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/item-inspector-2.png b/src/assets/phase-2/the-prototyping-workflow/item-inspector-2.png new file mode 100644 index 0000000..0280b59 Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/item-inspector-2.png differ diff --git a/src/assets/phase-2/the-prototyping-workflow/item-inspector-3.png b/src/assets/phase-2/the-prototyping-workflow/item-inspector-3.png new file mode 100644 index 0000000..17550ca Binary files /dev/null and b/src/assets/phase-2/the-prototyping-workflow/item-inspector-3.png differ diff --git a/src/content.config.ts b/src/content.config.ts index d9ee8c9..b2056de 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -1,7 +1,13 @@ import { defineCollection } from 'astro:content'; import { docsLoader } from '@astrojs/starlight/loaders'; import { docsSchema } from '@astrojs/starlight/schema'; +import { autoSidebarLoader } from 'starlight-auto-sidebar/loader' +import { autoSidebarSchema } from 'starlight-auto-sidebar/schema' export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), + autoSidebar: defineCollection({ + loader: autoSidebarLoader(), + schema: autoSidebarSchema(), + }), }; diff --git a/src/content/docs/Polishing/accessibility.mdx b/src/content/docs/Polishing/accessibility.mdx new file mode 100644 index 0000000..5d2cd15 --- /dev/null +++ b/src/content/docs/Polishing/accessibility.mdx @@ -0,0 +1,6 @@ +--- +title: Accessibility +description: Learn how to make your game UI accessible to all players using Gameface's built-in accessibility features. This section covers best practices for implementing screen reader support, keyboard navigation, and localization to ensure your UI is inclusive and reaches a wider audience. +sidebar: + order: 1 +--- \ No newline at end of file diff --git a/src/content/docs/core-concepts/hello-world.mdx b/src/content/docs/core-concepts/hello-world.mdx deleted file mode 100644 index 8a7b9e2..0000000 --- a/src/content/docs/core-concepts/hello-world.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Hello World" -description: "Your first steps into the world of Gameface development. Learn how to set up your environment, create a simple 'Hello World' interface, and understand the basics of Gameface's architecture." ---- - -Placeholder content for the "Hello World" guide. This section will cover the initial setup and creation of a simple interface using Gameface. Stay tuned for updates! \ No newline at end of file diff --git a/src/content/docs/ecosystem-tools/hello-world.mdx b/src/content/docs/ecosystem-tools/hello-world.mdx deleted file mode 100644 index 8a7b9e2..0000000 --- a/src/content/docs/ecosystem-tools/hello-world.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Hello World" -description: "Your first steps into the world of Gameface development. Learn how to set up your environment, create a simple 'Hello World' interface, and understand the basics of Gameface's architecture." ---- - -Placeholder content for the "Hello World" guide. This section will cover the initial setup and creation of a simple interface using Gameface. Stay tuned for updates! \ No newline at end of file diff --git a/src/content/docs/introduction/hello-world.mdx b/src/content/docs/introduction/hello-world.mdx deleted file mode 100644 index 8a7b9e2..0000000 --- a/src/content/docs/introduction/hello-world.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Hello World" -description: "Your first steps into the world of Gameface development. Learn how to set up your environment, create a simple 'Hello World' interface, and understand the basics of Gameface's architecture." ---- - -Placeholder content for the "Hello World" guide. This section will cover the initial setup and creation of a simple interface using Gameface. Stay tuned for updates! \ No newline at end of file diff --git a/src/content/docs/phase-1-getting-started/getting-started-with-the-player.mdx b/src/content/docs/phase-1-getting-started/getting-started-with-the-player.mdx new file mode 100644 index 0000000..de24491 --- /dev/null +++ b/src/content/docs/phase-1-getting-started/getting-started-with-the-player.mdx @@ -0,0 +1,68 @@ +--- +title: Getting Started with the Player +description: Learn how to use the Player, Gameface's primary tool for running and testing your UI without needing an engine. This hands-on demo will guide you through the basics of setting up and using the Player to streamline your development workflow. +sidebar: + order: 2 +draft: true +--- +import Summary from '../../../components/Summary.astro'; +import Highlight from '../../../components/Highlight.astro'; +import { Steps } from '@astrojs/starlight/components'; + + + The biggest bottleneck in traditional game UI development is the engine. Waiting for Unreal or Unity to compile just to see if a UI widget is centered or a health bar updates ruins iteration speed. + + Enter the Gameface Player. + + The Player is a lightweight, standalone version of the Gameface rendering engine. + It allows you to drag and drop your HTML files and see them render exactly as they would in the game. It is the ultimate tool for rapid UI prototyping & development. + + +## Download the Player + +Before we can test anything, you need the Player running on your machine. + +:::note[Download Link Placeholder] +[Click here to download the latest version of the Gameface Player](#) *(Note: Link will be updated when the demo environment goes live).* +::: + +Once downloaded and extracted, launch the `Player.exe` (or the equivalent executable for your OS). You don't need to configure any complex backend settings—just open it up and let's get building. + +## Hands-On: Exploring the Demo Environment + +When you first launch the Player, you will be greeted by the **Home Page**, which features a menu of pre-built UI samples. This is the perfect sandbox to see what Gameface is capable of right out of the box. + + + +1. #### **Play with a Sample** + From the Home Page, click on one of the featured samples. + + *[Placeholder: Briefly describe the specific sample here once it is live, e.g., "Open the Inventory sample to see a fully animated drag-and-drop grid, or the HUD sample to see a live minimap and compass."]* Take a moment to click around. Notice how fluid the animations are and how instantly the UI responds. This is all running on standard web technologies, powered by the Gameface renderer. + +2. #### **Navigate to the Demo Page** + Once you are done exploring the samples, head over to the **"Demo"** page using the main navigation. + + This page is designed to isolate and showcase the specific technical features of Gameface. It is an interactive playground where you can tweak values and see the engine react in real-time. + +3. #### **Test Live Data-Binding** + The first feature you will see on the Demo page is **Data-Binding**. In a real game, data coming from the engine (like player health or ammo) is bound to your HTML elements and displayed on the page in real-time. Here, we are simulating that live connection. + + * **The UI Element:** On the right side of the screen, you will see a visual element (like a health bar or a character stat block). + * **The Controls:** On the left side, you will find a series of input fields and sliders. + + Try changing the values in the inputs on the left. You will see the UI element on the right update instantly. You are actively modifying the data-bound attributes of the element, proving that you can fully test your UI's logic and data states without ever waiting for a backend programmer to hook up the real game data. + +4. #### **Explore the Next Features** + Data-binding is just the beginning. At the top of the Demo page, you will find a **dropdown menu**. Use this to switch to the next Gameface feature sandbox. + + *[Placeholder: Add a quick sentence about the next feature once decided, e.g., "Switch to the 'Live Views' tab to see how Gameface renders 3D engine textures directly onto a 2D DOM element, or check out the 'Spatial Navigation' demo."]* + + + +## Your Turn + +Feel free to spend some time exploring the rest of the dropdown features on the Demo page. The Player is designed to be your primary workspace. Whenever you write new UI code, this is where you will preview it. + +Once you are comfortable navigating the Player and seeing how it renders standard web code, it's time to learn how to fix things when they break. + +In the next article, we will introduce the **Gameface Inspector**—your standalone debugging tool for checking the DOM, tweaking CSS, and tracking down JavaScript errors. \ No newline at end of file diff --git a/src/content/docs/phase-1-getting-started/introduction.mdx b/src/content/docs/phase-1-getting-started/introduction.mdx new file mode 100644 index 0000000..fcebb27 --- /dev/null +++ b/src/content/docs/phase-1-getting-started/introduction.mdx @@ -0,0 +1,103 @@ +--- +title: "Introduction: Welcome to the UI workflow guide" +description: "Your first steps into the world of Gameface development. Learn how to set up your environment, create a simple 'Hello World' interface, and understand the basics of Gameface's architecture." +sidebar: + order: 1 +--- + +import Summary from '../../../components/Summary.astro'; +import Highlight from '../../../components/Highlight.astro'; +import { Steps } from '@astrojs/starlight/components'; + + + Welcome to the Gameface UI workflow guide! + + This guide is designed to take you from zero to hero in Gameface development, covering everything from the basics of setting up your environment to advanced performance optimization techniques. + Whether you're a seasoned front-end developer, a game designer, or a gameplay programmer stepping into the UI world, this guide will provide you with the exact knowledge and tools you need to create stunning, high-performance interfaces for games. + + +## What to Expect in This Guide + +This guide is structured chronologically to match the typical phases of the development process. Each phase builds on the previous one, so it's recommended to follow along in order. + +Here's a brief overview of what we'll cover in each phase: + + + +1. #### **Phase 1: Getting Started** + Introduction to the guide and Gameface. Get a hands-on demo with the Player, the primary tool for running and testing your UI without needing to compile a game engine. + +2. #### **Phase 2: Planning & Setup** + Configuring your development environment, establishing your recommended tech stack (like SolidJS and Vite), and understanding how data flows between the game and the UI. + + This phase covers core concepts like "push vs. fetch", how to organize your views, and bridging the gap between design and development + using tools like the [Figma Exporter](https://www.figma.com/community/plugin/1595556380268929590/coherent-gameface-exporter). + + We also bridge to prototyping by introducing [Gameface UI](https://gameface-ui.coherent-labs.com/)—our component library that makes prototyping fast and easy. + +3. #### **Phase 3: Layout, Assets & Styling** + The fun part! We cover how to translate designs into clean, scalable game UIs. + + You will learn when to use absolute versus flex layouts, write maintainable and performant CSS using BEM & SCSS, and build interfaces that scale perfectly across different aspect ratios. + + We also explore best practices for handling complex typography, rendering vector graphics and assets, and bringing your UI to life with high-performance animations. + +4. #### **Phase 4: Logic & Interactions** + Now that you have a beautiful UI, it's time to make it interactive! + + In this phase, we bridge the gap between static UI and information-rich, dynamic interfaces. + + We cover how to mock real game data to test your UI independently, + manage local versus game state using data-binding, + and handle complex user inputs like gamepad, touch support, and spatial navigation using the [Interaction Manager](https://frontend-tools.coherent-labs.com/interaction-manager/getting-started/). + +5. #### **Phase 5: Polishing & Debugging** + The final 10%. We cover how to polish your UI to make it feel smooth, accessible, bug-free, and most importantly, performant. + + Learn how to implement native localization and accessibility features, master the performance profiler, and write high-performance CSS. + + We also deep-dive into advanced, Gameface-exclusive rendering features like Live Views, Compositor effects, and backdrop filters. + + +## What You Won't Find in This Guide + +To keep this guide lean and focused on UI creation, we have intentionally excluded backend development. You will not find: +* C++ tutorials or engine-specific integration steps (Unreal, Unity, or custom engines). +* Deep dives into the Gameface API. +* Instructions on how to compile or initialize the Gameface library within your game. + +*If you are a backend programmer looking for engine integration, please refer to the [official Gameface technical documentation](https://docs.coherent-labs.com/cpp-gameface/).* + +## Your Content Creation Reference + +Think of this guide as your long-term UI playbook. While it is structured as a chronological course for beginners, it is ultimately designed to be your daily reference manual. + +Want to localize your UI? Jump straight to the *Localization* section. +Trying to remember how to handle ultrawide monitors? Check the *Scalability* page. +Need to set up a new animation library? Head over to *Animations*. + +Keep this guide bookmarked and refer back to it whenever you hit a UI roadblock. + +:::note[Structure is not mandatory] +While the guide is structured in a way that builds on previous knowledge, feel free to jump around and explore the sections that interest you the most. + +Each section is designed to be self-contained, so you can pick and choose the topics that are most relavant to your current project's progress or just for quick reference. +::: + +## Who Is This Guide For? + +**Short answer**: Everyone working with Gameface! + +Because team structures vary wildly, we built this guide for a wide range of skill sets. +Whether you are a seasoned front-end developer using Gameface for the first time, a UI/UX designer looking to understand the engine's capabilities, or a Unity/Unreal gameplay programmer +who has never worked with web technologies before—this guide has something for you. + +## Next Steps + +Ready to dive in? Proceed to the [next topic](/phase-1-getting-started/getting-started-with-the-player) where we will introduce you to the Player. +We will get our hands dirty with a quick demo showcasing how to run, test, and update game data in your UI without needing a backend engine! + +### Need more convincing? + +- Read more about what [Gameface is](https://docs.coherent-labs.com/cpp-gameface/what_is_gfp/overview/) - for a technical overview. +- Check out the main differences between Gameface and a traditional browser environment in our [Differences to traditional browsers](https://docs.coherent-labs.com/cpp-gameface/what_is_gfp/htmlfeaturesupport/) documentation. \ No newline at end of file diff --git a/src/content/docs/phase-1-getting-started/working-separately-from-the-game.mdx b/src/content/docs/phase-1-getting-started/working-separately-from-the-game.mdx new file mode 100644 index 0000000..6072066 --- /dev/null +++ b/src/content/docs/phase-1-getting-started/working-separately-from-the-game.mdx @@ -0,0 +1,70 @@ +--- +title: "Working Separately from the Game" +description: "Learn how to debug your game UI, tweak CSS, and test JavaScript logic using the standalone Gameface Inspector." +sidebar: + order: 3 +draft: true +--- + +import Summary from '../../../components/Summary.astro'; +import Highlight from '../../../components/Highlight.astro'; +import { Steps } from '@astrojs/starlight/components'; + + + In the previous article, you loaded your HTML file into the Player and watched it run perfectly. But what happens when things go wrong? What if a layout breaks, or a data-bound value isn't updating? + + If you have ever done traditional web development, we have great news: **you do not need to learn a proprietary game engine debugger.** + + Gameface uses the standard Chrome DevTools. You get the exact same inspection power and JavaScript debugging as a web browser, completely independent of the game engine. + + +## The Standalone Workflow + +The core philosophy of Gameface development is **separation of concerns**. + +You should never have to ask a gameplay programmer to recompile the Unreal or Unity engine just so you can change the color of a health bar. By pairing the **Player** (to render your HTML) with the **DevTools Inspector** (to debug it), you unlock a completely independent, rapid-iteration workflow. + +Write code in your IDE → See it update in the Player → Debug it in the Inspector. + +## Hands-On: Launching the Inspector + +Let's see how it works by inspecting the Demo page you were just playing with. + + + +1. #### **Keep the Player Running** + Make sure you still have the Player open and running the Demo page from the previous article. + +2. #### **Open the DevTools** + To open the Inspector, simply press F12 on your keyboard, or right-click anywhere inside the Player window and select **"Inspect"**. + +3. #### **Explore the Interface** + A new window will pop up. If you have ever used Google Chrome to build a website, you will instantly recognize this interface. It is fully equipped to debug your UI's DOM, styling, and logic. + + + +## A Quick Tour of the Tools + +While the Inspector contains all the standard web debugging features, Gameface includes a few custom additions specifically tailored for game UI. + +Here are the primary panels you will use daily: + +### 1. The Elements Panel +This is your layout laboratory. Here you can see the live DOM tree of your loaded HTML file. +* Click on any element to view its active CSS rules. +* Live Edit: Double-click a CSS property (like `width` or `background-color`) and change it. You will see the UI in the Player update instantly. This is the fastest way to polish designs without constantly saving and reloading files. + +### 2. The Console & Sources +This is the brain monitor. If you have a typo in your JavaScript, it will show up here in bright red. You can use the Console to manually type JavaScript commands to trigger UI events, or use the Sources tab to set standard breakpoints in your code and step through your logic line by line. + +### 3. The Custom Data-Bind Panel +Because Gameface relies heavily on data-binding to communicate with the game engine, we added a custom panel just for this workflow. +When you select an element in the DOM tree, you can use the Data-Bind tab to inspect exactly how its data-bound properties (like a dynamic health value or an inventory array) are updating in real-time. *(Don't worry, we will deep-dive into how to use this panel effectively in Phase 4: Logic & Interactions).* + +## Wrapping Up Phase 1 + +Congratulations! You now understand the fundamental Gameface workflow. You know how to load an HTML file into the Player, test live data-binding, and open the DevTools to debug your code—all without touching a single line of C++. + +You are now ready to build a real project. + +**Next up:** Proceed to [Phase 2: Planning & Setup](/phase-2-planning-and-setup/development-environment-and-tools). We will walk through configuring VS Code, installing Gameface-specific linters, and establishing our recommended modern tech stack (Vite + SolidJS). \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/_meta.yml b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/_meta.yml new file mode 100644 index 0000000..447bfac --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/_meta.yml @@ -0,0 +1,2 @@ +order: 3 +collapsed: true \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/preact-setup.mdx b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/preact-setup.mdx new file mode 100644 index 0000000..132d48d --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/preact-setup.mdx @@ -0,0 +1,13 @@ +--- +title: Setting up a Preact Project +description: Learn how to scaffold a modern Vite + Preact project and configure it to run perfectly within Gameface. +sidebar: + order: 2 +draft: true +--- + +- Degit or install with CLI the vite react gameface template + +- Go over the structure and how to run and build the project + +- Cover some important caveats about the framework in Gameface \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/react-setup.mdx b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/react-setup.mdx new file mode 100644 index 0000000..b6834cb --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/react-setup.mdx @@ -0,0 +1,14 @@ +--- +title: Setting up a React Project +description: Learn how to scaffold a modern Vite + React project and configure it to run perfectly within Gameface. +sidebar: + order: 1 +draft: true +--- + +- Degit or install with CLI the vite react gameface template + +- Go over the structure and how to run and build the project + +- Cover some important caveats about the framework in Gameface + diff --git a/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/svelte-setup.mdx b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/svelte-setup.mdx new file mode 100644 index 0000000..e45ad8d --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/svelte-setup.mdx @@ -0,0 +1,13 @@ +--- +title: Setting up a Svelte5 Project +description: Learn how to scaffold a modern Vite + Svelte5 project and configure it to run perfectly within Gameface. +sidebar: + order: 3 +draft: true +--- + +- Degit or install with CLI the vite react gameface template + +- Go over the structure and how to run and build the project + +- Cover some important caveats about the framework in Gameface \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/vue-setup.mdx b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/vue-setup.mdx new file mode 100644 index 0000000..2250a51 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Alternative Frameworks/vue-setup.mdx @@ -0,0 +1,13 @@ +--- +title: Setting up a Vue Project +description: Learn how to scaffold a modern Vite + Vue project and configure it to run perfectly within Gameface. +sidebar: + order: 4 +draft: true +--- + +- Degit or install with CLI the vite react gameface template + +- Go over the structure and how to run and build the project + +- Cover some important caveats about the framework in Gameface \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Design Work/_meta.yml b/src/content/docs/phase-2-planning-and-setup/Design Work/_meta.yml new file mode 100644 index 0000000..0eed315 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Design Work/_meta.yml @@ -0,0 +1,2 @@ +order: 6 +collapsed: true \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Design Work/animations.mdx b/src/content/docs/phase-2-planning-and-setup/Design Work/animations.mdx new file mode 100644 index 0000000..4764738 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Design Work/animations.mdx @@ -0,0 +1,40 @@ +--- +title: "Animations: Mockup and Handoff" +description: A translation guide for Unity developers leaving UGUI or UI Toolkit. +sidebar: + order: 3 +draft: true +--- + +import Summary from '../../../../components/Summary.astro'; +import Highlight from '../../../../components/Highlight.astro'; + + +A static mockup only tells half the story. To ensure your UI feels responsive and alive, designers need to properly concept and hand off animations. In this article, we discuss how to mock up animations and the best technologies for implementing them in Gameface. + + + +## Need to make a research... + + +## Designing for Performance +When mocking up animations, it is crucial to understand the tools the developer will use to implement them. Gameface animations can be created using standard CSS Animations or JavaScript libraries. + +When communicating your animation ideas to the dev team, keep these performance realities in mind: + +- CSS Transitions & Keyframes: CSS animations are more performant and should be your go-to for standard UI micro-interactions (like a button hover, a panel sliding in, or a simple fade). +- JavaScript Libraries: JS animations offer greater control for highly complex sequencing, but they come with a performance cost. +- Lottie: Lottie Animations, created in Adobe After Effects, are fully supported. This is often the best bridge for complex vector animations, as the designer can export the exact JSON file for the developer to drop into the project. + +## Handoff Best Practices +When handing off an animation mockup to a developer: + +1. Provide Reference Video: A simple MP4 or GIF of the intended interaction goes a long way. + +2. Define Timing: Explicitly state the duration, easing curves (e.g., ease-in-out), and any delays. + +3. Deliver Lottie JSON: If using After Effects, do not hand off an .mp4 for the final game asset. Export the .json using the Bodymovin plugin so it can be rendered natively. + +:::caution +Be cautious with CSS transitions during DOM insertion! Transitions often fail if an element's display changes simultaneously. Developers will usually need to leverage @starting-style to handle mount animations safely. +::: diff --git a/src/content/docs/phase-2-planning-and-setup/Design Work/arranging-your-designs.mdx b/src/content/docs/phase-2-planning-and-setup/Design Work/arranging-your-designs.mdx new file mode 100644 index 0000000..14e7d97 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Design Work/arranging-your-designs.mdx @@ -0,0 +1,9 @@ +--- +title: "Arranging Your Designs" +description: A translation guide for Unity developers leaving UGUI or UI Toolkit. +sidebar: + order: 1 +draft: true +--- + +Need to make a research... \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Design Work/figma-exporter.mdx b/src/content/docs/phase-2-planning-and-setup/Design Work/figma-exporter.mdx new file mode 100644 index 0000000..48001de --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Design Work/figma-exporter.mdx @@ -0,0 +1,13 @@ +--- +title: "Figma Exporter" +description: Introduction to the official Figma to Gameface design exporter plugin, and how to use it to export your designs into Gameface projects. +sidebar: + order: 2 +draft: true +--- + +- Introduce the figma exporter as a way for designers to quickly preview their designs in gameface +- Go over its features +- Explain whats different about exporting to gameface vs the browser and that exported design should be looked at in the Player not the browser. +- Explain that the plugin is new and there may be some inconsistencies +- Show how to run it, export a UI and Preview it in the Player diff --git a/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/_meta.yml b/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/_meta.yml new file mode 100644 index 0000000..894b5d9 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/_meta.yml @@ -0,0 +1,2 @@ +order: 2 +collapsed: true \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/recommended-teck-stack-overview.mdx b/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/recommended-teck-stack-overview.mdx new file mode 100644 index 0000000..8e647b2 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/recommended-teck-stack-overview.mdx @@ -0,0 +1,98 @@ +--- +title: "Recommended Tech Stack Overview" +description: "Discover the core technologies behind Gameface UI development. Learn why we recommend SolidJS, Vite, SCSS, and TypeScript for maximum game UI performance." +sidebar: + order: 1 +--- +import Summary from '../../../../components/Summary.astro'; +import Highlight from '../../../../components/Highlight.astro'; +import Link from '../../../../components/Link.astro'; +import { Icon } from '@astrojs/starlight/components'; + + + The choice of technology stack is a critical decision at the outset of any project, as it can influence multiple factors including performance, development time, and scalability. + + While traditional web developers often default to frameworks like React or Angular, game UI requires a different approach. Heavy runtimes, Virtual DOM diffing, and CSS-in-JS libraries can steal precious milliseconds from the game engine. + + To achieve the perfect balance between modern developer experience and raw performance, our officially recommended tech stack is + + SolidJS, + Vite, + SCSS (with BEM), + and TypeScript. + + +## Why Not Vanilla JavaScript? + +Choosing between using vanilla JavaScript (plain JavaScript) and a JavaScript framework is an important decision when starting your project. Vanilla JavaScript gives you complete control over the code, which can be an advantage for fine-tuning performance and behavior. + +However, as your project grows, building complex features from scratch can be time-consuming, potentially extending project timelines. Managing and maintaining a large codebase can become challenging without the organization and structure provided by a framework. Frameworks offer tools and features that streamline development and speed up the creation of complex applications. They also provide predefined architecture and patterns that help maintain a well-organized codebase. + +To get the organization of a framework without sacrificing the speed of Vanilla JS, we rely on SolidJS. + +## The Framework: SolidJS + +Our research and testing have revealed that SolidJS currently stands out as the optimal choice for achieving both high performance and scalability. + +If you are coming from traditional web development, SolidJS has a very similar syntax to React. However, under the hood, it operates entirely differently to maximize efficiency: + +* **No Virtual DOM:** Unlike React, SolidJS does not use a virtual DOM. Instead, it compiles templates to real DOM operations, leading to better performance and more predictable behavior. +* **Fine-Grained Reactivity:** SolidJS is engineered for high performance. It employs fine-grained reactivity, updating only the necessary parts of the DOM, resulting in faster rendering and lower memory usage compared to frameworks like React. +* **Vanilla-Like Speed:** Because it skips the Virtual DOM overhead, SolidJS achieves a level of performance that is incredibly close to writing pure vanilla JavaScript. + +:::note[Alternative Frameworks] +While Gameface does support other frameworks like React, Vue, and Preact, they rely on Virtual DOMs or heavier runtimes that can impact game performance. You can find setup guides for these in the +[Alternative Frameworks section](). +::: + +## The Bundler: Vite + +A bundler is a tool or software application that is used to combine multiple source files into a single, optimized bundle. For Gameface, our build tool of choice is Vite. + +Vite is a modern build tool and development server designed for web development. We chose it over older tools like Webpack for several key reasons: +* **Native ESM:** Vite natively supports ES modules without bundling during development, resulting in quicker build times. +* **Instant Updates:** Vite offers HMR by default, making it easy for developers to see changes in real-time during development. +* **Plugin System**: Vite provides a flexible plugin system, enabling customization and extensibility. + +## Styling: SCSS, BEM, and Modularity + +In a game engine, complex (hierarchical) selectors are expensive to match. To maintain high frame rates, your CSS classes need to be as "flat" as possible. + +We tackle this using a combination of SCSS and the BEM (Block Element Modifier) methodology: + +* **The BEM Methodology:** The BEM methodology is recommended for writing HTML classes, as it promotes style isolation and helps reduce CSS conflicts. Additionally, it can help prevent performance issues that may arise from writing too many complex CSS selectors in Gameface. +* **SCSS & Flat Selectors:** To write clearer and more concise selectors, consider using a CSS preprocessor with the BEM methodology. SASS is a recommended option that has a syntax similar to traditional CSS. It also offers highly useful features like variables and functions, and has a large community with many resources. + +:::note[Alternative Styling Approaches] +In general, strict BEM can result in longer class names, which might affect code readability in your HTML. You can opt for a more relaxed version of BEM that allows for shorter class names and clean nesting. + +For example, instead of writing `.dropdown__option--active`, you could write `.dropdown-option--active` or even `.dropdown-option-active`. +You can leverage scoped SolidJS [CSS Modules](https://docs.solidjs.com/guides/styling-components/css-modules) and SCSS's nesting capabilities to keep your styles scoped and organized while still compiling down to engine-friendly flat selectors. + +```scss +.dropdown { + &-option { + /* Compiles to .dropdown-option */ + &--active { + /* Compiles to .dropdown-option--active */ + color: red; + } + } +} +``` + +We will deep-dive into the nuances of BEM, CSS Modules, and writing high-performance styles later in [Phase 3: Layout, Assets & Styling](#). +::: + +## The Safety Net: TypeScript + +Finally, we highly recommend writing your UI logic in TypeScript. + +TypeScript definitions and documentation provide strong typing and enhanced tooling for your JavaScript code within the Gameface environment. +Because your UI will be communicating heavily with a C++ backend via data-binding, this ensures you catch data-shape errors in your IDE before your UI ever touches the game engine. + +## Next Steps + +Now that you understand the "Why" behind our tech stack, it is time for the "How". + +In the next article, we will walk through setting up your development environment and initializing your first Vite + SolidJS project specifically configured for the Gameface engine. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/setting-up-the-gameface-stack.mdx b/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/setting-up-the-gameface-stack.mdx new file mode 100644 index 0000000..8a21f38 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Recommended Tech Stack/setting-up-the-gameface-stack.mdx @@ -0,0 +1,127 @@ +--- +title: "Setting up the Gameface Stack" +description: "Learn how to scaffold a modern Vite + SolidJS project and configure it to run perfectly within the Gameface engine." +sidebar: + order: 2 +--- + +import Summary from '../../../../components/Summary.astro'; +import Highlight from '../../../../components/Highlight.astro'; +import Link from '../../../../components/Link.astro'; +import { Steps } from '@astrojs/starlight/components'; +import { Code } from '@astrojs/starlight/components'; +import { Icon } from '@astrojs/starlight/components'; + + + To get you up and running immediately, we have created pre-configured templates that bypass the manual setup of Vite and SolidJS. + + These templates come with the gameface-specific configurations already applied so your code will render perfectly in the Gameface Player right out of the box. + + +## Prerequisites + +Before we begin, ensure you have the following installed on your machine: +* **Node.js:** We recommend the latest LTS version. +* **A Package Manager:** `npm`, `yarn`, or `pnpm`. +* **VS Code:** Or your preferred text editor. + +## Choose Your Starting Point + +Depending on your project requirements, you can either start with a structured blank project or a fully development ready UI component library. + +To download these starter projects, we use a command line tool called `degit`. +This tool simply grabs a clean copy of the template files from our repository and places them on your computer, without bringing along any messy version control history. + +### Option A: Blank Vite & SolidJS Template +This template includes only the core recommended stack: +Vite, SolidJS, TypeScript & SASS. +It is completely clean, making it the perfect choice if you want to build your own UI architecture and components entirely from scratch. + +Run this command in your terminal to create a new folder called `my-game-ui` and install the blank template: + +```bash +npx degit CoherentLabs/gameface-solid-template my-game-ui +cd my-game-ui +npm install +``` + +Once the installation is complete, you can see how to [preview the project in gameface](#connect-to-the-gameface-player) in the next section. + +### Option B: The Gameface UI project + +If you have limited web experience or want to skip the component creation process, we highly recommend starting with our pre-built +Gameface UI template. +It includes the exact same core technologies, +but comes pre-loaded with a massive library of ready-to-use game components (like buttons, grids, and sliders), layout components for quick prototyping, and others. + +We actively support and maintain this library, adding new components and features based on community feedback. +This is our go to choice for starting new UI projects, and we highly recommend it for prototyping and production projects alike. + +:::note +We will explore more of the features and components of this library in-depth in a later articles. +::: + +To get started with the Gameface UI template, run this command in your terminal: + +```bash +npx degit CoherentLabs/gameface-ui-boilerplate my-game-ui +cd my-game-ui +npm install +``` + +This will create a new folder called `my-game-ui` with the boilerplate code, install all dependencies, and get you ready to start developing your game UI. + +## Connect to the Gameface Player + +Regardless of which option you chose above, the steps to start your local server and view your UI in the Player are exactly the same. + + + +1. #### Start the Development Server + Open your terminal inside your new `my-game-ui` folder and run: + + ```bash + npm run dev + ``` + + This will start a local web server, usually at `http://localhost:3000`. + +2. #### Launch the Player + Instead of viewing your UI in a standard web browser like Chrome, you should view it directly in the Gameface Player to ensure 100% engine accuracy. + + Locate the `Player.bat` file included in your Gameface package. Open the file in a text editor, + scroll down until you see a similar command: + + ```bat + start "Player" /d "%wd%" "..\Player\Player.exe" --player %*" + ``` + + and add the following parameter to the end of the line: + + + + + Save the file and double-click the `.bat` file to launch the Player. It will open and display your SolidJS application. + Because our setup supports Hot Module Replacement (HMR), every time you save a file in your code editor, the Player will instantly update! + + :::caution[Gameface UI URL] + Gameface UI comes with 2 pre built in samples. + If you went with the Gameface UI template, make sure to change the url to `http://localhost:3000/menu` or `/hud` depending on which preset sample you wish to preview. + Otherwise you will see a blank page. + ::: + + + +## Next Steps + +Your local environment is now running smoothly inside the Gameface Player! Where you go next depends on which starter project you chose: + +* **If you chose Option A (The Blank Starter):** Move on to [Workflow Planning](../../workflow-planning). +We will discuss setting up your IDE, version control, and how to translate your mindset from UMG/Unity to web & Gameface technologies. + +* **If you chose Option B (The Gameface UI Library):** Jump right into [Prototyping and Developing (Gameface UI)](../../prototyping-and-developing). +We will explore the Gameface UI's file structure and show you how to rapidly prototype a view using the pre-made components. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/_meta.yml b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/_meta.yml new file mode 100644 index 0000000..e2bcfce --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/_meta.yml @@ -0,0 +1,2 @@ +order: 7 +collapsed: true \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/prototyping-an-inventory-part-one.mdx b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/prototyping-an-inventory-part-one.mdx new file mode 100644 index 0000000..97c2b9b --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/prototyping-an-inventory-part-one.mdx @@ -0,0 +1,603 @@ +--- +title: "Prototyping an Inventory Screen - Part 1: Assets and Layout" +description: "Learn how to quickly prototype an inventory screen using the Gameface UI boilerplate. In this first part, we will set up the project, create a new view, and build the basic layout using pre-built components." +sidebar: + order: 2 +--- + +import Summary from '../../../../components/Summary.astro'; +import Highlight from '../../../../components/Highlight.astro'; +import Link from '../../../../components/Link.astro'; +import { Steps, FileTree } from '@astrojs/starlight/components'; +import leftColumnPreviewVideo from '../../../../assets/phase-2/the-prototyping-workflow/inventory-left-column-preview.webm' + + + In Part 1 of this walkthrough, we will establish the structural foundation of the inventory prototype. + + + 1. We will begin by configuring the project's global styles to ensure the UI scales correctly across different resolutions. + + 2. Next, we will cover how to manage and load custom assets like fonts and SVG icons. + + 3. Finally, we will use Gameface UI's layout components to divide the screen into our three core columns and generate the inventory grid. + + + +## Project Initialization + +Before building the layout, we need to set up the global styles for our view. This includes basic resets and establishing a responsive scaling logic for our units. + +### The Global CSS Reset + +Just like in the browser, Gameface keeps some default styles on elements like `body`, and `h1` or other heading tags. +To ensure a consistent starting point, we apply a global CSS reset that removes default margins, paddings, and sets some rules for our project. + +The best place to do such resets is in the `index.css` file which is the style root for our `inventory` view. + +Put the following code in `src/views/inventory/index.css`: + +```css title='index.css' +h1,h2,h3,h4,h5,h6 { + margin: 0; +} + +body { + width: 100vw; + height: 100vh; + margin: 0; + background-color: black; + color: white; +} +``` + +Adding the `width: 100vw` and `height: 100vh` rules to the body ensures that our view will take up the entire screen space in the Player, regardless of the resolution. + +:::tip +Doing the resets in the `index.css` files allows for easy overrides for specific elements if needed, avoiding specificity issues down the line. +::: + +#### Adding border for visual debugging (optional) + +To help us visualize the layout as we build it, we can add a class that will add a temporary border to all elements. + +```css title='index.css' +.test-border { + border: 1px solid white; +} +``` + +During development, you can add the `test-border` class to any element to see its exact dimensions and how it fits within the layout. +This is especially useful for debugging spacing and alignment issues. + +### Responsive UI Scaling + +When building game UI, hardcoding static pixel values (like `font-size: 16px` or `width: 300px`) creates scaling issues. +A UI designed at 1080p will appear incorrectly proportioned—massive on a 720p display and tiny on a 4K display. + +To resolve this for our prototype, we will tie the root font-size of the document to the Viewport Height (vh). +By doing this, any element sized using rem units will scale proportionally to the screen's resolution. + +Assuming our reference wireframe was designed at a standard 1920x1080 resolution, and we want our base `1rem` to equal `16px` at that resolution, we calculate the viewport height percentage: +`(16px / 1080px) * 100 = 1.4814vh`. + +Add this rule to the top of your index.css: + +```css title='index.css' +html { + font-size: 1.4814vh; +} +``` + +With this rule applied, using `rem` for `margins`, `paddings`, and dimensions ensures the layout scales predictably. + +For example, an element with `width: 2rem` will render at exactly 32px on a 1080p screen, but will dynamically scale up on a 1440p or 4K screen, while still +maintaining its relative proportion to the height of the window. + +:::caution +While this pure vh scaling method is highly effective for rapid prototyping and ensuring immediate multi-resolution support, +it is not a flawless solution for final production. +Extreme aspect ratios (like ultrawide monitors) often require additional logic, to prevent the UI from scaling out of bounds. +We will explore these advanced scaling techniques later in the optimization section of the guide. +::: + +## Managing Assets + +Gameface UI utilizes Vite's asset pipeline to handle static resources like fonts and images. Managing these files properly ensures they are bundled correctly and optimized for the engine. + +### Adding Custom Fonts + +For this prototype, we are using a custom font called "Cinzel" for our headers to match the RPG aesthetic. + +Adding a custom font in Gameface UI is straightforward. You simply place the `ttf` font files in your `src/assets/` directory and reference them in your CSS using the +`@font-face` CSS rule and a relative path. + +For a better file structure, we recommend creating a `fonts` subfolder inside `src/assets/` and placing the `Cinzel-Regular.ttf` file there. + + + +- src + - assets + - fonts + - Cinzel-Regular.ttf + - components + - ... + - views + - ... + + + +Once you have added the assets, add the following snippet to the top of your `src/views/inventory/index.css`: + +```css title='index.css' +@font-face { + font-family: 'Cinzel'; + /* Use a relative path so Vite processes the asset during the build */ + src: url('../../assets/fonts/Cinzel-Regular.ttf') format('truetype'); + font-weight: normal; + font-style: normal; +} +``` + +:::tip[Using the font] +Now that the font is loaded, you can use it in your project like this: +```css +.some-element { + font-family: 'Cinzel', serif; +} +``` +::: + +### Organizing and Using Icons + +Rather than manually writing standard `` tags or inline SVGs for every item in our inventory, Gameface UI includes an optimized `` component. + +This component will suggest and display any SVG or PNG file located inside the `src/assets/icons/` directory. + +In the starter assets for this walkthrough, we have included a few sample icons (like `sword.svg` and `shield.svg`) that we will use for our inventory items. + +Create a new `inventory` folder inside `src/assets/icons/` and place the icons there: + + +- src + - assets + -fonts + - Cinzel-Regular.ttf + - icons + - inventory + - sword.svg + - shield.svg + - ... + - components + - ... + - views + - ... + + +Once the files are in the folder, you can import the `` component into your JSX file and call them dynamically using dot notation based on the folder structure and file name: + +```tsx title='Inventory.tsx' +import { Icon } from "@components/Media/Icon/Icon"; + +// Renders the 'sword.svg' file located in src/assets/icons/inventory/icons/ + +``` + +:::tip +If you want to learn more about how the `Icon` component generates types or handles different image formats, you can refer to the dedicated +`` component documentation. +::: + +## Building the Core Layout + +With our assets ready and global styles defined, we can construct the macro-level skeleton of the inventory screen. +We will build this up step-by-step, starting from the outermost containers down to the specific UI components. + +### Declaring modular stylesheet and SCSS variables + +Before writing the JSX, we should set up the styles for the inventory view. Apart from the global styles in `index.css`, we will also create a modular stylesheet for the inventory layout. +This will ensure that our styles are scoped to this view and do not interfere with other parts of the project. + +Create a new file named `Inventory.module.scss` in your view folder. Then, open your main component file (`Inventory.tsx`) and import the styles so they are ready to use: + +```tsx title='Inventory.tsx' +import styles from './Inventory.module.scss'; +``` + +#### Setting up variables + +One final thing we can do before diving into the prototype is to declare some SCSS variables. +This will help us reuse code throughout our project and significantly speed up the styling process. + +We will declare variables for: + +- The global spacing between elements, which we will use as a baseline to calculate specific padding and margins. +- The custom font that our headers will use. +- The main color palette of this prototype. + +Inside the `Inventory.module.scss` file you just created, add the following code: + +```scss title="Inventory.module.scss" +$global-spacing: 3rem; +$font-cinzel: 'Cinzel', serif; +$primaryColor: #868599; +$secondaryColor: #3e3d5d; +$background-soft-solid: #383940; +``` + +Now we are ready to start building the inventory prototype. + +### The Master Container and Columns + +In Gameface UI, we use the `` and `` layout components to quickly set up a twelve column layout structure. +These `Column` components are perfect for blocking out a view into distinct sections. + +To use them, simply import the `Column` component and append the number of columns you want it to span out of the 12-column grid (e.g., ``, ``, up to `` for a full span). + +For our inventory screen, we will create a three-column layout wrapped in a master `` component: + +1. A left navigation column (``) +2. A middle equipment and grid column (``) +3. A right item inspector column (``) + +```tsx title='Inventory.tsx' +import Row from "@components/Layout/Row/Row"; +import Column from "@components/Layout/Column/Column"; +import styles from './Inventory.module.scss'; + +const Inventory = () => { + return ( + + + + + + ) +}; + +export default Inventory; +``` + +:::tip[Visualizing the layout] +You can add the `.test-border` class we created earlier directly to the `Column` components to see the layout structure visually as you build it out. + +```tsx title='Inventory.tsx' ins="class="test-border"" + + + + + +``` +::: + +### Setting up routes (Tabs) + +Before we populate the columns with content, we need to set up the routing. +By design, our left column will serve as persistent navigation for different menu categories (like Inventory, Crafting, Quest Items, etc.), +while the middle and right columns will change based on the active tab. + +To set up simple routing in Gameface UI, we use the `` component as a master wrapper for our view, and `` components to define the specific content for each route. + + + +1. First, import and wrap your entire layout with the `` component. This will enable routing functionality for all child `Tab` components. + + ```diff lang="tsx" title='Inventory.tsx' + +import Tabs from "@components/Navigation/Tabs/Tabs"; + + const Inventory = () => { + return ( + + + + + + + + + + ) + }; + + export default Inventory; + ``` + + The `default` prop determines which route is active when the view first loads. + +2. Next, we add the `` component to define our inventory route. We wrap our middle and right columns inside it so they only render when the "inventory" location is active. + + ```diff lang="tsx" title='Inventory.tsx' + +import Tab from "@components/Navigation/Tab/Tab"; + + const Inventory = () => { + return ( + + + + + + + + + + + + ) + }; + + export default Inventory; + ``` + +3. That's it! + + The routing is now set up. You can add additional `Tab` components below this one for other routes (like "crafting" or "log"), and they will automatically be handled by the master `Tabs` component. + + + +To actually trigger these route changes, we need to add clickable links inside our left column. For this, we will use the `TabLink` component. + +### Adding the Navigation (Left Column) + +To create the navigation, we will populate the `` component with `TabLink` components. We will use a `` container to stack these links vertically. + +#### 1. Defining the Styles + +Before adding the components, open your `Inventory.module.scss` file and add the styles for the sidebar and the tab links. + +```scss title="Inventory.module.scss" +.sidebar { + padding-top: calc(2rem + $global-spacing); + flex-grow: 1; + background-color: $background-soft-solid; +} + +.tab-link { + font-family: $font-cinzel; + width: 85%; + padding: 1.5rem 0; + text-align: center; + font-size: 2rem; + background-color: $primaryColor; + + &-current { + background-color: $secondaryColor; + color: white; + } +} +``` + +:::note[Using CSS Modules] +When using CSS Modules in JSX, you access your classes as properties of the `styles` object. +- For standard class names, use dot notation: `class={styles.sidebar}` +- For class names containing hyphens, use bracket notation: `class={styles['tab-link']}` +::: + +#### 2. Building the Layout + +Now, return to `Inventory.tsx`. Import the `Flex` and `TabLink` components at the top of your file: + +```tsx title="Inventory.tsx" +import Flex from "@components/Layout/Flex/Flex"; +import TabLink from "@components/Layout/TabLink/TabLink"; +``` + +Next, nest the `` component inside ``, and populate it with four `` components corresponding to our intended routes: + +```diff lang="tsx" title="Inventory.tsx" + ++ ++ Inventory ++ Crafting ++ Quest Items ++ Log ++ + +``` + +The final result is a vertical column of four links, that are aligned to the horizontal end of the their wrapper and have `1rem` gap between them. + +#### 3. Understanding `activeClass` + +You will notice that the `` components have an additional prop called `activeClass`. + +The `` component automatically tracks the routing state managed by the parent `` component. +When the current route matches the `location` prop of the link, it dynamically applies whatever CSS class you provided to the `activeClass` prop. + +#### Result + +If you have followed the tutorial so far, you should see this displayed in your Player! + + + +### Structuring the Center Panel + +The middle section (``) acts as the core of our inventory view. +We will split this column horizontally into two distinct areas: a vertical stack of equipped items on the left, and a large inventory grid on the right. + +To achieve this, we will place a master `` container inside our column, and nest two child `` containers inside of it. + +#### 1. The Equipped Items Column + +Our goal for the left side of this panel is to create a vertical stack of six equipment slots that is pushed down from the top and evenly distributed within a restricted height. + +Open `Inventory.tsx`, import the `` component at the top, and then build out the JSX structure. + +```diff lang="tsx" title="Inventory.tsx" ++import { Icon } from "@components/Media/Icon/Icon"; + +// ... + + ++ + ++ {/* Equipped Items Stack */} ++ ++
++
++
++
++
++
++ + ++ + +``` + +:::note[Icon fill property] +Notice the use of the `fill` prop on the `` components? This is a built-in property that tells the icon image to span the full width & height of it's container. +::: + +To make this JSX layout behave correctly, open `Inventory.module.scss` and add the styling logic. + +```scss title="Inventory.module.scss" +.main-panel { + padding: $global-spacing 0; + flex: 1; /* Forces the panel to take up all available height in the column */ +} + +.equipped { + &-items-wrapper { + margin: 0 $global-spacing; + margin-top: calc(5rem + $global-spacing); // 8rem total + height: 75%; /* Restricting height so space-between can distribute the items */ + } + + &-item { + width: 6.15rem; + height: 6.15rem; + background-color: $primaryColor; + } +} +``` + +By restricting the height to 75%, our `` component's `space-between` rule will evenly distribute the items within that specific space. + +#### 2. Generating the Inventory Grid + +For the right side of the panel, we want the actual inventory grid to claim all the remaining horizontal space and automatically generate a 5x6 slot layout. + +Return to `Inventory.tsx` and import the `` component. When using the `` component, we simply pass the exact dimensions we want (`cols={5}` and `rows={6}`). + +To populate those specific slots, we use the `` component. `` allows you to specify exactly what content renders at a specific row and column coordinate. + +Add this code right below the Equipped Items `Flex` block you just created: + +```diff lang="tsx" title="Inventory.tsx" ++import Grid from "@components/Layout/Grid/Grid"; + +// ... + + + + + {/* Equipped Items Stack */} + + {/* ... items ... */} + + ++ {/* Grid Wrapper */} ++ + ++ {/* Empty header for interactive options (Dropdowns, etc.) added in Part 2 */} ++ + ++ {/* The 5x6 Inventory Grid */} ++ ++ {/* Populating specific coordinate slots with items */} ++ ++ ++ ++ ++ ++ ++ + ++ + + + +``` + +Additionally, we use the `column-class` prop of the grid to apply a `grid-cell` class to each grid cell. + +Finally, define the borders and colors for the grid area in `Inventory.module.scss`. + +```scss title="Inventory.module.scss" +.grid { + width: 100%; + flex-grow: 1; + padding: 2rem; + color: white; + background-color: $background-soft-solid; + + &-wrapper { + flex-grow: 1; /* Pushes the grid to fill the remaining horizontal space */ + border: 0.5rem solid $secondaryColor; + } + + &-options { + padding: 2rem; + width: 100%; + } + + &-cell { + background-color: rgba($primaryColor, 0.5); + } +} +``` + +:::note[Filling the container] +Notice how we use `flex-grow: 1` on the wrapper and the grid itself? This is the flexbox rule that pushes the grid and the wrappper element to fill the rest of the available empty space. +::: + +#### Result + +If you have followed the tutorial so far, you should see this displayed in your Player! + +![Grid Prototype Preview](../../../../assets/phase-2/the-prototyping-workflow/grid-preview.png) + +### The Item Inspector (Right Column) + +To finish our layout skeleton, we will add a simple placeholder to our right column (``). +In the next part of this series, we will transform this empty space into a detailed Item Inspector UI using Gameface UI's "basic" components such as: inputs, progress bars, and buttons. + +Open `Inventory.module.scss` and add a quick wrapper style: + +```scss title="Inventory.module.scss" +.item { + &-container { + padding: $global-spacing; + } + + &-wrapper { + border: 0.5rem solid $secondaryColor; + flex-grow: 1; + font-size: 1.375rem; + } +} +``` + +Then, add the wrapper to your `` in `Inventory.tsx`: + +```diff lang="tsx" title="Inventory.tsx" +- ++ ++
++ Item Inspector (Coming Soon) ++
++ +``` + +And with that, the core layout for our inventory screen is complete! + +## Wrapping Up + +Congratulations! You have successfully built the core structural layout for your inventory screen. +You have set up a responsive grid, implemented modular SCSS, configured basic routing, and learned how to dynamically load SVG assets. + +In **Part 2** of this guide, we will breathe life into this skeleton by introducing Gameface UI's rich UI components. +We will populate the central panel with Dropdowns and Checkboxes, and build out the detailed Item Inspector panel using Progress Bars, Number Inputs, and Toggle Buttons to complete our visual prototype. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/prototyping-an-inventory-part-two.mdx b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/prototyping-an-inventory-part-two.mdx new file mode 100644 index 0000000..8378916 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/prototyping-an-inventory-part-two.mdx @@ -0,0 +1,457 @@ +--- +title: "Prototyping an Inventory Screen - Part 2: UI Components & Interactivity" +description: "Breathe life into your inventory prototype by adding interactive Gameface UI components, styling active states, and extracting logic into custom components." +sidebar: + order: 3 +--- + +import Summary from '../../../../components/Summary.astro'; +import Highlight from '../../../../components/Highlight.astro'; +import Link from '../../../../components/Link.astro'; +import { Steps, FileTree } from '@astrojs/starlight/components'; +import gridImage from "../../../../assets/phase-2/the-prototyping-workflow/grid-finished-preview.png" +import itemInspectorOne from "../../../../assets/phase-2/the-prototyping-workflow/item-inspector-1.png" +import itemInspectorTwo from "../../../../assets/phase-2/the-prototyping-workflow/item-inspector-2.png" +import itemInspectorThree from "../../../../assets/phase-2/the-prototyping-workflow/item-inspector-3.png" + + + In Part 2 of this walkthrough, we will transform our layout skeleton into a rich, interactive visual prototype using Gameface UI's built-in basic components. + + + 1. First, we will populate the center grid options using the `` and `` components. + 2. Next, we will fully build out the right-side Item Inspector using inputs, progress bars, and buttons. + 3. Finally, we will polish the prototype by adding active visual states to our navigation links. + + + +## Integrating Complex UI Components + +Before we write any code, let's talk about how Gameface UI components are structured. +They use a **compound component** pattern, meaning complex elements are broken down into their individual parts. + +Instead of passing a massive list of props to a single monolithic tag (e.g., ``), +we compose the UI using smaller, targeted sub-components like `` and ``. + +This philosophy gives you granular control over the layout and styling of every individual piece without fighting the boilerplate. + +### Populating the Grid Options + +In Part 1, we left an empty `` container with the class `grid-options` above our inventory grid. +Our goal here is to add interactive controls so the player can sort their items and filter for usable gear. + +Open `Inventory.tsx` and import the required components at the top of your file: + +```tsx title="Inventory.tsx" +import Dropdown from "@components/Basic/Dropdown/Dropdown"; +import Checkbox from "@components/Basic/Checkbox/Checkbox"; +``` + +Now, let's populate the `.grid-options` container. + +```diff lang="tsx" title="Inventory.tsx" +{/* Grid Wrapper */} + + +- {/* Empty header for interactive options */} +- ++ {/* Grid Sorting & Filtering Options */} ++ + ++ ++
Sort By:
++ ++ {/* We can inject custom classes directly onto the sub-components */} ++ ++ Rarity ++ ++ ++ + ++ ++ ++ {/* Using the built-in label simplifies formatting */} ++ Show Usable Only ++ + ++ + + {/* The 5x6 Inventory Grid */} + + {/* ... Grid Tiles ... */} + + + +``` + +:::note +Notice how using the built-in `` instead of creating our own text `
` +simplifies the process—it handles the alignment and spacing out-of-the-box. +::: + +To make these components match the aesthetic of our prototype, apply our custom dimensions and colors. Open `Inventory.module.scss` +and nest the following targeted styles inside your existing `.grid-options` class: + +```scss title="Inventory.module.scss" +.grid { + // ... existing grid styles ... + + &-options { + padding: 2rem; + width: 100%; + + // Targeting the specific Dropdown sub-components we declared + &-dropdown-trigger { + width: 17rem; + height: 2.5rem; + background-color: $primaryColor; + } + + // Targeting the default svg in the dropdown icon + &-dropdown-icon path { + stroke: $disabledTextColor; + transition: stroke .15s ease; + } + + // Targeting the Checkbox control box + &-checkbox { + width: 2.5rem; + height: 2.5rem; + } + } +} +``` + +#### Results + +With these changes your inventory grid should be looking like this: + + + +### Building the Item Inspector + +Now we will transform the right column (``) from a simple placeholder into a fully fleshed-out item details panel. + +This is where a component library really shines. Instead of spending hours writing custom logic for sliders, input fields, and toggle states, we can use Gameface UI's pre-built interactive components to rapidly assemble our prototype. + +First, import the necessary UI and layout components at the top of `Inventory.tsx`: + +```tsx title="Inventory.tsx" +import Progress from "@components/Feedback/Progress/Progress"; +import NumberInput from "@components/Basic/Input/NumberInput/NumberInput"; +import Button from "@components/Basic/Button/Button"; +import ToggleButton from "@components/Basic/ToggleButton/ToggleButton"; +import Relative from "@components/Layout/Relative/Relative"; +import Absolute from "@components/Layout/Absolute/Absolute"; +``` + +We will cover this column in three distinct parts: the item identity, the item stats, and the interactive controls. + +#### Part 1: Item Identity and Wrapper + +Our first goal is to set up the main `` wrapper for the panel, add the inspector header, and display the item's image and name. + +Replace the placeholder inside your `` with this new structure: + +```tsx title="Inventory.tsx" + + + + {/* Header & Item Icon */} +

Item Inspector

+
+ +
+ + {/* Item Name */} + +

Iron Broadsword

+
+ + + {/* We will add stats and controls here next */} + + + +``` + +Next, open `Inventory.module.scss` and add the specific classes required to style this upper section. We use our predefined `$font-cinzel` variable to give the headers that classic RPG aesthetic. + +```scss title="Inventory.module.scss" +.item { + &-container { + padding: $global-spacing; + } + + &-wrapper { + border: 0.5rem solid $secondaryColor; + flex-grow: 1; + font-size: 1.375rem; + } + + &-inspector-label { + width: 100%; + padding: 0.5rem; + margin: 0; + background-color: $background-soft-solid; + text-align: center; + font-family: $font-cinzel; + } + + &-image { + width: 15rem; + height: 15rem; + background-color: $primaryColor; + border: 0.5rem solid $secondaryColor; + } + + &-name { + font-family: $font-cinzel; + color: white; + font-size: 2rem; + } +} + +.separator { + width: 18rem; + height: 0.1rem; + background-color: white; +} +``` + +##### Result + +So far your item inspector panel should be looking like this: + + + +#### Part 2: Stats and Durability + +Our next goal is to display the weapon's stats and its current durability. + +A common challenge in UI design is overlaying text onto a progress bar. +Instead of polluting your CSS files with arbitrary class names and wrapper elements just to handle basic positioning, + +Gameface UI makes this structural relationship explicit with the help of the `` and `` layout components. + +Add this code inside your `.item-wrapper` flex container, right below the item name separator: + +```tsx title="Inventory.tsx" ins=" +
Damage: 15-22
+
Speed: Medium
+ + +{/* Durability Bar with Absolute Text Overlay */} + +
Durability
+ + + 80% + + +``` + +:::note[Absolute's center property] +The `` component includes a highly convenient `center` prop. + +By wrapping the `` in a `` container, we can use `` to perfectly align the "80%" text right over the middle of the bar without writing a single line of custom CSS math! +::: + +##### Result + +After these changes the item inspector panel should be looking like this: + + + +#### Part 3: Interactive Controls + +Finally, we need to add the final piece of components. + +Here we see the compound component pattern shine again with the ``. Because it is split into `DecreaseControl`, `IncreaseControl`, and `Input` pieces, +we can easily inject inline styles (like `fontSize: '2rem'`) on the exact element we need them. + +We also drop in the standard ` + + + +{/* Toggle Button */} + + +
Favorite
+ + +``` + +To finish off the inspector, add this single rule to your `Inventory.module.scss` to style the buttons: + +```scss title="Inventory.module.scss" +.item { + // ... previous item styles ... + + &-button { + font-family: $font-cinzel; + color: white; + font-size: 2rem; + } +} +``` + +##### Results + +With that the final column of our prototype has been finished! The final resul: + + + +## Adding Visual Feedback to Elements + +A prototype isn't complete until it *feels* interactive. We need to add visual cues so the player knows which navigation tab they are currently viewing, as well as which inventory items are currently selected. + +#### The Navigation Arrow + +In Part 1, we passed `activeClass={styles['tab-link-current']}` to our Inventory ``. The Gameface UI component automatically applies this class when the current route matches the link. Now, let's actually write that CSS to give it a cool, active indicator arrow. + +We will use an `::after` pseudo-element and a CSS `clip-path` to draw the arrow dynamically. Open `Inventory.module.scss` and add this to your sidebar styles: + +```diff lang="scss" title="Inventory.module.scss" +.tab-link { + // ... existing tab-link styles ... + + &-current { + background-color: $secondaryColor; + color: white; ++ position: relative; + + /* Adds the active indicator arrow pointing to the content */ ++ &::after { ++ content: ''; ++ position: absolute; ++ top: 0; ++ bottom: 0; ++ right: -3rem; ++ width: 3rem; ++ z-index: -1; ++ background-color: $secondaryColor; ++ clip-path: polygon(0 0, 0 100%, 100% 50%); ++ } + } +} +``` + +#### The Inventory Slots (Using Mixins) + +Next, we need to create an "active" state for our inventory slots so the player knows exactly which item they have selected. + +Because the styles for the active states of both the `equipped items` and the `grid items` are almost identical, we can laverage SCSS `@mixin`. + +Think of a `mixin` as a reusable function for your CSS. Instead of copying and pasting the same block of styles across different classes, you define the rules once in a `mixin` and `@include` +them wherever needed. You can even pass arguments to them to handle minor variations! + +Add this mixin at the top of your `Inventory.module.scss` file, right below your variables. + +```scss title="Inventory.module.scss" +// Define the mixin to handle active slot borders and backgrounds +@mixin active-slot($border-width) { + border: $border-width solid white; + background-color: $secondaryColor; +} +``` + +We will pass `$border-width` as an argument so we can slightly adjust the thickness depending on where the item is located. + +Now, scroll down and use the `@include` directive to apply this mixin to our equipped items and grid tiles: + +```diff lang="scss" title="Inventory.module.scss" +.equipped { + // ... existing equipped styles ... + + &-item { + width: 6.15rem; + height: 6.15rem; + background-color: $primaryColor; + + // Apply the mixin with a 0.20rem border ++ &-active { ++ @include active-slot(0.20rem); ++ } + } +} + +.grid { + // ... existing grid styles ... + + &-cell { + background-color: rgba($primaryColor, 0.5); + } + + // Apply the mixin with a slightly thicker 0.25rem border ++ &-item-active { ++ @include active-slot(0.25rem); ++ } +} +``` + +#### Simulating the Active State + +Finally, let's hardcode these active classes onto a couple of items in `Inventory.tsx` so we can see the visual feedback in our prototype. + +Let's make the sword and boots slots in the equipped items panel and the sword item in the grid look "selected." + +```tsx lang="tsx" title="Inventory.tsx" ins="${styles['equipped-item-active']}" ins="class={styles['grid-item-active']}" +{/* Equipped Items */} + +
+
+
+ {/* Apply the active class to the sword & boots */} +
+
+
+ + +// ... further down ... + +{/* Inside the Grid */} + + +{/* Apply the active class to the sword in the grid */} + + +``` + +## Final Result + +With these final touches our prototype is now finished! + +![Finished Inventory Prototype](../../../../assets/phase-2/the-prototyping-workflow/inventory-finished.png) + +--- + +## Wrapping Up + +Congratulations! You have successfully built a rich, visual prototype from the ground up. + +Throughout this two-part series, you've learned how to: +* **Wire up layouts** using structural components like ``, ``, and ``. +* **Compose interactive UI** using Gameface UI's compound components like `` and ``. +* **Position elements** using spatial components like ``, `` and ``. +* **Polish visual feedback** using CSS Modules and SCSS `@mixin`s. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/section-overview.mdx b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/section-overview.mdx new file mode 100644 index 0000000..48e56dd --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/The Prototyping Workflow/section-overview.mdx @@ -0,0 +1,65 @@ +--- +title: "Section Overview: Prototyping an Inventory" +description: "Learn the core principles of Gameface UI by translating a structural wireframe into an interactive prototype." +sidebar: + order: 1 +--- + +import Summary from '../../../../components/Summary.astro'; +import Highlight from '../../../../components/Highlight.astro'; +import Link from '../../../../components/Link.astro'; + + + In this section, we will walk through the process of building a simple inventory screen for an RPG game using Gameface UI. + + This walkthrough covers the core layout and component principles of Gameface UI, showing you how to leverage the boilerplate to move fast without manually writing complex CSS and HTML for every box on the screen. + + We believe the true power of Gameface UI lies in its ability to facilitate rapid prototyping and quickly test design layouts. For that reason, we are diving into a hands-on build rather than providing a dry explanation of the features. + + +:::note[Prerequisites] +Before continuing, ensure you have the Gameface UI boilerplate installed and a new `inventory` view running in your Player. + +If you need to set up your environment, return to the [Prototyping and Developing](../../prototyping-and-developing/#creating-your-first-view) article. +::: + +## What We Will Build + +For this walkthrough, we will build a simple inventory screen for an RPG game. The screen will consist of three main panels: +1. A left navigation panel with tabs for different menu categories. +2. A center panel displaying a grid of item slots. +3. A right panel showing detailed information about the selected item, including its name, description, and stats. + +We will prototype the wireframe below: + +![RPG Inventory Wireframe](../../../../assets/phase-2/the-prototyping-workflow/inventory-wireframe.png) + +## Core Concepts We Will Cover + +Instead of manually writing complex CSS and HTML for every box on the screen, this walkthrough will show you how to leverage the boilerplate to move quickly from design to implementation. + +Throughout this process, you will learn how to: + +* **Structure Scalable Layouts:** Use Gameface UI's Layout components to quickly structure the prototype. +* **Generate Grids:** Use the `` component to automatically generate the item slots in the center panel. +* **Use & Customize Pre-built Components:** Utilize our component library to simplify adding fully functional components like the dropdown and checkbox, and adjust their default styles to fit the look. +* **Add Frontend State:** Wire up basic active states for some elements. +* **Write Reusable Styles:** Use the built-in SASS CSS library to customize the look of our prototype and reuse styles. +* **Reuse Logic:** Take repeatable logic and make a reusable custom component. +* **Manage Assets:** Properly load custom fonts and UI SVG icons using Vite's asset pipeline. + +### Project assets + +To follow along with this walkthrough, download the provided starter assets, which include the necessary font and SVG icons. Extract the contents into your project's `src/assets/` directory. + +[**📥 Download the Starter Assets (inventory-assets.zip)**](/public/resources/phase-two/inventory-prototype-assets.zip) + +:::note[Asset Credits] +The "Cinzel" font is provided by Google Fonts under the SIL Open Font License. The UI icons are provided by [game-icons.net](https://game-icons.net) under the CC BY 3.0 license. +::: + +## Next Steps + +Once your development server is running and your `inventory` view is loaded, proceed to the first phase of the build. + +[**Continue to Part 1: Building the Layout Structure ➔**](../prototyping-an-inventory-part-one/) \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Workflow Planning/_meta.yml b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/_meta.yml new file mode 100644 index 0000000..364eb84 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/_meta.yml @@ -0,0 +1,2 @@ +order: 5 +collapsed: true \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Workflow Planning/switching-from-unity-ui-to-gameface.mdx b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/switching-from-unity-ui-to-gameface.mdx new file mode 100644 index 0000000..065efe2 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/switching-from-unity-ui-to-gameface.mdx @@ -0,0 +1,13 @@ +--- +title: Switching from Unity UI to Gameface +description: A translation guide for Unity developers leaving UGUI or UI Toolkit. +sidebar: + order: 2 +draft: true +--- + +- RectTransforms vs. CSS Box Model: Relearning layout by moving from Unity's anchor-based RectTransforms to the standard web Box Model. + +- Prefabs vs. Web Components/Frameworks: How the web ecosystem (using libraries like Gameface UI or raw React/Solid) handles reusability compared to Unity UI Prefabs. + +- MonoBehaviours vs. Frontend State: Bridging the gap between attaching C# scripts to Canvases and using JavaScript to manage UI state, plus how Gameface passes events back to Unity C#. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Workflow Planning/switching-from-unreal-umg-to-gameface.mdx b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/switching-from-unreal-umg-to-gameface.mdx new file mode 100644 index 0000000..5dbfbd4 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/switching-from-unreal-umg-to-gameface.mdx @@ -0,0 +1,13 @@ +--- +title: Switching from Unreal UMG to Gameface +description: A direct translation guide for Unreal developers moving away from Slate/UMG to the Gameface middleware. +sidebar: + order: 2 +draft: true +--- + +- Canvas Panel vs. DOM Layouts: Moving away from UMG anchors and absolute positioning to the highly responsive world of CSS Flexbox and Grid. + +- Widget Blueprints vs. JavaScript/TypeScript: Transitioning from visual scripting (UMG event graphs) to writing standard, highly performant frontend code. + +- Data Binding: How Gameface's cohtml data binding models replace UMG's property bindings and tick events to communicate with Unreal C++/Blueprints efficiently. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/Workflow Planning/workflow-planning.mdx b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/workflow-planning.mdx new file mode 100644 index 0000000..b49f39f --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/Workflow Planning/workflow-planning.mdx @@ -0,0 +1,11 @@ +--- +title: Workflow Planning - Setting Up the Gameface Environment +description: Setting up your development environment and tools for Gameface UI development. This section covers the +sidebar: + order: 1 +draft: true +--- + +- The Source of Truth: Why you should use the Gameface Player instead of standard web browsers to preview your UI, ensuring 100% rendering accuracy and performance profiling before engine integration. +- Live Reloading Pipeline: How to configure your IDE (like VS Code) and bundlers (Webpack/Vite) to push hot reloads directly to the Gameface Player. +- Separation of Concerns: Structuring your frontend repository so UI designers and frontend devs can work independently from the C++ / Blueprint engineers, relying on the Player and mock data. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/core-concepts-and-information-flow.mdx b/src/content/docs/phase-2-planning-and-setup/core-concepts-and-information-flow.mdx new file mode 100644 index 0000000..fd1cb3d --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/core-concepts-and-information-flow.mdx @@ -0,0 +1,70 @@ +--- +title: Core Concepts & Information Flow +description: Transitioning from standard web development to game UI requires a fundamental shift in how you think about data and structure. In this article, we will cover how data flows between the game engine and your interface, why your UI should stay as "dumb" as possible, and how to structure your HTML documents into optimized "Views". +sidebar: + order: 6 +draft: true +--- + +import Summary from '../../../components/Summary.astro'; +import Highlight from '../../../components/Highlight.astro'; +import Link from '../../../components/Link.astro'; +import { Steps, FileTree } from '@astrojs/starlight/components'; + + +Transitioning from standard web development to game UI requires a fundamental shift in how you think about data and structure. + +In this article, we will cover how data flows between the game engine and your interface, why your UI should stay as "dumb" as possible, and how to structure your HTML documents into optimized "Views". + + +## The "Push" Philosophy: How Data Works in Games + +If you are coming from a traditional web development background, you are likely used to the Fetch model. In a standard web app, the frontend asks a server for data, waits for a network response, displays a loading spinner, and then parses a JSON payload. + +Game UIs operate entirely differently. There are rarely any loading spinners or network requests to a backend API. Instead, Gameface operates on a Push model. + +The game engine is constantly running at 60 or more frames per second. Every single frame, the C++ engine uses data-binding to synchronize data between the UI and the engine. When data in the engine changes, the corresponding UI elements are automatically updated to reflect those changes. + +### Keep Your UI "Dumb" + +Because the game engine is pushing state updates continuously, your frontend should hold as little state as possible. The game engine is the ultimate source of truth. + +Your UI should remain "dumb." It shouldn't calculate how much damage a player took, nor should it sort a massive inventory array. The engine handles the heavy computational logic and pushes the finalized data, allowing your interface to simply react and render the result. + +:::tip +Always rely on the engine for logic and math. Your JavaScript should be reserved for managing pure UI interactions, like opening a dropdown panel or triggering an animation. +::: + +--- + +## What is a "View"? + +In Gameface terminology, each loaded HTML page within your game is referred to as a View. When planning your development workflow, you essentially have to decide how to split the UI into these views, which dictates how many distinct HTML pages your project will have. + +Generally, game UIs can be categorized into a few major screen types: + +* **Menu:** The main navigational hubs, like the Start screen, Settings, or Inventory. +* **HUD (Heads-Up Display):** The persistent, on-screen elements like health bars, minimaps, and crosshairs. +* **Spatial / Diegetic:** Elements that exist within the 3D game world itself, such as interactable computer terminals or floating nameplates above characters. +* **Meta:** 2D overlays that relate to the story but sit on top of the game, like subtitles or cinematic pop-ups. + +--- + +## Best Practices: Minimizing Views + +While it might be tempting to create a separate HTML file for every single menu screen in your game, it is highly advisable to minimize the number of views created. Loading new views entirely from scratch is much heavier than updating an existing one. + +Instead of swapping between separate HTML documents, you should leverage tabs or routing components to consolidate multiple elements onto a single view to enhance performance. + +### Routing vs. Separate Views + +Treat your complex screens like a Single Page Application (SPA). By using a frontend router, you can swap out panels and widgets instantly without asking the engine to spin up a brand-new HTML document. + +Here is a common, optimized approach to structuring a game: + +* **The Main Menu SPA:** Build your main menu as a Single Page Application. When the player clicks from "Play" to "Settings", use routing to swap the content dynamically within the same view. +* **The HUD Static Page:** Keep your HUD as a highly optimized, single HTML file without any complex routing. Hide and show widgets strictly through data-binding triggers. + +:::warning +Avoid using complex routing or heavy state-management libraries for simple Spatial or HUD views. Keep your active DOM tree small, and rely on `data-bind-if` to add or remove elements only when they are explicitly needed by the player. +::: \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/development-environment-and-tools.mdx b/src/content/docs/phase-2-planning-and-setup/development-environment-and-tools.mdx new file mode 100644 index 0000000..bf5648e --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/development-environment-and-tools.mdx @@ -0,0 +1,54 @@ +--- +title: "Development Environment & Tools" +description: "Configure your workspace with the essential editor plugins, linters, and debugging tools required for Gameface development." +sidebar: + order: 1 +draft: true +--- + +import Summary from '../../../components/Summary.astro'; +import Highlight from '../../../components/Highlight.astro'; + + + To set you up for success with Gameface, we provide a suite of specialized tools designed to streamline your workflow. + + This guide covers the core utilities you need to write, preview, and debug your UI, including IDE extensions, engine-specific linters, and our standalone preview environment. + + +## 1. The Code Editor & Plugins + +We highly recommend **Visual Studio Code (VS Code)** for Gameface development. Beyond standard code editing, VS Code allows you to attach your debugger directly to the Gameface Player or your game engine. This means you can set breakpoints, step through your UI's JavaScript, and inspect variables without ever leaving your editor. + +To further improve your workflow, we provide several official VS Code extensions: + +### Data Binding Autocomplete +Your frontend will communicate heavily with the game engine's backend data. The Data Binding Autocomplete extension provides context-aware IntelliSense for these bindings, helping you quickly reference properties and preventing typos when linking to engine data. + +* **How to install:** [Placeholder for VS Code Marketplace link or install instructions] + +### Gameface HTML & CSS Linters +Because Gameface is optimized for raw performance, it does not support every single web feature found in a standard browser. + +Our official linters run directly in your editor and will highlight unsupported properties (like certain CSS features or HTML tags) *before* you even run the game, saving you from runtime surprises. + +* **How to install the CSS Linter:** [Placeholder for npm install command or extension link] +* **How to install the HTML Linter:** [Placeholder for npm install command or extension link] + +## 2. The Local Sandbox: Gameface Player + +When building Gameface UI, you preview your work in the **Gameface Player** rather than a standard web browser. + +The Player is a standalone, lightweight version of the Coherent UI engine. It acts as your local sandbox, ensuring that what you see on your development screen is exactly how the UI will render and perform in the final compiled game. + +* **Where to find it:** The `Player.bat` (Windows) or `Player` executable (Mac/Linux) is located in your core Gameface package directory. +* **How we use it:** In the upcoming project setup guides, we will show you how to connect your local development server directly to this Player. + +## 3. The Debugger: Gameface Inspector + +Because your UI runs natively inside the game engine, you cannot simply right-click and "Inspect Element." Instead, you use the standalone **Gameface Inspector** app to connect to the running Player or your game. + +The Inspector is your primary visual debugging tool, allowing you to: +* Inspect and modify the DOM tree in real-time. +* Tweak CSS values on the fly to perfect your layouts. +* Profile layout and rendering performance to ensure your UI hits 60 FPS. +* View console logs and JavaScript errors thrown inside the engine. \ No newline at end of file diff --git a/src/content/docs/phase-2-planning-and-setup/prototyping-and-developing.mdx b/src/content/docs/phase-2-planning-and-setup/prototyping-and-developing.mdx new file mode 100644 index 0000000..56af987 --- /dev/null +++ b/src/content/docs/phase-2-planning-and-setup/prototyping-and-developing.mdx @@ -0,0 +1,320 @@ +--- +title: "Prototyping and Developing (Gameface UI)" +description: "An introduction to the Gameface UI boilerplate, its structure, and how it accelerates your UI development." +sidebar: + order: 4 +--- + +import Summary from '../../../components/Summary.astro'; +import Highlight from '../../../components/Highlight.astro'; +import Link from '../../../components/Link.astro'; +import { FileTree, Steps, Code } from '@astrojs/starlight/components'; +import menuPreviewVideo from '../../../assets/phase-2/prototyping-and-developing/gameface-ui-menu-preview.webm' +import hmrPreview from '../../../assets/phase-2/prototyping-and-developing/HMR-preview.webm' + + + Gameface UI is an official boilerplate powered by Vite and SolidJS, pre-configured with a comprehensive library of game-ready components. + + This guide covers how to install the boilerplate, preview the pre-built UI views, understand the project structure, and create your first custom view using the component library. + + +## Getting Started + +If you followed Option B in the previous ["Setting up the Gameface Stack"](../recommended-tech-stack/setting-up-the-gameface-stack/#option-b-the-gameface-ui-project) article, +you likely already have this installed and can skip to the [next section](#understanding-the-project-structure)! + +If you are starting fresh, you can download a clean copy of the boilerplate using `degit`. Open your terminal and run: + +```bash +npx degit CoherentLabs/gameface-ui-boilerplate my-game-ui +cd my-game-ui +npm install +``` + +This will create a new folder called `my-game-ui` with the boilerplate code, install all dependencies, and get you ready to start developing your game UI. + +### Previewing the Pre-built Menu + +The boilerplate comes with a fully functioning `menu` view right out of the box so you can immediately see Gameface UI in action. + + + +1. **Start the Dev Server:** In your terminal, type the following command to start the Vite development server: + ```bash + npm run dev + ``` + Your server is now running at `http://localhost:3000/menu`. + +2. **Run the server in the player:** Locate the `Player.bat` file included in your Gameface package. Open the file in a text editor, + scroll down until you see a similar command: + + ```bat + start "Player" /d "%wd%" "..\Player\Player.exe" --player %*" + ``` + + and add the following parameter to the end of the line: + + + +3. "Launch the Player:" Launch the `Player.bat` file and you should see a fully interactive menu screen rendered perfectly inside the game engine! + + + + + +:::tip +This Menu UI is built entirely using the Gameface UI boilerplate and its component library. +::: + +## Understanding the project structure + +To understand how that menu was built, we need to look at the project's folder structure. Gameface UI enforces a specific architecture to keep your project modular and easy to navigate. + +- **`/src/assets`**: This directory is designated for all UI assets used in the development process. This folder can include files such as `.png`, `.svg`, fonts, and other resources. +- **`/src/components`**: All of our pre-made components live here!. +This folder is organized into subfolders based on component types. Each component is a standalone block of UI that can be easily imported and reused across different views. + - Basic: Includes components like buttons, checkboxes, and sliders. + - Complex: Contains more intricate components that combine multiple basic components, such as: color picker, carousel, radial menu and others. + - Feedback: Here are the components that provide feedback to the users: modal, progress bars, toast and others. + - Layout: Contains components for structuring your UI, such as grids, columns, rows and other structural containers that help with quick prototyping. + - Media: Houses components for displaying images, icons and other media types. + - Utility: Includes helper components that don't fit into the other categories but are still essential for building your UI, such as: `Navigation`. + Which is our component for establishing a keyboard and gamepad navigation and interactions. + + :::tip[Checkout the full component library!] + You can see the full list of available components in the [Gameface UI documentation](https://gameface-ui.coherent-labs.com/components/). + ::: + +- **`/src/custom-components`**: This directory is reserved for components created during UI development. We recommend placing all of your custom components in this folder. +- **`/src/views`**: Gameface UI views are standalone HTML pages paired with their respective CSS & JavaScript files. +- **`/tests`**: This is the place where you can write your end to end tests for your views. +- **`package.json`**: Handles project dependencies and defines scripts for running various commands. (You don't need to worry about it yet). +- **`tsconfig.json`**: Specifies TypeScript rules and settings for the project (You don't need to worry about it yet). +- **`vite.config.mts`**: Configures the Vite build tool, setting options and plugins to optimize and transform the source code for Gameface during the build process. + +### Structure overview + + + +- src + - assets + - icons/ + - components + - Basic/ + - Complex/ + - Feedback/ + - Layout/ + - Media/ + - Utility/ + - ... + - custom-components/ + - views + - hud + - index.html + - index.css + - index.tsx + - Hud.tsx + - Hud.module.css + - menu + - index.html + - index.css + - index.tsx + - Menu.tsx + - Menu.module.css +- tests/ +- package.json +- tsconfig.json +- vite.config.mts + + + +## Creating Your First View + +Let's put this structure into practice by creating a brand new "Inventory" view and dropping in a pre-built component. + + + +1. #### **Create the View Folder** + Inside `/src/views`, create a new folder called `inventory`. + +2. #### **Create the View Files** + Following the Gameface UI standard, you need to create four files inside this new folder: + - `index.html`: This is the entry HTML file for the view. It should contain a root div where your UI will be rendered. + ```html title="src/views/inventory/index.html" + + + + + +
+ + + + + ``` + - `index.css`: This file will contain any global styles for your view. This is a good place to set up any style resets or constant styles that will be used across multiple components in the view. + + ```css title="src/views/inventory/index.css" + body { + width: 100vw; + height: 100vh; + margin: 0; + } + ``` + - `index.tsx`: This is the entry Typescript file where you will set up the rendering logic for your view. + ```tsx title="src/views/inventory/index.tsx" + import { render } from 'solid-js/web'; + import Inventory from './Inventory'; + import './index.css'; + + const root = document.getElementById('root'); + + render(() => , root!); + ``` + :::caution + This is a mandatory setup for every SolidJS entry point. Feel free to copy and paste this into any new view you create! Replace the `Inventory` import with the name of your view's main component. + ::: + + - `Inventory.tsx`: The entry component of your view. This is where you will build the main structure of your view and import any components you want to use. + ```tsx title="src/views/inventory/Inventory.tsx" + const Inventory = () => { + return
Inventory
; + }; + + export default Inventory; + ``` + +3. #### **Test the View** + Make sure your dev server is running (`npm run dev`), then open your Gameface Player and change the URL to your new view: + + + You should see a bright orange square with the word "Inventory" rendered in the Player! + + ![Inventory view image](../../../assets/phase-2/prototyping-and-developing/inventory-view.png) + +4. #### Drop in some components + Now let's populate the empty view with some real components from the library. Open `Inventory.tsx` and import some of our pre-built components. We will use the `ToggleButton`, `Checkbox` and `Slider` basic components + and the `Flex` layout component to quickly structure them in a column with gaps. + + ```diff lang="tsx" title="src/views/inventory/Inventory.tsx" ins="50rem" + +import Checkbox from "@components/Basic/Checkbox/Checkbox"; + +import Slider from "@components/Basic/Slider/Slider"; + +import ToggleButton from "@components/Basic/ToggleButton/ToggleButton"; + +import Flex from "@components/Layout/Flex/Flex"; + + const Inventory = () => { + return
+ + + + + + Off + + On + + + + Fullscreen Mode + + Motion Blur + + + + +
; + }; + + export default Inventory; + ``` + + Save the file and check the Player again. You should see the components preview in the Player! + + + +## Gameface UI features + +The Gameface UI project comes pre-configured with a lot of features to make your development experience as smooth as possible. Here are just a few of them: + +### Hot Module Replacement (HMR) + +Every time you save a file, the Player will instantly update with your changes without needing a manual refresh. +This allows for a super fast development iteration cycle, where you can see the impact of your code changes in real-time. + + + +### Alias imports + +To make your imports cleaner and more intuitive, Gameface UI comes with pre-configured alias imports for the most commonly used folders. +You can import components, assets, and custom components using simple aliases instead of long relative paths. + +| Folder | Alias | +|----------------------------|--------------------| +| `/src/assets/` | `@assets` | +| `/src/components/` | `@components` | +| `/src/custom-components/` | `@custom-components` | + +Consider the following folder structure: + + + +- src + - assets + - logo.png + - components + - Layout + - Block + - Block.tsx + - ... + - custom-components + - MyComponent + - MyComponent.tsx + - views + - hud + - Hud.tsx + - ... + - ... + + + +To import `logo.png`, `Block.tsx`, and `MyComponent.tsx` in `Hud.tsx`, you can write: + +```jsx title="/src/views/hud/Hud.tsx" ins="@assets" ins="@components" ins="@custom-components" +import Block from '@components/Layout/Block/Block'; +import MyComponent from '@custom-components/MyComponent/MyComponent'; +import Logo from '@assets/logo.png'; + +const Hud = () => { + return ( + + + + + ); +}; +``` + +:::tip[Alias benefits] +Alias imports enhance code readability and maintainability by replacing lengthy relative paths like + `../../../assets/logo.png` with shorter, more intuitive paths such as `@assets/logo.png`. This simplifies navigation and minimizes errors during refactoring. +::: + +### Deep tools integration + +Because Gameface UI is built on top of Vite and SolidJS, you can take advantage of the rich ecosystem of tools and plugins available for these technologies. + +We have also integrated some of our own tools and libraries directly into the boilerplate: + +- The Gameface E2E testing library, which allows you to write end-to-end tests for your views using a simple and intuitive API. +- The Interaction Manager library, which provides a powerful system for handling user navigation and input in your UI. +- The Vite Gameface style transformer, a Vite plugin that transforms your inline styles to reusable CSS classes at build time to ensure optimal performance in Gameface. + +## Next Steps + +This is just scratching the surface of what Gameface UI can do. We will be exploring more of its features and capabilities in the upcoming articles, +including how to prototype quickly and create custom components. + +If you are ready to finalize your setup, move on to the [Workflow Planning](../workflow-planning/) article, where we will discuss version control and IDE configuration. \ No newline at end of file diff --git a/src/content/docs/phase-3-layout-assets-and-styling/laying-out-the-screen.mdx b/src/content/docs/phase-3-layout-assets-and-styling/laying-out-the-screen.mdx new file mode 100644 index 0000000..81afe04 --- /dev/null +++ b/src/content/docs/phase-3-layout-assets-and-styling/laying-out-the-screen.mdx @@ -0,0 +1,6 @@ +--- +title: Laying out the screen +description: Learn how to lay out your game UI using Gameface's powerful layout system. This section covers best practices for structuring your HTML, using CSS for responsive and scalable layouts, and managing assets like images and fonts to create visually stunning interfaces that perform well across different devices and aspect ratios. +sidebar: + order: 1 +--- \ No newline at end of file diff --git a/src/content/docs/phase-4-logic-and-interactions/mocking-data.mdx b/src/content/docs/phase-4-logic-and-interactions/mocking-data.mdx new file mode 100644 index 0000000..9041659 --- /dev/null +++ b/src/content/docs/phase-4-logic-and-interactions/mocking-data.mdx @@ -0,0 +1,6 @@ +--- +title: Mocking Data +description: Learn how to mock real game data to test your UI independently. This section covers best practices for simulating dynamic data, managing local versus game state, and creating realistic test scenarios to ensure your UI is robust and ready for integration. +sidebar: + order: 1 +--- \ No newline at end of file