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 scaffold these starter projects, we provide a command line tool called create-gameface-app . It downloads the template of your choice, optionally installs its dependencies, and leaves you with a project that is ready to run.

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:

npm create gameface-app -- --template gameface-ui --default

This command will run an installation wizard which will ask you to provide a name for your project and then install the needed dependencies.

Full wizard

Alternatively, you can run the command without any arguments to go through an interactive wizard that will guide you through the setup process.

npm create gameface-app

Option B: A Bare SolidJS Template

If you prefer full control over your setup, start from our bare solid template. It gives you a clean Vite + SolidJS + TypeScript project with all the Gameface-specific configurations already applied, but without any of the pre-built components from Option A.

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

To scaffold it, run:

npm create gameface-app -- --template solid --default

This command will run an installation wizard which will ask you to provide a name for your project, will install the dependencies, and leave you with a project that already renders correctly in the Player - no manual Vite configuration required.

This is not a stock create-solid project. Our Gameface tooling comes wired into vite.config.mts, so none of it is left for you to set up:

• The vite-plugin-gameface-styles plugin runs with isSolidProject: true and turns static inline styles into flat gf-prop--* classes. UnoCSS and presetGameface() decode those class names back into real CSS.
• The vite-gameface plugin applies the Solid-specific compile options the engine needs, loaded after the Solid plugin.
• vite-plugin-solid runs with explicit compiler flags that preserve closing tags and attribute quotes.
• eslint-plugin-gameface is wired to a gameface-models/Model.json file for data-binding checks.

You also get a sample entry screen, complete with an animated background, an achievements panel, player stats, and an interactive carousel menu, which doubles as a working reference for your own views.

Leave the Solid compiler flags alone

SolidJS omits the last closing tag of an element and the quotes around attributes by default to save bytes. Gameface expects strict, valid HTML, so the template already disables those optimizations. Turning omitLastClosingTag, omitNestedClosingTags, or omitQuotes back on brings the console warnings and runtime errors straight back.

Known SolidJS Limitations

Both starting points build on SolidJS, so these apply whichever option you picked.

• 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 project 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

   The Gameface UI template ships with a set of pre-built sample views (such as a main menu and a HUD). If you went with the Gameface UI template, append the sample’s route to the URL - for example http://localhost:3000/menu/ - to preview a specific sample. Check the template’s README for the full, up-to-date list of available views. Otherwise you will see a blank page.