Shader Playground Workflow Classroom Exercises Playground
How to Get Started

Workflow

Install the project on whatever machine you are sitting at, run the server, edit a shader in conversation with a language model, save, see the change, commit to your fork. A short reference, because most students repeat the first step every class — lab computers tend to clear out between sessions.

Nothing here is novel. It is a standard web-development workflow with a language model added to the conversation. What follows is the short version: five stages of the loop you will be in all semester, each written so you can find the step you need without reading the page from the top.

Setup

Five steps: install Node, download the project, install its dependencies, start the local server, open the URL in a browser.

All of it happens at a command line. On macOS, open the Terminal app (⌘+Space, type terminal). On Windows, open PowerShell (Start menu, type powershell). On Linux, open whichever console your distribution ships with.

Install Node

On macOS, the simplest route is nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Add the following to ~/.zshrc (or ~/.bashrc):

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Reload your shell and install Node:

source ~/.zshrc
nvm install --lts

On Windows, install Node.js from nodejs.org using the standard installer. In PowerShell, confirm node -v and npm -v both print version numbers.

Download the project

Pick a folder where you keep your code (your home directory is fine), then clone the repository there:

cd ~
git clone https://github.com/douglasgoodwin/shader-playground.git
cd shader-playground

Or download the ZIP from GitHub and unzip it somewhere under your home directory. Either way, the rest of the steps happen from inside the shader-playground folder.

Install dependencies

From inside shader-playground:

npm install

Start the server

npm run dev

A local URL — usually http://localhost:5173/ — will be printed in the terminal.

Open the URL

Open the URL your terminal printed in a browser. You now have the playground running on your machine. Ctrl+C in the terminal stops the server when you are done.

The source tree

With the server running in development mode, a small panel appears in the bottom-left corner of every shader page: a tree of the files that feed that page, with the entry JS at the top and each imported shader below it.

Every filename in the panel is a link. Click it, and the file opens directly in Visual Studio Code on your machine. This uses the vscode:// URL scheme, which macOS and Windows both understand when VS Code is installed.

The panel is there so you don't have to hunt for the right file. A shader page is usually the result of three to five small files — an entry JS, a vertex shader, one or two fragment shaders, a CSS. Click the one you want to change. Your editor opens at that file.

If VS Code isn't your editor, you can either associate the vscode:// handler with another tool, or use the panel as a map and open files by hand.

The prompt loop

This is the daily work.

  1. Open a shader page in the browser. Find the file you want to change in the source tree — usually a .glsl file.
  2. Click to open it in your editor. Copy the whole file into the conversation with your language model.
  3. Describe the change in plain English. One change at a time. "Make the circle pulse with time." "Add a second circle that orbits the first." "The gradient should go left to right, not top to bottom."
  4. Paste the result back into the file. Save.
  5. The browser hot-reloads. The change appears immediately.
  6. Iterate. Keep the loop tight.

If the model produces code that does not compile, paste the exact error text into the conversation. The model parses errors much better than it parses descriptions of errors. If a conversation has drifted into a stuck place, start a fresh session; the same question sometimes gets a better answer from a new transcript.

Making a new shader

Once you want your own work rather than edits to someone else's, you'll make a new shader. Three small edits, always in the same order.

  1. Copy an existing shader. In src/shaders/<section>/, duplicate the .glsl file that's closest to what you want. Rename it.
  2. Register it in the entry JS. Open src/<section>.js. Add an import for your new file near the top, and add it to the shaders registry below.
  3. Add a button. Open <section>/index.html. Copy one of the existing <button data-piece="..."> lines and change the name.

Save all three. Refresh the page. Your new shader appears in the button bar. Every shader in the project was made this way.

Your own fork

When the work is yours, it should live in your repository, not in the one you cloned.

  1. Fork the shader-playground repo on GitHub. GitHub will give you a URL for your copy.
  2. Point your local clone at your fork. In the terminal, inside your shader-playground directory: 
    git remote set-url origin https://github.com/YOUR_USER/shader-playground.git
  3. Commit your changes with a short message: 
    git add .
git commit -m "added a radial pulse shader"
  4. Push to your fork: 
    git push

Your work now lives on GitHub. The next time you sit down at a lab machine, you clone your fork instead of mine. Everything you made comes back.

Between classes

If the setup stages feel repetitive, that is the trade you make for working on a different machine every day. Most students settle into the rhythm within two or three class meetings. When a step fails, paste the exact terminal output into your language model and say which step you were on — you'll usually be unstuck in a few minutes.

Visit the Classroom  ·  Back to the Playground