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

    • Directoryhud

      • index.html
      • index.css
      • index.tsx
      • Hud.tsx
      • Hud.module.css
    • Directorymenu

      • index.html
      • index.css
      • index.tsx
      • Menu.tsx
      • Menu.module.css
• 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.

Tip

We recommend placing all custom components in this folder. This allows you to easily import them using the @custom-components alias throughout the project. For more details on using such imports, see the importing assets and components page.

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 typically includes an index.html, index.css, and index.tsx file, which collectively define its structure, styling, and behavior. This setup allows developers to work on multiple Views efficiently.

Note

For additional details about Views and how Gameface operates, refer to the following sections of the Gameface documentation:

• Workflow
• Technical Overview
• Rendering Architecture
• Cohtml View Class

Creating a View

To create a new View, follow the structure of src/views/hud or src/views/menu. Begin by creating a new folder src/views/${viewName} and include the following files: index.html, index.tsx, index.css, and ${viewName}.tsx.

Tip

Although not mandatory, it is recommended to create a ${viewName}.tsx file within the /src/views/${viewName} folder. This file defines the structure of the entry component rendered by the index.tsx file. For instance:

/src/views/hud/index.tsx

import { render } from 'solid-js/web';
import './index.css';
import Hud from './Hud';

const root = document.getElementById('root');

render(() => <Hud />, root!);

The Hud.tsx file would then return a JSX element:

/src/views/hud/Hud.tsx

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

export default Hud;

Using a separate file like ${viewName}.tsx promotes modularity and simplifies maintenance. It allows you to focus on the component’s structure and logic independently, while the index.tsx file handles rendering and initialization. This approach is especially beneficial for complex Views with multiple components.