Skip to content

Getting started

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

The following steps should help you get started with the HCJE. The HCJE has been designed to facilitate incorporation into a project as a Git submodule and contains build tools that run in a Node.js environment. No additional packages need to be added to the Node environment.

Note

In the code samples, function comments are minimal to keep the examples as short as possible. Also in some cases the code is deliberately not as efficient as possible in order to highlight certain features of the HCJE.

Add the HCJE to your project

This guide assumes that your current project structure looks something like this:

myProject
    package.json
    + source
        index.html
        + other source files and required folders

Tip

Although you can name the source folder to anything you like, src for example, keeping the name as above will make this guide easier to follow and reduce any necessary editing of the configuration files used by the project.

If you don't have a package.json file yet, you can run npm init from within your myProject folder.

To install the HCJE as a submodule in the project structure above, you can simple run the following command from within the myProject folder:

git submodule add https://github.com/henspace/html-css-js-engine source

The result should be:

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

Warning

Make sure the HCJE submodule is installed in the same folder as index.html and the rest of the source, and that its name is not changed from its default of html‑css‑js‑engine as this name and location are required for the build script to operate correctly.

The HCJE should now be installed ready for use.

Add scripts to your package.json file

First ensure that package.json includes the following lines and that the main property has been removed. We are only using package.json as a build tool and not for publishing Node packages.

"type": "module",
"private": true,

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

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

The build and test commands require JSON configuration files, build-config.json and test-config.json respectively. There are sample configuration files in the HCJE submodule in the folder resources_for_submodule_users. You can copy these into the root folder of your project alongside package.json.

Note

The default build configuration will not create a zip file of the resulting build. If you require a zipped version of the build, you will need to edit the build‑config.json file and set the zippedOutputDir property; if using Windows, you will probably need to alter the zipOptions.win32.cmd property as well.

Modify your game's 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 own 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>

Warning

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 by replacing html-css-js-engine/source/hcje with _hcje. As such it is important to write the references to the HCJE style and script files as shown above.

The result of the build process is summarised below.

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>

When we start writing our game code we will remove the content of the <body>. This means that index.html can contain any information we like to indicate to the user that we are loading.

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.

/**
 * Start the game.
 */ 
function startGame() {
  const GAME_WIDTH = 672;
  const GAME_HEIGHT = 420;
  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';
}

// execute the game
startGame();

The initialisation code is in a function named startGame and at the very bottom of the file we call startGame() to get going. The function clears the existing body, creates the game area and adds a title. If you run it, you should see a rather boring grey rectangle appear.

Note

Information about the createChild and createGameArea methods can be found in the hcje/domTools module documentation.

Add a welcome dialog

Most games have music, but music can only be started in HTML games in response to a user action. So, in most games you will want to start with a button being clicked. In this code modification, we'll make the following changes:

  • Create a gameLoop function. This will hold our main game code when we get round to writing it.
  • Modify startGame to create a welcome dialog and then call the gameLoop function.
/**
 * The main game loop.
 */
function gameLoop(gameArea) {
}

/**
 * Start the game.
 */ 
function startGame() {
  const GAME_WIDTH = 672;
  const GAME_HEIGHT = 420;
  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) => gameLoop(gameArea)) 
}

// execute the game
startGame();

If you run this code, you should finish up with a welcome dialog appearing that closes when you click the play button.

Note

information about the createDialog method can be found in the hcje/domTools module documentation.

Add a sprite

To make things a little more interesting, let's add a simple text sprite in our game loop

Modify the gameLoop function so it contains code to create and position a simple text sprite.

/**
 * The main game loop.
 */
function gameLoop(gameArea) {
  const mySprite = hcjeLib.sprites.createTextSprite(gameArea, "HELLO *WORLD*",
    { markdown: true,
      dimensions: {width: 64, height: 64}
    });
  const gameDimensions = gameArea.designDims;
  mySprite.position = {x: gameDimensions.width / 2, y: gameDimensions.height / 2, angle: Math.PI};
}

This code creates a simple text sprite and then positions it near the middle of the game area and rotated by 180°(π radians). It's not actually centred as the position property is the sprite's top-left corner and not its centre.

Note

Information about the Sprite class can be found in the hcje/sprites.Sprite documentation

That completes the getting started guide. To explore further techniques, check the other sections in this wiki.

Clone this wiki locally