Setting up the Gameface Stack

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: 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:

npx degit CoherentLabs/Gameface-UI 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.

Option B: Scaffold a SolidJS Project from Scratch

If you prefer full control over your setup, you can scaffold a clean Vite + SolidJS project yourself using the official create-solid tool and then apply a few Gameface-specific configurations.

This route is ideal if you want to build your own UI architecture and components entirely from scratch, without any pre-built boilerplate.

1. Create the Project

   Open a terminal in the directory where you want to create your project and run:

   npm init solid

   Follow the prompts to set up your project:

   • Project name: enter your desired project name (e.g. my-game-ui).
   • What type of project would you like to create? select SolidJS + Vite.
   • Use TypeScript? select Yes to use TypeScript.
   • Which template would you like to use? select basic.

2. Install Dependencies

   Navigate into your project directory and install the dependencies:

   cd my-game-ui
   npm install

   Known install issue

   The basic template may fail to install because of a problem resolving the solid-devtools dependency. As a temporary workaround, install the dependencies using npm i --legacy-peer-deps instead.

3. Configure Closing Tags

   By default, SolidJS optimizes performance by omitting the last closing tag of an element and the quotes around attributes. However, Gameface expects strict, valid HTML, so you must disable these optimizations to prevent console warnings and runtime errors.

   Set the following options to false in your vite.config.ts:

   • omitNestedClosingTags
   • omitLastClosingTag
   • omitQuotes

   Your vite.config.ts should look like this:

   import { defineConfig } from 'vite';
   import solidPlugin from 'vite-plugin-solid';
   import devtools from 'solid-devtools/vite';
   
   export default defineConfig({
     plugins: [devtools(), solidPlugin({
       solid: {
         omitLastClosingTag: false,
         omitNestedClosingTags: false,
         omitQuotes: false,
       }
     })],
     server: {
       port: 3000,
     },
     base: './',
     build: {
       target: 'esnext',
     },
   });

   Note

   The base: './' option ensures all assets are referenced relative to index.html when you build for production (npm run build). This lets you preview the build by drag-and-dropping the generated dist/index.html into the Player.

Once the configuration is complete, you can see how to preview the project in Gameface in the next section.

Helpful plugins

To smooth out the development experience, Coherent Labs also maintains a couple of Vite plugins worth considering:

• Gameface Vite Plugin — properly closes all HTML tags, fixes empty text nodes generated by SolidJS, and correctly quotes SVG attributes.
• Solid Style to CSS Plugin — converts inline style properties to class, improving performance through better caching and reusability.

Known limitations

• Routing: the official SolidJS router is currently not compatible with Gameface. If you need routing, use the routing solution provided by the Gameface UI library (Option A).
• Empty text nodes: SolidJS generates empty text nodes that older versions of Gameface may strip out, causing errors. Use Gameface v2.2.0 or greater to avoid this.

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:

   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:

   start "Player" /d "%wd%" "..\Player\Player.exe" --player %*"

   and add the following parameter to the end of the line:

   start "Player" /d "%wd%" "..PlayerPlayer.exe" --player "--url=http://localhost:3000/"

   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!

   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 http://localhost:3000/hud/ depending on which preset sample you wish to preview. Otherwise you will see a blank page.