Victory
+
+
+
+
+ Reward Unlocked
+ +Embedded HTML in SVG
+
+
+
+```
+
+From here, all map movement and zooming comes from updating `viewBox`.
+
+The `viewBox="0 0 400 400"` value means:
+
+- Start viewing the SVG from coordinate `0, 0`.
+- Show `400` units horizontally.
+- Show `400` units vertically.
+
+:::note[Match the authored coordinate space]
+
+`viewBox` values should match the coordinate space your SVG was authored in. If your paths were drawn in a `0..400` by `0..400` space, use
+`viewBox="0 0 400 400"` as the baseline.
+
+This also sets camera bounds. With a `400x400` authored map, the camera's max top-left position is computed from `MAP_WIDTH - visibleWidth` and
+`MAP_HEIGHT - visibleHeight`, where `MAP_WIDTH` and `MAP_HEIGHT` are both `400`.
+
+Aspect ratio still matters, but ratio alone is not enough. The coordinate range must align with how the SVG content is authored.
+
+:::
+
+```css title="minimap.css"
+.map-frame {
+ width: 56vh;
+ height: 56vh;
+ border: 0.12vh solid #2a3b49;
+ border-radius: 0.8vh;
+ overflow: hidden;
+ background: #0f151c;
+}
+
+.world-map {
+ width: 100%;
+ height: 100%;
+}
+```
+
+Here the map is sized with `vh` so it scales with the game viewport. You could use `px`, `vh`, `vmax`, or a layout-specific variable. The `viewBox`
+logic would stay the same because `viewBox` does not use CSS units. It uses the SVG's internal coordinate system.
+
+In other words, `width: 56vh` and `height: 56vh` only define the final UI box on screen. The internal map is still `400x400` SVG units, and every
+point, road, marker, and region is interpreted inside that coordinate space. When the UI box grows or shrinks,
+
+
+
+
+```
+
+```css title="hud-wrapper.css"
+.hud-safezone {
+ position: relative;
+ width: 100vw;
+ max-width: 100rem; /* Locks the UI to a specified width */
+ height: 100vh;
+ margin: 0 auto; /* Centers the container horizontally, creating safe zones on either side on ultrawides */
+}
+
+.health-bar {
+ position: absolute;
+ bottom: 3rem;
+ left: 3rem;
+}
+
+.minimap {
+ position: absolute;
+ top: 3rem;
+ right: 3rem;
+ width: 15rem;
+ height: 15rem;
+}
+```
+
+:::note[The Tradeoffs]
+This is structurally robust and highly performant because it avoids media query recalculations entirely.
+It guarantees your HUD never stretches beyond a specific boundary, it's great for simple use cases.
+
+However... it acts as a global constraint. If a specific element within that wrapper needs to bleed out to the screen edge or be positioned differently, the wrapper restricts it.
+Furthermore, you lose granular aspect ratio control. A wrapper cannot smoothly fade the opacity or scale down an element *only* when the screen hits a 21:9 ratio.
+
+**For that level of control, you need media queries.**
+:::
+
+### Approach 2: Pure Aspect-Ratio Media Queries
+
+Gameface supports the `aspect-ratio`, `min-aspect-ratio`, and `max-aspect-ratio` media features. This allows for granular control over individual elements rather than the entire screen.
+
+Designers often want to push critical elements (Health, Minimap) inward to a safe zone on an ultrawide, while keeping non-critical elements (Chat Box, Damage Vignettes) glued to the true edges for maximum immersion.
+Furthermore, media queries allow you to change other properties—like shrinking elements or lowering opacity—specifically for extreme screen shapes.
+
+Here, we leave the chat box on the left edge of the screen, but selectively push the minimap inward.
+
+```html title="hud-media.html"
+
+ System: Welcome...
+
+
+```
+
+```css title="hud-media.css"
+/* The Chat Box always stays glued to the extreme left edge for immersion */
+.chat-box {
+ position: absolute;
+ bottom: 2rem;
+ left: 2rem;
+}
+
+/* 1. Default 16:9 Anchor for the Minimap */
+.minimap {
+ position: absolute;
+ top: 2rem;
+ right: 2rem;
+ width: 15rem;
+ height: 15rem;
+}
+
+/* 2. Ultrawide (21:9): Push inward slightly so it doesn't spread out */
+@media (min-aspect-ratio: 21/9) {
+ .minimap {
+ right: 15vw;
+ transform: scale(0.9); /* Shrink slightly so it doesn't block the wider cinematic view */
+ }
+}
+
+/* 3. Super-Ultrawide (32:9): Push heavily inward into the player's safe zone */
+@media (min-aspect-ratio: 32/9) {
+ .minimap {
+ right: 25vw;
+ transform: scale(0.8); /* Shrink so it doesn't block the wider cinematic view */
+ opacity: 0.7; /* Lower opacity to reduce peripheral distraction */
+ }
+}
+```
+
+:::note[The Tradeoffs]
+Allows fine control over every individual element. But managing dozens of media queries for every single UI element can become verbose, hard to maintain and slightly less performant than a pure structural wrapper.
+:::
+
+### Complex UIs use both!
+
+If your UI is complex enough to require both rigid centering and granular aspect ratio tweaks, the best practice is to combine both approaches.
+
+You create two separate layers: an **Edge Layer** (for immersive, full-screen elements) and a **Safe Zone Layer** (for critical HUD elements).
+
+This gives you the structural safety of Approach 1, but allows you to use `min-aspect-ratio` media queries to achieve granular UX tweaks when the player is on a massive screen.
+
+```html title="hud-hybrid.html"
+
+
+
+
+ System: Welcome...
+
+
+
+
+```
+
+```css title="hud-hybrid.css"
+/* --- STRUCTURAL LAYERS --- */
+.edge-layer {
+ position: absolute;
+ width: 100vw;
+ height: 100vh;
+}
+
+.safe-zone-layer {
+ position: absolute;
+ width: 100vw;
+ max-width: 100rem; /* Locks the critical HUD to 16:9 */
+ height: 100vh;
+ left: 50%;
+ transform: translateX(-50%);
+}
+
+/* --- ELEMENT STYLING --- */
+.chat-box {
+ position: absolute;
+ bottom: 2rem;
+ left: 2rem;
+}
+
+.minimap {
+ position: absolute;
+ top: 2rem;
+ right: 2rem;
+ width: 15rem;
+ height: 15rem;
+}
+
+/* --- GRANULAR UX TWEAKS VIA MEDIA QUERIES --- */
+/* The minimap is already perfectly positioned by the safe-zone-layer.
+ We only use the media query to tweak its scale and opacity for super-ultrawide users! */
+@media (min-aspect-ratio: 32/9) {
+ .minimap {
+ transform: scale(0.8); /* Shrink so it doesn't block the wider cinematic view */
+ opacity: 0.7; /* Lower opacity to reduce peripheral distraction */
+ }
+}
+```
+
+:::tip[The Best of Both Worlds]
+In the Hybrid Approach, you never have to guess or calculate `vw` offsets to push elements around if they need to stick to the center.
+The defined size of the `.safe-zone-layer` handles the positioning automatically.
+
+You only use Media Queries when you want to execute highly specific design changes based on the screen's shape, leaving your CSS clean, scalable, and easy to maintain.
+:::
+
+## Resolution vs. Orientation Queries
+
+While `aspect-ratio` is your primary tool for responsive game UI, Gameface also supports specific size and orientation expressions: `min-width`, `max-width`, `min-height`, `max-height`, and `orientation`.
+
+You can chain multiple expressions together using the `and` operator to create highly specific targeting.
+
+* **`min-width` / `max-width`:** Use these when a specific UI component physically runs out of room to render its content correctly. For example, if your settings menu becomes illegible below 1280px wide regardless of the aspect ratio, use `@media (max-width: 1280px)` to switch the layout to a more compact design.
+* **`orientation`:** Gameface supports the values `landscape` and `portrait`. If you are developing a mobile game or a companion app, the player might physically rotate their device, altering the width/height ratio.
+
+For example, you can seamlessly switch a mobile inventory layout from a horizontal grid to a vertically scrolling list when the device is held upright:
+
+```css title="mobile-inventory.css"
+/* Default: Landscape (Horizontal Layout) */
+.inventory-grid {
+ display: flex;
+ flex-direction: row;
+}
+
+/* Portrait (Vertical Layout) */
+@media (orientation: portrait) {
+ .inventory-grid {
+ flex-direction: column;
+ }
+}
+```
+## Beyond Aspect Ratios: Custom Media Features
+
+Although managing aspect ratios is the most common use case for media queries, Gameface includes a powerful capability that extends this system:
+ 
+
+```
+
+Now, let's see how a standard nested CSS structure compares to a flat BEM structure, and why the engine prefers the latter.
**Before (Deeply Nested & Expensive):**
-```css title="menu.css"
+```css title="player-card.css"
/* Requires multiple node traversals during style recalculation */
-.nav-menu { background: #333; }
-.nav-menu ul { list-style: none; }
-.nav-menu ul li { padding: 10px; }
-.nav-menu ul li a { color: white; }
-.nav-menu ul li a.active { font-weight: bold; }
+.player-card { background: #222; }
+.player-card .info { display: flex; }
+.player-card .info .name { font-size: 1.2rem; }
+.player-card .info .status { color: green; }
+.player-card .info .status.offline { color: gray; }
```
**After (BEM - Flat & Performant):**
-```css title="menu.css"
-/* Engine immediately identifies the target node without traversing parents */
-.nav-menu { background: #333; }
-.nav-menu__list { list-style: none; }
-.nav-menu__item { padding: 10px; }
-.nav-menu__link { color: white; }
-.nav-menu__link--active { font-weight: bold; }
+```css title="player-card.css"
+/* The engine immediately identifies the target node without traversing parents */
+.player-card { background: #222; }
+.player-card__info { display: flex; }
+.player-card__name { font-size: 1.2rem; }
+.player-card__status { color: green; }
+.player-card__status--offline { color: gray; }
```
-By refactoring to BEM, the engine only needs to check for a single class name (`.nav-menu__link--active`) rather than traversing four levels of DOM nodes. This drastically reduces the time spent matching CSS rules.
+:::tip[The Performance Win]
+By refactoring to BEM, the engine only needs to check for a single exact class match (like `.player-card__status--offline`) rather than traversing four levels of DOM nodes to confirm a match.
+This drastically reduces the time spent calculating styles during DOM updates.
+:::
-## Leveraging SASS
+## Leveraging CSS Preprocessors (SASS)
While BEM is fantastic for performance, writing out long class names manually can become tedious. This is where a CSS preprocessor like **SASS** becomes invaluable.
-SASS allows you to use the parent selector (`&`) to generate BEM class names dynamically, keeping your stylesheets clean and organized. Furthermore, SASS provides **variables** to standardize your UI colors and typography, and **mixins** to reuse layout patterns across different views without bloating the compiled CSS.
+SASS allows you to use the
+
+ xX_Sniper_Xx
+ Offline
+
+
+
+```
+
+```scss title="mixins.scss"
+// Define a mixin for a common game UI pattern: a full-screen absolute anchor
+@mixin absolute-fill {
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: 100vw;
+ height: 100vh;
+}
+
+// Define a mixin for perfectly centering flex content
+@mixin flex-center {
+ display: flex;
+ justify-content: center;
+ align-items: center;
+}
+```
+
+```scss title="death-screen.scss"
+// Use the mixins inside your BEM block
+.death-screen {
+ // Injects the absolute positioning logic
+ @include absolute-fill;
+ // Injects the flex centering logic
+ @include flex-center;
+
+ background-color: rgba(0, 0, 0, 0.8);
+
+ &__text {
+ color: red;
+ font-size: 5rem;
+ }
+}
+```
+
+:::note[The Performance Trade-off]
+When this SASS compiles, the properties inside the mixin are physically duplicated into every CSS class that includes it.
+While this slightly increases the final `.css` file size, it guarantees that the Gameface engine only has to evaluate a single, flat selector.
+In game UI, trading a tiny bit of memory for faster CPU style-matching is exactly what we want!
:::
## Alternative Approaches
@@ -146,32 +223,72 @@ If you prefer modern component-based styling over global BEM classes, there are
### CSS Modules
-CSS Modules automatically generate unique class names for your styles at build time (e.g., `.button` becomes `_button_1x89f_1`).
+CSS Modules provide a way to write standard CSS that is locally scoped to a specific component.
+When you use CSS modules, the build tool automatically generates unique class names for your styles (e.g., `.card` becomes `_card_1x89f_1`).
+
+This solves the problem of naming collisions without needing strict naming conventions like BEM.
-* **Pros:** Excellent style isolation out of the box. Selectors remain completely flat, making them highly performant for Gameface. This is fully supported by the Vite boilerplate (just name your file `[name].module.css`).
-* **Cons:** You lose some of the global pattern reusability that SASS mixins provide natively, requiring you to structure your components carefully.
+* **Pros:** Excellent style isolation out of the box. Because the generated hashes are unique, the selectors remain completely flat, making them highly performant for Gameface's style matching.
+This is fully supported by the `Vite` (just name your file `[name].module.css`).
+* **Cons:** You lose some of the global pattern reusability that SASS mixins provide natively, requiring you to structure your React/Solid components carefully to share logic.
-```tsx title="Button.tsx"
+```tsx title="PlayerCard.tsx"
// Importing the CSS Module maps the local class name to the hashed build name
-import styles from './Button.module.css';
+import styles from './PlayerCard.module.css';
-const Button = () => {
- // Renders as a flat selector: