Skip to content

Getting started

Jump to bottom
Steve Butler edited this page Aug 23, 2026 · 27 revisions

The following steps should help you get started with the HCJE.

Step 1: Add the HCJE to your project

The HCJE has been designed to facilitate incorporation into a project as a Git submodule. The build tools assume that if included as a submodule, the default name, hcje‑css‑js‑engine, will have been used and it will have been added to the root. So the structure for your files is expected to be:

Note that because the HCJE is installed as a subproject, its default location will be in a folder at the same level as the project's source. The typical folder structure is shown below.

myProject
    + source
        + index.html
        + other source files and required folders
    + hcje-css-js-engine
        + all the hcje files

When loading items from the HCJE, they will need to be referenced from the main index.html file by using ../ to traverse up a level outside of the source's root folder. This works for local testing, but will not work in the final build. To counter this problem, the build script automatically replaces any occurrences of ../html-css-js-engine/source/hcje/ with _hcje/ and places the HCJE files in a subfolder named _hcje.

The HCJE should now be installed ready for use.

Step 3: Add scripts to your package.json file

To utilise some of the tools in HCJE, you should modify your package.json file to facilitate running the scripts. Typically your scripts property should include the

  "scripts": {
    "prebuild": "npm run test",
    "build": "node ./html-css-js-engine/tools/build/build.js ./build-config.json",
    "test": "node ./html-css-js-engine/tools/testing/runner.js test-config.json",
    "serve-build": "node ./html-css-js-engine/tools/server/server.js 8080 build",
    "serve": "node ./html-css-js-engine/tools/server/server.js 8080 ."
  },

Add configuration files

The build and test commands require JSON configuration files, build-config.json and test-config.json respectively.

Step 2: Modify index.html to load the HCJE

Your index.html page will need to load the _HCJE_style sheet, your style sheet, the HCJE scripts, and finally your game scripts. The following code shows the way to do this.

<html>
  <head>
    …
    <link rel='stylesheet' href='../html-css-js-engine/source/hcje/styles/style.css'>
    <link rel='stylesheet' href='./styles/style.css'>
  <head>
  …
  <body>
    <p>Loading. Please wait.</p>
  </body>
  <script type = 'module' src='../html-css-js-engine/source/hcje/scripts/hcje-lib.js'></script>
  <script type = 'module' src='./scripts/index.js'></script>
</html>
<link rel='stylesheet' href='../html-css-js-engine/source/hcje/styles/style.css'>
…
<script type = 'module' src='../html-css-js-engine/source/hcje/scripts/hcje-lib.js'></script>

These commands allow the css and js files of the HCJE to be accessed from index.html in the project's source folder. However, although using ../ to traverse up a level outside of the source's root folder will work for local testing, it is not appropriate for the final build. As such, the build tools automatically flatten the HCJE folder and place the HCJE's script files in a subdirectory named _hcje and modify the link and script lines above. The resulting output will be:

outputFolder
  + index.html
  + other source files and required folders
  + _hcje

<link rel='stylesheet' href='_hcje/styles/style.css'>
...
<script type = 'module' src='_hcje/scripts/hcje-lib.js'></script>

All of the content of index.html page will be generated by the HCJE. However, as there may well be a delay in loading the HCJE your initial page should include some loading guidance which can be removed once the HCJE has loaded. An example index.html file is shown below.

Note the script src link to the HCJE script is loading the file from the HCJE submodule. This is modified during the build. See Getting started if this is unclear.

<html>
  …
  <body>
    <p>Loading. Please wait.</p>
  </body>
  <script type = 'module' src='../html-css-js-engine/source/hcje/scripts/hcje-lib.js'></script>
  <script type = 'module' src='./scripts/index.js'></script>
</html>

Step 3: Create the game area

We now need to use code in our index.js script to clear the loading information from the body and create the game area. Add the following code to your script. You can change the GAME_WIDTH_ and GAME_HEIGHT constants to your own preferred values.

const GAME_WIDTH = 672;
const GAME_HEIGHT = 420;

/**
 * The main game loop.
 */
function gameLoop() {
  // main code will go here.
}

/**
 * Start the game. Any body content is remove and the game area is created. Then a welcome dialog is displayed
 * before calling the main gameLoop function.
 */ 
function startGame() {
  document.body.replaceChildren();
  const gameArea = new hcjeLib.domTools.GameArea({
    width: GAME_WIDTH,
    height: GAME_HEIGHT,
  });
  const title = new hcjeLib.domTools.createChild(gameArea, 'p', 'game-title');
  title.innerText = 'My game';

  hcjeLib.domTools.createDialog({
    title: "Welcome",
    markdown: "Click the *PLAY* button to get started.",
    children: [],
    buttonDefns: [
      {id: 'PLAY', label: 'Play'},
    ]
  })
    .then((id) => {
    });
}

// execute the game
startGame();

Clone this wiki locally