fragment-tools 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Raphaël Améaume
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+<h1 align="center">Fragment</h1>
+<div align="center">A web development environment for creative coding</div>
+<br/>
+
+![Screen capture of Fragment, splitted in two columns, the left one has a centered canvas displaying squares arranged in a grid, the right column contains various controls for colors, variables and exports](https://github.com/raphaelameaume/fragment/raw/main/screenshot.png "Screen Capture of Fragment")
+
+`fragment` provides a simple API to work with `<canvas>`.
+
+## Features
+
+- Multiple rendering modes: [Canvas 2D](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API), [p5.js](https://github.com/processing/p5.js/), [three.js](https://github.com/mrdoob/three.js/), [WebGL fragment shaders](https://developer.mozilla.org/en-US/docs/Web/API/WebGLShader)
+- Built-in GUI from sketch files
+- Export `<canvas>` to images (.png, .webm, .jpg) or videos (.mp4, .webm, .gif) on the fly
+- Hot shader reloading & [glslify](https://github.com/glslify/glslify) support
+- Interactive sketches using *triggers*
+- Static build for production deployment
+
+## Installation
+
+`fragment` is not yet available on [npmjs.com](npmjs.com) so you need to clone and link the project in order to use it. It's only a few steps.
+
+```
+# clone the project
+git clone https://github.com/raphaelameaume/fragment
+
+# move to the project directory
+cd fragment
+
+# link the project
+npm link
+``` 
+
+You should now be able to run `fragment` from your command line. If you encounter any issues, you can read more about linking on [npmjs.com](https://docs.npmjs.com/cli/v8/commands/npm-link).
+
+## Usage
+
+```
+# create a new directory for your sketches
+mkdir ../sketches
+
+# move into that folder
+cd sketches
+
+# initialize npm for linking to work
+npm init
+
+# create a sketch from a template
+fragment ./sketch.js --new --template=2d
+```
+
+Learn more about the available flag options in the [CLI docs](./docs/api/CLI.md).
+
+## Example
+
+This is an example of a sketch drawing a blue circle on a black background with a custom control for the radius of the circle.
+
+```js
+export let props = {
+  radius: {
+    value: 10,
+    params: {
+      min: 4,
+      max: 30
+    }
+  }
+};
+
+export let update = ({ context, width, height }) => {
+  // draw background
+  context.fillStyle = '#000000';
+  context.fillRect(0, 0, width, height);
+
+  // draw circle
+  const radius = props.radius.value;
+
+  context.fillStyle = '#0000ff';
+  context.beginPath();
+  context.arc(width * 0.5, height * 0.5, radius, 0, 2 * Math.PI, false);
+  context.fill();
+};
+```
+
+Learn how to write your own sketch in the [API docs](./docs/api/sketch.md) or read the [examples](./examples/).
+
+## Contributing
+
+If you find issues, please [file one](https://github.com/raphaelameaume/fragment/issues) with details on how to reproduce it.
+
+Feel free to reach out on [Twitter](https://twitter.com/raphaelameaume) if you want to discuss the project.
+
+## Credits
+
+- [Vite](https://vitejs.dev/)
+- [Svelte](https://svelte.dev/)
+- The font used for display is the [JetBrains Mono](https://www.jetbrains.com/lp/mono/).
+- Icons are from [Iconic](https://iconic.app/)
+- A special thanks to [Matt Deslauriers](https://www.mattdesl.com/) for [canvas-sketch](https://github.com/mattdesl/canvas-sketch) and his multiple projects around generative-art tools.
+
+## License
+
+See [LICENSE.md](./LICENSE.md) for details.

package/bin/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import sade from "sade";
+import { run } from "../src/cli/index.js";
+
+sade('fragment [entry]')
+    .version('0.1.0')
+    .describe('Run a dev environment for fragment')
+    .option('-n, --new', 'Create file if it does not exist', false)
+    .option('-t, --template', 'Specify template to create the file from', '2d')
+    .option('-p, --port', 'Port to bind', 3000)
+    .option('-dev, --development', 'Enable development mode', false)
+    .option('-b, --build', 'Build sketch for production', false)
+    .option('--outDir', 'Directory used for static build', null)
+    .option('--emptyOutDir', "Empty outDir before static build", false)
+    .action((entry, options) => {
+        run(entry, options);
+    })
+    .parse(process.argv);

package/docs/README.md

@@ -0,0 +1,18 @@
+#### <sup>[fragment](../README.md) → [Documentation](./README.md)</sup>
+<br>
+
+## Guide
+- [About](./guide/about.md)
+- [Getting started](./guide/getting-started.md)
+- [Export a sketch](./guide/exports.md)
+- [Using external dependencies](./guide/external-dependencies.md)
+- [Using triggers](./guide/using-triggers.md)
+- [Hot Shader Reloading](./guide/hot-shader-reloading.md)
+- [Shortcuts](./guide/shortcuts.md)
+
+
+## APIs
+- [CLI](./api/CLI.md)
+- [Sketch](./api/sketch.md)
+- [Renderers](./api/renderers.md)
+- [Triggers](./api/triggers.md)

package/docs/api/CLI.md

@@ -0,0 +1,44 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [API](../README.md#apis) → CLI</sup>
+<br>
+
+# CLI
+
+Once `fragment` is properly [installed](../../README.md#installation), you can launch it and create sketches from the command line.
+
+## Usage
+
+`fragment [file] [opts]`
+
+## Examples
+
+```
+# Start fragment with an existing sketch
+fragment ./sketch.js
+
+# Create a new file on disk and start
+fragment ./sketch.js --new
+
+# Create a new file from a pre-defined template
+fragment ./sketch.js --new --template=three/orthographic
+```
+
+## Options
+
+| Flag | Shortcut | Description | Default |
+|---|---|---|---|
+|`--new`| `-n` | Create a new file and start | `false` |
+|`--template`| `-t` | Specify the type of template to use as source | `2d` |
+|`--port`| `-p` | Specify the server port.  | `3000` |
+|`--build`| `-b` | Build sketch for production  | `false` |
+|`--outDir`| `none` | Change directory used for production build  | `[/[sketch-name]` |
+|`--emptyOutDir`| `none` | Empty outDir before static build  | `false` |
+
+## Templates
+
+`fragment` currently supports the following templates:
+- [2d](../../src/cli/templates/2d.js)
+- [fragment](../../src/cli/templates/fragment.js)
+- [three/fragment](../../src/cli/templates/three-fragment.js)
+- [three/orthographic](../../src/cli/templates/three-orthographic.js)
+- [three/perspective](../../src/cli/templates/three-perspective.js)
+- [p5](../../src/cli/templates/p5.js)

package/docs/api/renderers.md

@@ -0,0 +1,80 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [API](../README.md#apis) → Renderers</sup>
+<br>
+
+# Renderers
+
+They described systems that take *sketchs* as input and output their results to a canvas. A renderer should be capable of displaying multiple skeches of the same *rendering* at the same time in the most efficient way possible, meaning it should share ressources between sketches whenever possible.
+
+A renderer can implement the [*hooks*](#hooks) described here in order to match requirements described above.
+
+## Hooks
+
+#### `init`
+- Type: `() => InitParams`
+
+Called once on the first time a sketch with matching rendering is mounted. Useful to create and save ressources that will be shared across sketches. The object returned from this function will spread as params and made available to sketch hooks.
+
+Example:
+```js
+// renderer.js
+export let init = () => {
+	let renderer = createRenderer();
+	let value = true;
+
+	return {
+		renderer,
+		value,
+	}
+};
+
+// sketch.js
+export let init = ({ renderer, value }) => {
+	console.log(value); // true
+};
+```
+
+#### `onMountPreview`
+- Type: `({ index: number, canvas: HTMLCanvasElement }) => MountParams`
+
+Called everytime a sketch is mounted or hot reloaded. The object returned from this function will spread as params and made available to sketch hooks.
+
+```js
+// renderer.js
+export let onMountPreview = ({ index }) => {
+	return {
+		previewIndex: index,
+	};
+};
+
+// sketch.js
+export let update = ({ previewIndex }) => {
+	console.log(previewIndex); // 0
+};
+```
+
+> ⚠️ InitParams and MountParams are both spread at the same level and in this order, so if you export an object key from `init()` and the same key for a different value from `onMountPreview`, `onMountPreview` value will take over as the spread happen {...InitParams, ...MountParams }.
+
+#### `onBeforeUpdatePreview`
+- Type: `({ index: number, canvas: HTMLCanvasElement }) => void`
+
+Called on each frame before `sketch.update()`.
+
+#### `onAfterUpdatePreview`
+- Type: `({ index: number, canvas: HTMLCanvasElement }) => void`
+
+Called on each frame after `sketch.update()`.
+
+#### `onResizePreview`
+- Type: `({ index: number, canvas: HTMLCanvasElement, width: number, height: number }) => void`
+
+Called for each preview when OutputParams.canvasSize or OutputParams.dimensions change.
+
+#### `onDestroyPreview`
+- Type: `({ index: number, canvas: HTMLCanvasElement }) => void`
+
+Called when a sketch is unmounted or hot reloaded.
+
+#### `resize`
+- Type: `({ width: number, height: number, pixelRatio: number }) => void`
+
+Called once when OutputParams.canvasSize or OutputParams.dimensions change.

package/docs/api/sketch.md

@@ -0,0 +1,216 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [API](../README.md#apis) → Sketch</sup>
+<br>
+
+# Sketch
+
+A sketch in `fragment` is the entry point of your project. Its API is fairly simple, supports different types of renderings and can grow in complexity.
+
+## Lifecycle
+
+Each time your sketch is saved, the previous one is destroyed and a new *lifecycle* is called. Internally, `fragment` will call available [exports](./#exports) from your sketch in this specific order.
+
+```js
+sketch.init();
+sketch.resize();
+sketch.update();
+```
+
+## Exports
+
+`fragment` leverages the power of [named ESM exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export), meaning that you can export various properties from your sketch entry point and they will be picked up on runtime.
+
+#### `init`
+- Type: `({ canvas: HTMLCanvasElement, width: number, height: number, pixelRatio, ...params: {...InitParams, ...MountParams }}) => void`
+
+| name | type | description |
+|---|---|---|
+| canvas | `HTMLCanvasElement` | The canvas element used for drawing |
+| width | `number` | Width of the canvas |
+| height | `number` | Height of the canvas |
+| pixelRatio | `number` | PixelRatio of the canvas |
+
+Depending on the rendering context, params can contain different things.
+
+> ⚠ Notice the spread operator `...` before `params`, this means that the rest of the object will be "collected" into a single object called `params`. The values defined here are available directly if you want:
+
+##### `rendering = "2d"`
+| name | type | description |
+|---|---|---|
+| `context` | `CanvasRenderingContext2D` | The context of the canvas |
+##### `rendering = "p5"`
+| name | type | description |
+|---|---|---|
+| `p` | `p5Instance` | The p5 instance |
+##### `rendering = "three"`
+| name | type | description |
+|---|---|---|
+| `renderer` | `THREE.WebGLRenderer` | The three.js WebGLRenderer |
+| `scene` | `THREE.Scene` | A instance of THREE.Scene |
+##### `rendering = "fragment"`
+| name | type | description |
+|---|---|---|
+| `frag` | `fragmentInstance` | The fragment instance |
+
+```js
+export let rendering = "2d";
+
+export let init = ({ context, width, height }) => {
+  context.fillStyle = '#ff0000';
+};
+```
+
+#### `update`
+- Type: `({ time: number, deltaTime: number, playhead?: number, playcount?: number }) => void`
+
+| name | type | description |
+|---|---|---|
+| time | `number` | Amount of time ellapsed since the start of fragment. In milliseconds |
+| deltaTime | `number` | Amount of time ellapsed since the last frame. In milliseconds |
+| playhead | `number` | If [`duration`](#duration) is defined, playhead will go from 0 to 1 every specified duration |
+| playcount | `number` | If [`duration`](#duration) is defined, playcount will increase of 1 every loop |
+
+#### `resize`
+- Type: `({ width: number, height: number, pixelRatio: number }) => void`
+
+| name | type | description |
+|---|---|---|
+| width | `number` | Width of the canvas |
+| height | `number` | Height of the canvas |
+| pixelRatio | `number` | PixelRatio of the canvas |
+
+#### `props`
+- Type: `SketchProps`
+
+See [SketchProps](#sketchprops) for details.
+
+#### `rendering`
+- Type: `string`
+- Values: `2d`, `three`, `p5`, `fragment`
+- Default: `2d`
+
+> ⚠ If you used either `three` or `p5` rendering, you'll need to install them from your project root directory in order to make it work.
+
+```
+npm install three --save
+```
+
+#### `duration`
+- Type: `number`
+- Default: `undefined`
+
+Setting a duration to a sketch will compute correct values for `playhead` and `playcount` in [`update`](#update) callback params.
+
+#### `fps`
+- Type: `number`
+- Default: `60`
+
+Change how many times `update()` is called in 1 second. Py default, the value is 60, meaning `update()` will be called on every *requestAnimationFrame*.
+If you set it to `0`, `fragment` will only call `update()` once at the end of the *lifecycle* and when `props` change.
+
+#### `name`
+- Type: `string`
+- Default: `[filename]`
+
+Change the value used for display in the monitor dropdown.
+
+#### `filenamePattern`
+- Type: `({ filename: string, suffix: string, year:string, month:string, day:string, hours:string, minutes:string, seconds:string, props: SketchProps }) => string`
+- Default: `({ filename, suffix }) => ${filename}.${suffix}`
+
+Change the filename pattern when exporting a file. By default, `fragment` will use the sketch filename and a timestamp to name your export like `sketch.js.2022.05.27-08.30.00.[extension]`.
+
+In order to reuse the timestamp in your own pattern, `suffix` is available as a parameter within the callback, but you can also deconstruct `{ year, month, day, hours, minutes, seconds}` to make up your own.
+
+> ⚠️ You don't need to specify the extension since this is handled internally by the [Exports](./modules.md#exports) module.
+
+The callback is also returning the sketch current props so you can use their values in your export name.
+
+Example: 
+
+```js
+export let filenamePattern = ({ filename, suffix, props }) => {
+  return `${filename}.${suffix}.radius=${props.radius.value}`;
+}
+```
+
+## SketchProps
+
+You can define `props` in your sketch files in order to create GUI elements and use their values directly in your code. `fragment` will attempt to infer the type of field you want based on values and params of the props.
+
+| value type | params | field |
+|---|---|---|
+| `number` | { disabled?: `boolean`, step?: `number` } | `<NumberInput>` |
+| `number` | { min:`number`, max: `number` } | `<ProgressInput>` + `<NumberInput>` |
+| `number` | { options?: `number[] \| object[{label?: string, value:number}]`} | `<SelectInput>`|
+| `string` | { disabled?: `boolean`} | `<TextInput>`|
+| `string` | { options?: `string[] \| object[{label?: string, value:string}]`} | `<SelectInput>`|
+| `function` | { disabled?: `boolean`, label?: `string` } | `<ButtonInput>`|
+| `number[](2)` | { locked?: `boolean` } | `<Vec2Input>`|
+| `number[](3)` | { locked?: `boolean` } | `<Vec3Input>`|
+
+Example:
+```js
+export let props = {
+  radius: {
+    value: 10,
+    params: {
+        min: 1,
+        max: 30,
+        step: 0.1
+    }
+  }
+};
+
+// use props.radius.value
+export let update = ({ context }) => {
+  const radius = props.radius.value;
+
+  context.arc(x, y, radius, 0, 2 * Math.PI); 
+};
+```
+
+You can force a type on a prop by assigning a `type` to your object like so:
+
+```js
+export let props = {
+  color: {
+    value: [255, 0, 255],
+    type: "color",
+  }
+}
+```
+
+You can also add a listener if you want to trigger a function when the prop value changes.
+
+```js
+function onColorChange({ value }) {
+  console.log("color has changed!", value);
+}
+
+export let props = {
+  color: {
+    value: [255, 0, 255],
+    type: "color",
+    onChange: onColorChange,
+  }
+}
+```
+
+A prop can be `hidden` so it doesn't show up in the Parameters module or in `build` mode.
+
+```js
+export let props = {
+  color: {
+    value: [255, 0, 255],
+    hidden: __PRODUCTION__,
+  }
+}
+```
+
+## Templates
+
+`fragment` comes with a bunch of pre-defined templates. See [CLI docs](./CLI.md#templates) for details.
+
+## Interactivity
+
+You can set up *triggers* in your sketch files to make them **interactive**. See [Triggers docs](./triggers.md) for details.

package/docs/api/triggers.md

@@ -0,0 +1,101 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [API](../README.md#apis) → Triggers</sup>
+<br>
+
+# Triggers
+
+## Mouse
+
+Mouse triggers are called when the event happens on the `<canvas>` used for your sketch.
+
+#### `onClick`
+- Type: `(listener(event:MouseEvent): function) => void`
+
+Register a `click` listener on the `<canvas>`.
+
+#### `onMouseDown`
+- Type: `(listener(event:MouseEvent): function) => void`
+
+Register a `mousedown` listener on the `<canvas>`.
+
+#### `onMouseUp`
+- Type: `(listener(event:MouseEvent): function) => void`
+
+Register a `mouseup` listener on the `<canvas>`.
+
+#### `onMouseMove`
+- Type: `(listener(event:MouseEvent): function) => void`
+
+Register a `mousemove` listener on the `<canvas>`.
+
+## Keyboard
+
+Keyboard triggers are called when the event happens on `window`.
+A `key` argument can be optionnaly passed to call the listener only when a specific key is typed. If a single function is provided, the listener will be called for every key typed. The `key` argument can also be an array, in this case it will be called for every key typed in the array.
+
+> ⚠ The `key` argument is case sensitive, so `onKeyPress('a', () =>)` and `onKeyPress('A', () =>)` is not the same thing
+
+```js
+import { onKeyPress } from "@fragment/triggers";
+
+export let init = () => {
+	onKeyPress(() => {
+		console.log("called for every keypress");
+	});
+
+	onKeyPress('a', () => {
+		console.log("called when 'a' is pressed");
+	});
+
+	onKeyPress('A', () => {
+		console.log("called when 'A' is pressed");
+	});
+
+	onKeyPress(['a', 'A'], () => {
+		console.log("called when 'a' or 'A' is pressed");
+	});
+};
+```
+
+#### `onKeyPress`
+- Type: `(key?: (string|string[]), listener(event:KeyboardEvent): function) => void`
+
+Register a `keypress` listener for `key` on `window`.
+
+#### `onKeyDown`
+- Type: `(key?: (string|string[]), listener(event:KeyboardEvent): function) => void`
+
+Register a `keydown` listener for `key` on `window`.
+
+#### `onKeyUp`
+- Type: `(key?: (string|string[]), listener(event:KeyboardEvent): function) => void`
+
+Register a `keyup` listener for `key` on `window`.
+
+## MIDI
+
+MIDI triggers are called when using a MIDI device after authorizing usage of the [Web MIDI API](https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API). 
+
+#### `onNoteOn`
+- Type: `(note?:(string|string[]), listener(event:MIDIEvent): function) => void`
+
+Register a listener called when `note` is played on. Notes: `["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]`.
+
+#### `onNoteOff`
+- Type: `(note?:(string|string[]), listener(event:MIDIEvent): function) => void`
+
+Register a listener called when `note` is played off. Notes: `["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]`.
+
+#### `onNumberOn`
+- Type: `(noteNumber?:(number|number[], listener(event:MIDIEvent): function) => void`
+
+Register a listener called when `noteNumber` is played on.
+
+#### `onNumberOff`
+- Type: `(noteNumber?:(number|number[], listener(event:MIDIEvent): function) => void`
+
+Register a listener called when `noteNumber` is played off.
+
+#### `onControlChange`
+- Type: `(control?:(number|number[]), listener(event:MIDIEvent): function) => void`
+
+Register a listener called when `control` changes.

package/docs/guide/about.md

@@ -0,0 +1,16 @@
+#### <sup>[fragment](../../README.md) → [Documentation](../README.md) → [Guide](../README.md#guide) → About</sup>
+<br>
+
+# About
+
+`fragment` started as an idea in 2017 when I did a VJ performance based on [three.js](https://threejs.org/) visuals with a friend. We had a couple of different scenes that could react to audio beats and MIDI inputs. All scenes were made at different times, with different stacks and MIDI inputs had to be programmed and reminded beforehand.
+
+In 2018, we did a projection mapping for MAPP Montreal, also made with [three.js](https://threejs.org/). Visuals were still reacting to the soundtrack but it was not live, we needed to export a video of the whole thing. As we were lacking time to find better solutions, we ended up using a computer capable of capturing the screen while still rendering at 60fps. Not ideal.
+
+In 2019, I became a freelance creative developer and extended the variety of my practices: web development, real-time graphics, and generative art. I felt the need of a sketching environment, who could support the range of needs of my previous and future projects:
+- programmable interface
+- reactive to different kinds of inputs (GUIS, keyboard, MIDI, mouse, sound...) from the code and the UI
+- fast as possible
+- images, videos or live exports
+
+So I spent the last 3 years building my own tool.