Getting Started with the Tool Chain

Foundation

Please keep in mind that the Foundation tool chain and its documentation are still a work in progress. Current tool chain features include:

  • Boilerplate project creation
  • Single-command project compilation
  • Debug in a stand-alone window (with Chrome developer tools at your disposal)
  • Easy project updates for newer versions of Foundation core files
  • Single-command build for desktop application targets (Windows, Linux, OS X)
  • More build targets (mobile) coming soon.
  • Works on Windows, Linux, and OS X

This guide relates to Foundation versions 0.7.0 and above.


1. Prerequisites

The Foundation tool chain is built on Node.js and uses NPM for dependency management. Before going any further, make sure you have Node.js and NPM installed. Any recent version will work, but if you want to match Foundation's development environment then the following versions are recommended:

  • Node.js 4.4.3 (LTS) or newer stable
  • NPM 2.15.1 (LTS) or newer stable

2. An Extra Step for Linux Users

If you're on a Linux-based system (Ubuntu in particular), run the following command from a terminal before proceeding:

node -v

If there are no errors, you can move on to the next section. If, however, node is not recognized as an executable command, there's one more step needed before you can proceed. Due to a package naming conflict in some Linux-based systems (Ubuntu), node is not recognized as an executable command. The alternative nodejs will not work with the Foundation tool-chain (this could be fixed internally, but an underlying dependency also relies on the node executable, rendering an internal fix useless). You can find more information on this issue here. The TLDR version is that you will need to run the following command before proceeding:

sudo update-alternatives --install /usr/bin/node node /usr/bin/nodejs 10

3. Download and Install Foundation

Download the latest tagged version of Foundation and extract the downloaded archive to a location of your choice. Foundation uses NPM for dependency management. To resolve all dependencies, simply open a terminal / console in the foundation/tools directory and run:

npm install

You're now ready to create your first project (that was simple!)


4. The Foundation Folder

This section describes the Foundation folder structure and you should take a moment to read over it. If, however, you're impatient to get going with your first project, skip ahead to section 5.

Once the above install has finished, your foundation folder contains all needed dependencies for the tool chain (apart from Node.js itself). Feel free to move it around your file system as much as you'd like. You can move it to another computer too, but with the following caveats:

  • You will only be able to use Foundation where Node.js is installed.
  • Some of the dependencies might be operating system specific. If you've taken foundation to a new OS and everything broke, you can simply delete the foundation/tools/node_modules directory, then run npm install from the foundation/tools directory to rebuild dependencies for the new system.

Now on to what you'll find in the foundation folder:

  • The foundation/.projectTemplates directory contains the project templates the tool chain uses to create a new project. Note that you cannot directly copy/paste a project from here--these projects are incomplete. In versions 0.8.0+ this folder moved to foundation/tools/.projectTemplates
  • The foundation/core directory contains the actual Foundation game library. Here you will find all of the Foundation types, non-compiled. When you create a new project, the tool chain compiles this library and copies it to your project. To learn how to update a project's core files, see the Project Structure page.
  • The foundation/projects directory is where you'll find all of your projects.
  • The foundation/tools directory contains all of the tool chain scripts and their dependencies.
  • The foundation/about.json file contains the current version number, and the minimum compatible version number.

5. Create Your First Project

To create your first project, open a terminal / console in the foundation/tools directory and run:

node scripts/createProject MyProject benchmark

This will create a new project with the title "MyProject" using the "benchmark" project template. There are 3 project templates available:

  • default: Used when no template is specified. Minimalist project with a rotating image which changes direction and makes a sound when clicked.
  • benchmark: Benchmark project. Click the screen to add more Nodeheads. Find out more on the templates documentation page.
  • particles: A small showcase of particle systems made with Foundation's simple particle generator.

Your new project will now be available in the foundation/projects directory. To run your project, change your working directory to the project folder and run the debug tool:

cd ../projects/MyProject
node tools/debug

Your project should open in a stand-alone window. If you used the benchmark template, click anywhere on the screen to add more Nodeheads. You can access Chrome Developer Tools with the f12 key. You can learn more about using the benchmark project from the link below.