Introduction

Forge is a browser-based, code only game engine. It has everything you would expect from an engine, including rendering, audio, input, animations, ECS, etc.

Let's begin with setting up a new project.

Getting Started

Installing Forge in your project

The Forge npm package is hosted on GitHub Packages, so you will need to authenticate npm against it before you can install the package.

a. Create a classic personal access token with the read:packages scope.

info
The Forge-Game-Engine organization requires personal access tokens to expire in 60 days or fewer, so you will need to set an expiration of 60 days or less and regenerate the token periodically.

b. Log in to the GitHub npm registry with that token, scoped to the @forge-game-engine package scope. When prompted, enter your GitHub username, the personal access token as your password, and any email address.
shell
```
npm login --scope=@forge-game-engine --registry=https://npm.pkg.github.com
```
This adds an .npmrc file adjacent to your package.json file that points the @forge-game-engine scope at the GitHub npm registry and stores your auth token, equivalent to running:
shell
```
echo '@forge-game-engine:registry=https://npm.pkg.github.com' >> .npmrc
echo '//npm.pkg.github.com/:_authToken=<YOUR_PERSONAL_ACCESS_TOKEN>' >> .npmrc
```
warning
Don't commit your personal access token. If you write the token into .npmrc directly, add .npmrc to your .gitignore, or reference an environment variable (e.g. _authToken=${GITHUB_TOKEN}) instead.
Install the forge package

shell
npm i @forge-game-engine/forge@latest

Creating the game instance

You will need to initialize the game in the entry point of your app. This will differ depending on the toolchain you use. For example, if you use vite with the vanilla-ts template. You will have an index.html file in the root of your app and a src/main.ts file. This file will be the "entry point" of your app.

Once you have identified where to initialize your game, use the createGame helper. It builds a Game, an EcsWorld, a RenderContext, and a Time instance for you from a container element's ID, and returns all four so you can wire up your game:

import { createGame } from '@forge-game-engine/forge/utilities';

const { game, world, renderContext } = createGame('game-container');

game.run();

Although this won't do anything just yet, world and renderContext are what we'll use next to get something rendering on screen.

Render a sprite in your scene

Load an image

We need to fetch an image for our sprite. Any HTMLImageElement will do. renderContext already carries an ImageCache for loading and caching images.

import { createGame } from '@forge-game-engine/forge/utilities';

const { game, world, renderContext } = createGame('game-container');

const { imageCache } = renderContext;
const image = await imageCache.getOrLoad('sprite.png');

game.run();

Create a sprite

We then need to create a sprite from that image:

import { createGame } from '@forge-game-engine/forge/utilities';
import { createImageSprite } from '@forge-game-engine/forge/rendering';

const { game, world, renderContext } = createGame('game-container');

const { imageCache } = renderContext;
const image = await imageCache.getOrLoad('sprite.png');

const sprite = createImageSprite(image, renderContext);

game.run();

Finally we need to add an entity to our world with a position and that sprite:

import { createGame } from '@forge-game-engine/forge/utilities';
import {
  createImageSprite,
  addSpriteComponent,
} from '@forge-game-engine/forge/rendering';
import { addPositionComponent } from '@forge-game-engine/forge/common';

const { game, world, renderContext } = createGame('game-container');

const { imageCache } = renderContext;
const image = await imageCache.getOrLoad('sprite.png');

const sprite = createImageSprite(image, renderContext);

const entity = world.createEntity();
addPositionComponent(world, entity);
addSpriteComponent(world, entity, sprite);

game.run();

Congratulations, you should now see something rendered to your screen! 🎉

Getting Started​

Installing Forge in your project​

Creating the game instance​

Render a sprite in your scene​

Load an image​

Create a sprite​