Paper Playground Installation Guide¶

This guide will walk you through setting up Paper Playground, including hardware recommendations, installation, and troubleshooting. Follow each section to ensure proper configuration.

Hardware Requirements¶

For optimal performance, we recommend the following hardware. Check that you have these items available before starting:

• Minimum Setup: Basic requirements for running Paper Playground.
• Second monitor or TV
• Webcam (720p minimum)

• Color Printer for printing templates and materials

• Full Setup:

• Projector (2000 lumens minimum) for better visibility and interactivity

For further details on hardware specifications and recommendations, refer to our Hardware Guide.

Quick Installation Instructions¶

Here’s a streamlined process to install Paper Playground and get started quickly.

1. Check Dependencies: Ensure you have Git, Node.js, and npm installed by running the following commands:

   git -v  # Verify Git installation
   node -v # Recommended LTS version of Node.js
   npm -v  # Verify npm installation
   

If npm is not installed, follow these instructions to install it.

1. Install Paper Playground: Run these commands to clone the repository and install dependencies:

   cd ~
   git clone https://github.com/phetsims/paper-land.git
   cd paper-land
   npm install
   npm start
   

2. Access Paper Playground:

3. Open http://localhost:3000 in a web browser to access the main interface.
4. To access the camera page, go to http://localhost:3000/camera and ensure it’s working as expected.

Troubleshooting¶

If you encounter issues, use these common solutions.

Camera Access Issues¶

If the camera fails to open or prompts for access, it may not have permission in your browser settings.

• Fix: Open Chrome settings directly at chrome://settings/content/siteDetails?site=http%3A%2F%2Flocalhost%3A3000 and make sure to enable camera access. Once done, reload the page and select your camera from the dropdown options.

Adjusting the Viewport Size¶

To match your projector’s display area with the interface, adjust the viewport by dragging the red circles in the interface corners. Proper alignment helps with accurate detection and interactivity.

Example of incorrect viewport alignment:

Running Example Programs¶

1. Open the Creator interface: Go to http://localhost:3000/creator to start working with example programs.

2. Suggested Start: Select the example “cat-fetch” and click “Send to Playground” to launch it in the main interface.

3. Open the Camera: Go to http://localhost:3000/camera to monitor the camera view, ensuring it detects objects accurately.

4. Open Interactive Display & Canvas To execute your code setup, open the Interactive Display (http://localhost:3000/display.html) (on a second window or screen) and Canvas (http://localhost:3000/projector.html) (can be hidden on another tab).

5. Preview Programs: Use the 'eye' icon besides each program to execute the paper programs that script the "Cat," "Ball," and "Items". Move them around! Go back to Creator to make edits and repeat the process!

6. Print the Programs: Click the print option for each program to print the paper itself and set up the physical play space.

You’re all set to start exploring Paper Playground’s capabilities!

Next Steps and Additional Resources¶

To expand your setup and explore more features, here are some recommended resources:

• Device Setup Guide: Follow the Device Setup Guide for comprehensive hardware configuration and troubleshooting.
• Interface Overview: Get familiar with the camera and other interfaces with the Interface Overview.
• Creator Tutorial: Start coding with the Creator Tutorial for more advanced use.

Developer Details¶

The Paper Playground client runs locally. For program storage, Paper Playground uses your device's local storage by default. If you would like to support multiple users editing or accessing paper programs, you can configure a remote, hosted database OR a local PostgreSQL database.

To run the client, you need a command-line interface and a few other software components.

Install the Client¶

1. Install Node.js/npm, Git, and a command-line interface, CLI (e.g., Bash, Terminal, Command Prompt, etc.).

   Note: Some users have reported issues installing newer versions of Node.js/npm on older macOS versions. Verify the last supported Node.js/npm version for your operating system.

2. In your CLI, navigate to the directory your wish to install Paper Playground: e.g., cd {insert directory}
3. Clone the repository using the following command: git clone https://github.com/phetsims/paper-land.git
4. Install the dependencies: npm install
5. (OPTIONAL) Set up the database (see instructions below for Remote or Local database).
6. Start the tool: npm start
7. Open localhost:3000 in your browser and follow the links on the landing page.

Start up Paper Playground¶

You should be good to go! Move on to setting up your devices or straight to the interface overview to get started creating and testing your paper programs!

Paper Playground comes with a host of spaces and projects that will be installed by default in your local storage found in root/server/default-data. Check them out!

The programs you create are stored in root/server/data.

Recommended start up if following development¶

Currently, Paper Playground must be run from the command line. If you're following the development of Paper Playground, it is recommended to regularly execute the following commands:

1. git pull
2. npm install
3. npm start

(OPTIONAL) Installing Database for Collaborative Editing¶

1. create a .env file (no prefix, usually creates a hidden file in your OS) in the root of paper-land and
2. Write a key:value pair on a new line to provide Paper Playground with: STORAGE_TYPE=postgresql

Remote Database¶

If you are using a remote program database, which you can find online by searching "PostgreSQL database hosting" (paid), or by setting up your own (advanced):

1. create a .env file in the root of paper-land and

2. Write a key:value pair on a new line to provide Paper Playground with a remote database address under DATABASE_URL.

3. Example: DATABASE_URL=postgres://someDatabaseAddressFromSomeHostingService

Local Database¶

If you do not have access to a remote database, you can host a local database on your computer using PostgreSQL.

• You will need to install PostgreSQL.

Setting up PostgreSQL database permissions¶

• Edit pg_hba.conf file (found in PostgreSQL installation directory) by changing auth method “scram-sha-256” for local to “trust”
• you can be risky and set everything to “trust” if you’re having trouble, just make sure to change that if you ever do anything else with SQL.
• Example paths:
  • (WINDOWS) C:\Program Files\PostgreSQL\15\data\pg_hba.conf
  • (MacOS) Library\PostgreSQL\15\data\pg_hba.conf
• In terminal (make sure PSQL is in your PATH for Windows):
• Add a new user that matches your OS username. Be careful to match the case of the OS user and include semicolon. Following commands:
  • psql -U postgres
  • create role "Username"; // replace Username with name matching your OS username (include quotes though)
  • alter role "Username" superuser createrole createdb login;
  • \du to see the role
  • exit to leave the psql in the terminal

Initial Run¶

• [FIRST TIME - INITIAL SETUP ONLY] Use following command to create the database the first time in terminal
• npm run dev

Packaged Paper Playground¶

To package the project so that it is sharable, we have custom build scripts that include necessary files and make it easy to install dependencies. While a standalone executable may be possible in the future, it is not currently available. For additional details and history on the packaging process, see https://github.com/phetsims/paper-land/issues/259.

We require that you have Node.js installed on your system to run these scripts. Once you have Node.js you can run paper-playground by clicking on the setup executables.

Building your own package¶

If you are interested in packaging the project yourself, you can use the following steps:

1) Install pkg globally: npm install -g pkg. pkg is used to package setup scripts into an executable. 2) Run npm run build to build the project. This will create a build directory in the root of the project. 3) Within the build directory are platform specific executables that a user can run to install node modules and run the project. 4) It also includes a .env file where you can configure variables for the project.

• Note that there are other build scripts to build individual parts of the project (front end, server, etc.). See package.json for more details.
• Note that this process requires the user to have Node.js installed on their system. A fully standalone build is not supported at this time.