Getting started

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:

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

Note that the HCJE when installed as a subproject in its default location will be in a folder at the same level as the project's source. When incorporating the HCJE, it will need to be referenced in the main index.html file as follows:

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

The _HCJE_ should now be installed ready for use. 

# Step 2: Modify _index.html_ to load the _HCJE_

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](getting-started) if this is unclear.

```html
<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();