Skip to content

SceneryStack Development Guide

Under Construction

This section and others in Getting Started with SceneryStack are under heavy revisement and will be updated in January 2025.

Introduction

Welcome to the SceneryStack development guide! This document is intended for developers who want to contribute to SceneryStack, an open-source library ecosystem for building interactive educational simulations in HTML5.

SceneryStack is built with a modular approach, making it versatile for creating simulations that integrate features like custom graphics, audio effects, animations, and accessibility. This guide will walk you through setting up your environment, understanding the repository structure, and starting your development journey.

For discussions and feedback, visit the SceneryStack Discussions forum.

Getting Started

Prerequisites

Before setting up your development environment, ensure the following tools are installed:

  1. Command Line Interface: Use Terminal (macOS) or Command Prompt (Windows).
  2. Git: Download from git-scm.com or install via Xcode command-line tools on macOS.
  3. Node.js and npm: Install the latest version from Node.js. After installation, run:
npm config set save false
npm config set package-lock false
  1. Grunt CLI: For building simulations, install Grunt globally:
npm install -g grunt-cli
  1. HTTP Server: To serve files locally, install a lightweight server:
npm install -g http-server

Setting Up the Project Directory

  1. Create a directory for the source code:
mkdir scenerystack
cd scenerystack
  1. Clone the repository:
git clone https://github.com/scenerystack/perennial
  1. Run the repository setup script:
./perennial/bin/clone-missing-repos.sh

Installing Dependencies

Install project dependencies:

  1. Navigate to the required directories and run:
cd chipper
npm install
cd ../perennial
npm install
cd ../perennial-alias
npm install

Development Workflow

Transpiling TypeScript

  1. Navigate to the build tools directory:
cd chipper
  1. Run the TypeScript transpiler with live reloading:
grunt transpile --live

Running a Simulation

  1. Serve the files locally:
cd scenerystack
http-server -c-1
  1. Open your browser and navigate to:
http://localhost:8080/example-sim/example-sim_en.html

Modifying and Testing

  • Modify the simulation source code in your text editor.
  • Refresh the browser to see the changes.

Building a Simulation

To create a production-ready build:

  1. Navigate to the simulation directory:
cd example-sim
  1. Run the build command:
grunt --brands=adapted-from-phet
  1. Access the built simulation at:
http://localhost:8080/example-sim/build/adapted-from-phet/example-sim_en_adapted-from-phet.html

Repository Overview

SceneryStack libraries are modular and follow the Model-View-Controller (MVC) design pattern. Here’s a breakdown of key repositories:

Core Libraries

  • Dot: Core math utilities (vectors, matrices).
  • Axon: Event-driven architecture with properties and emitters.
  • Tandem: Support for name-object registration and instrumentation.

Rendering and UI

  • Scenery: Graphics rendering engine (SVG, Canvas, WebGL).
  • Sun: UI components like buttons and sliders.
  • Twixt: Animation and tweening.

Interaction and Accessibility

  • Tambo: Audio effects and sonification.
  • UtteranceQueue: Accessibility support via ARIA live regions.
  • Tangible: Tangible input via computer vision.

Tooling

  • Chipper: Build tools for simulations.
  • Sherpa: Third-party libraries.

Contributing

Coding Standards

grunt lint
  • Add comments and documentation for maintainability.

Testing

  • Run unit tests after modifications:
cd tests
open unit-tests.html
  • Use query parameters for debugging:
  • ?ea: Enable assertions.
  • ?showPointerAreas: Visualize touch/mouse input regions.

Submitting Changes

  1. Create a new branch for your feature or fix.
  2. Commit changes with clear messages referencing any relevant issues.
  3. Submit a pull request for review.

Resources