Skip to main content

​
Prerequisites

Before you begin developing Utopia Fleet Builder, ensure you have the following installed:

Node.js

Version 14.x or higher recommended

Grunt CLI

Task runner for build automation

Git

Version control system

Text Editor

VS Code, Sublime, or your preferred editor

​
Installation Steps

1

Clone the Repository

Clone the Utopia Fleet Builder repository to your local machine:
git clone https://github.com/AngryTribble/Star-Trek-Attack-Wing-Utopia.git
cd Star-Trek-Attack-Wing-Utopia
2

Install Grunt CLI

If you haven’t already, install Grunt globally:
npm install -g grunt-cli
You may need to use sudo on macOS/Linux or run as Administrator on Windows.
3

Install Dependencies

Install all project dependencies using npm:
npm install
This installs:
  • Grunt and all build plugins
  • AngularJS dependencies
  • Development tools (ESLint, etc.)
  • Third-party libraries (jQuery PowerTip, etc.)
4

Build the Project

Generate the application files:
npm start
This runs the default Grunt build task, which:
  • Compiles and minifies JavaScript
  • Processes Angular templates
  • Minifies CSS stylesheets
  • Generates game data JSON
  • Copies assets to the build directory
5

Verify Installation

Check that the staw-utopia directory was created with the built files:
ls -la staw-utopia/
You should see:
  • index.html
  • js/ directory with minified JavaScript
  • css/ directory with minified stylesheets
  • data/data.json with game data

​
Directory Structure

After installation, your project structure should look like this: 
Star-Trek-Attack-Wing-Utopia/
├── src/                          # Source files (edit these)
│   ├── data/                     # Game data definitions
│   │   ├── ships.js
│   │   ├── captains.js
│   │   ├── upgrades.js
│   │   └── ...
│   ├── js/                       # JavaScript source
│   │   ├── common/               # Shared JS modules
│   │   └── *.js                  # App controllers/services
│   ├── css/                      # Stylesheet source
│   │   ├── common/               # Shared styles
│   │   └── *.css
│   ├── templates/                # Angular templates
│   │   ├── common/
│   │   └── *.html
│   ├── img/                      # Images and icons
│   ├── fonts/                    # Font files
│   └── *.html                    # Main HTML files
├── staw-utopia/                  # Built application (DO NOT EDIT)
│   ├── js/
│   ├── css/
│   ├── data/
│   └── index.html
├── node_modules/                 # Dependencies
├── package.json                  # NPM configuration
└── gruntfile.js                  # Build configuration
Never edit files in staw-utopia/ directly! These are generated files that will be overwritten on the next build. Always edit source files in src/.

​
Development Workflow

​
Available NPM Scripts

Runs the default Grunt build task. Equivalent to npm run build.
npm start
Use this for a one-time build of all assets.
Explicitly runs the Grunt build process.
npm run build
Watches source files for changes and automatically rebuilds:
npm run watch
Watches:
  • JavaScript files → triggers build-js
  • CSS files → triggers build-css
  • HTML templates → triggers build-js
  • HTML index files → triggers build-index
  • Data files → triggers build-data
  • Gruntfile itself → reloads configuration
Combines build and watch for active development:
npm run dev
This runs npm start followed by npm run watch.
Builds the project and starts a local HTTP server:
npm run serve
Opens the application at http://localhost:8000
Lints and regenerates only the game data:
npm run data
Runs:
  1. npm run lint-data - ESLint fixes data files
  2. npm run generate-data - Compiles data.json

​
Typical Development Session

1

Start Watch Mode

Open a terminal and start the file watcher:
npm run watch
Keep this running in the background.
2

Start Local Server

In a second terminal, start the HTTP server:
npm run serve
Open http://localhost:8000 in your browser.
3

Make Changes

Edit source files in src/:
  • Modify JavaScript in src/js/
  • Update styles in src/css/
  • Change game data in src/data/
  • Edit templates in src/templates/
4

See Changes

The watch task automatically rebuilds. Refresh your browser to see changes.
For data changes, you may need to clear browser cache or use hard refresh (Ctrl+Shift+R / Cmd+Shift+R).

​
Common Issues

Problem: Running grunt or npm start fails with “command not found”.Solution: Install Grunt CLI globally:
npm install -g grunt-cli
Problem: npm install fails with EACCES or permission errors.Solution: Either:
  • Use sudo npm install -g grunt-cli (not recommended)
  • Configure npm to use a different directory (recommended)
  • Use a Node version manager like nvm
Problem: Security warnings or deprecated package warnings.Solution: Update dependencies:
npm update
npm audit fix
Problem: Changes to source files don’t appear in the built application.Solution:
  1. Stop the watch task (Ctrl+C)
  2. Run a full rebuild: npm start
  3. Restart watch: npm run watch
  4. Hard refresh your browser

​
Next Steps

Once your environment is set up:

Build Process

Learn about Grunt tasks and the build system

Data Structure

Understand how game data is organized

Contributing

Guidelines for contributing code

Game Data

Learn about ships, captains, and upgrades

Build docs developers (and LLMs) love

Get started for freeTalk to us