Template structure & usage

This page provides an in-depth explanation of the functionality and usage of GamefaceUI.

The boilerplate project is organized with the following structure:

Directorysrc
- assets
- Directorycomponents
  - DirectoryBasic/
    …
  - DirectoryLayout/
    …
  - DirectoryMedia/
    …
  - …
- Directorycustom-components/
  - …
- Directoryviews
  - global.scss
  - Directoryhud
    Hud.tsx
    Hud.module.scss
  - Directorymenu
    global.scss
    Menu.tsx
    Menu.module.scss
package.json
tsconfig.json
vite.config.mts

To provide a clearer understanding of the rationale behind this structure, we will explain it in greater detail.

Project Configuration

The project’s configuration is managed through three key files: package.json, tsconfig.json, and vite.config.mts.

package.json: Handles project dependencies and defines scripts for running various commands.
tsconfig.json: Specifies TypeScript rules and settings for the project.
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.

Assets

The /src/assets 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.

GamefaceUI Components

Predefined components for streamlined UI development are located in the /src/components directory. For detailed information about each component and its usage, refer to the components section of the documentation.

Custom Components

The /src/custom-components directory is reserved for components created during UI development.

Views

Gameface Views are standalone HTML5 pages paired with their respective JavaScript contexts. Each View represents a complete UI or a significant UI component. Since multiple Views can be instantiated, the /src/views directory is included in the boilerplate to help organize and manage them effectively.

Each View resides in its own folder within /src/views and holds a component file named after that folder. The HTML document and the code that renders the component into it are generated for you.

Creating a View

Create a folder src/views/${viewName} and add a ${ViewName}.tsx file to it that default exports the component. That is the whole requirement:

const Hud = () => {
  return <div>Hello</div>;
};

export default Hud;

The View is then served at http://localhost:3000/hud in development and built into dist/hud.

The folder name and the component file name are matched loosely - case and separators are ignored - so chart-playground/ChartPlayground.tsx works as well as hud/Hud.tsx. Everything else the View needs (more components, helpers, assets) can live in the same folder.

Styling a View

${ViewName}.module.scss is scoped to the component through CSS modules, which is where most of a View’s styles belong:

import styles from './Hud.module.scss';

const Hud = () => {
  return <div class={styles.Hud}>Hello</div>;
};

export default Hud;

Rules that have to apply globally - html and body, @font-face, element selectors - go in a global.scss (or global.css) file. There are two levels, both optional:

/src/views/global.scss is applied to every View. The boilerplate uses it for the root font size and to make the body fill the viewport.
/src/views/${viewName}/global.scss is applied to that View only, and is loaded after the shared one so it can override it.

Both are loaded before the View’s own module styles.

@font-face {
  font-family: 'Cinzel';
  src: url('../../assets/fonts/Cinzel-Regular.ttf') format('truetype');
}

body {
  background-color: black;
  color: white;
}