Merge pull request #250 from nudibranchrecords/dev

v0.5.0

.babelrc

@@ -2,34 +2,35 @@
   "env": {
     "development": {
       "presets": [
-        [ "es2015", { "modules": false } ],
-        "stage-2",
-        "react"
+        "@babel/preset-env",
+        "@babel/preset-react"
       ],
       "plugins": [
+        "styled-components",
         "react-hot-loader/babel",
-        "transform-object-rest-spread"
+        "@babel/plugin-proposal-object-rest-spread"
       ]
     },
     "production": {
       "presets": [
-        [ "es2015"],
-        "stage-2",
-        "react"
+        "@babel/preset-env",
+        "@babel/preset-react"
       ],
       "plugins": [
-        "transform-object-rest-spread"
+        "styled-components",
+        "@babel/plugin-proposal-object-rest-spread"
       ]
     },
     "test": {
       "presets": [
-        "es2015",
-        "stage-2",
-        "react"
+        "@babel/preset-env",
+        "@babel/preset-react"
       ],
       "plugins": [
+        "styled-components",
         "react-hot-loader/babel",
-        "transform-object-rest-spread"
+        "@babel/plugin-proposal-object-rest-spread",
+        "@babel/plugin-transform-runtime"
       ]
     }
   }

.eslintignore

@@ -1,4 +1 @@
-coverage/**
-node_modules/**
-dist/**
-src/index.html
+node_modules

.eslintrc

@@ -4,27 +4,23 @@
     "standard",
     "standard-react"
   ],
-  "plugins": [
-    "babel",
-    "react",
-    "promise"
-  ],
-  "env": {
-    "browser" : true
-  },
   "globals": {
-    "__DEV__"               : false,
-    "__TEST__"              : false,
-    "__PROD__"              : false,
-    "__COVERAGE__"          : false,
-    "__DEFAULT_PROJECT__"   : false,
-    "nw"                    : false
+    "THREE": "readonly"
   },
+  "env": {
+    "browser" : true,
+    "jest/globals": true
+  },
+  "plugins": [
+    "jest"
+  ],
   "rules": {
     "key-spacing"          : 0,
     "jsx-quotes"           : [2, "prefer-single"],
     "max-len"              : [2, 120, 2],
     "object-curly-spacing" : [2, "always"],
-    "no-var"               : 2
+    "no-var"               : 2,
+    "comma-dangle"         : [2, "always-multiline"],
+    "no-console"           : [2, { "allow": ["warn", "error"] }]
   }
 }

config/webpack.custom.config.js

@@ -1,33 +1,12 @@
-const tryRequire = require('try-require')
-
 const config = {
   module: {
     rules: [
       {
         test: /\.icon\.txt$/,
-        use: 'svg-inline-loader?classPrefix'
-      }
-    ]
-  }
-}
-
-if (process.env.NODE_ENV === 'development') {
-  const devConfig = tryRequire('./dev.config.js', require)
-  let devServerOptions = {}
-
-  if (devConfig && devConfig.defaultProject) {
-    const defaultProject = require(devConfig.defaultProject)
-    const sketchesPath = defaultProject.project.sketchesPath
-
-    if (sketchesPath) {
-      devServerOptions = {
-        contentBase: sketchesPath,
-        watchContentBase: true
-      }
-    }
-  }
-
-  config.devServer = devServerOptions
+        use: 'svg-inline-loader?classPrefix',
+      },
+    ],
+  },
 }
 
 module.exports = config

docs/dev/index.md

@@ -8,8 +8,11 @@ It is best practice to create a project folder outside of Hedron. This is advant
 
 Inside the project folder, you'll want to have a "sketches" folder, this is what you'll point Hedron to.
 
+## Sketches Directory
+This directory contains sketch folders. Sketch folders can be grouped into directories to keep things neat, with as many levels of organisation as you need. However, you can't have a sketch folder inside another sketch folder.
+
 ## Sketch
-Sketches together in the sketches directory. A sketch is itself directory with two required files:
+Sketches live in the sketches directory. A sketch is itself a directory with two required files:
 
 - config.js
 - index.js
@@ -22,14 +25,20 @@ This is where the params and shots are defined.
 module.exports = {
   // Default title when sketch is loaded in (can be changed by user)
   defaultTitle: 'Solid',
+  // Category and author can be used as a way to organise sketches based on the user's settings
+  category: 'Simple',
+  author: 'Laurence Ipsum',  
   // Params are values between 0 and 1 that can be manipulated by the user
   // these values are sent to the sketch every frame
   // e.g. Speed, scale, colour
   params: [
     {
       key: 'rotSpeedX', // needs to be unique
-      title: 'Rotation Speed X', // should be human
-      defaultValue: 0 // must be between 0 and 1
+      defaultValue: 0, // must be between 0 and 1
+      title: 'Rotation Speed X', // optional, should be human, if not provided defaults to the key
+      defaultMin: 0, // optional, the value passed to the sketch when the param is at it's lowest value, if not provided defaults to 0
+      defaultMax: 1, // optional, the value passed to the sketch when the param is at it's highest value, if not provided defaults to 1
+      hidden: false, // optional, some params may want to be hidden in the UI, if they are controlled programatically by the sketch. Defaults to false.
     },
   ],
   // Shots are single functions that can fire, as opposed to values that change
@@ -45,14 +54,14 @@ module.exports = {
 
 ## index.js
 
-This is where the actual sketch is held. You can `require` other modules from here, so don't feel restricted to a single file.
+This is where the actual sketch is held. `THREE` is available as a global variable and it's strongly advised you use this rather than import the library yourself, to prevent unexpected behaviour. For convenience, `THREE.GLTFLoader` and `THREE.OrbitControls` are available too.
+
+You can `require` other modules from here, so don't feel restricted to a single file. 
 
 ### Very basic example
 This is the minimum you need to do in order to use Hedron.
 
 ```javascript
-const THREE = require('three')
-
 class MyFirstSketch {
   constructor () {
     // Create a cube, add it to the root of the scene
@@ -82,11 +91,6 @@ A polyhedron that can spin on all axes. The user can change the speed of the rot
 The user can change the scale. The user can also click on "shapeshift" and the geometry changes.
 **/
 
-/** HEDRON TIP **
-  Hedron uses three.js, so you'll need that :)
-**/
-const THREE = require('three')
-
 /** HEDRON TIP **
   Hedron sketches must be a class
 **/
@@ -97,17 +101,17 @@ class Solid {
     scene - This is the THREE object for the scene. You can also access the THREE renderer
     using scene.renderer
 
+    params - The sketch params when the sketch first initialises
+
     meta - This is an object with meta data that might be useful. It has the following properties:
       sketchesFolder - The path to the sketches folder on your computer. Useful if you need to link to a resource such as an image.
-
-    params - The sketch params when the sketch first initialises
   **/
-  constructor (scene, meta, params) {
+  constructor (scene, params, meta) {
     /** HEDRON TIP **
       Must define a "root" property as a THREE.Group or THREE.Object3D
       Hedron looks for this and will add it to the scene.
     **/
-    this.root = new THREE.Group()
+    this.root = new THREE.Group() // THREE is a global var so no need to import
 
     /** HEDRON TIP **
       It's good practice to not manipulate the root object
@@ -235,6 +239,13 @@ class Solid {
 module.exports = Solid
 ```
 
+## Reloading sketches / Auto reload
+If you have the "Watch sketches" setting enabled, Hedron will automatically refresh your sketches. However, if you don't have this enabled or something went wrong with the file watch (e.g. your sketch imports a file outside of its own folder) you'll need to click "Reload File" to see changes made to sketch files.
+
+This refresh will remove the sketch from the scene, import any new params or shots, remove and old params and shots, and then add the new sketch back into the scene.
+
+**Please note: File change detection may not work with all text editors. (e.g. Atom on OSX is reported to be inconsistent).**
+
 ## Hedron dev config
 
 You can get extra functionality by adding `dev.config.js` to `/config` (from the root directory of the Hedron repo).
@@ -246,10 +257,4 @@ module.exports = {
 }
 ```
 
-Setting `defaultProject` to the path of a saved project (e.g. `/Users/alex/Desktop/foo.json`) can help improve your workflow when developing:
-* The project will load automatically on load/restart
-* The project sketches folder will be watched for changes, triggering a restart
-
-## Reimporting
-
-If you've already got a project going with some sketches and then make edits to a sketch, Hedron automatically loads in the new content. However, if you've made changes to `config.js`, you'll need to "reimport" to see the new params and shots. Do this by clicking the button at the bottom of the view for that sketch.
+Setting `defaultProject` to the path of a saved project (e.g. `/Users/alex/Desktop/foo.json`) can help improve your workflow when developing by  automatically loading that project when the app compiles. This is particularly useful when developing Hedron itself, so that you can test changes made to the app immediately, without having to manually load in a project each time.

docs/user-guide/index.md

@@ -5,18 +5,19 @@ Here is a quick overview of how to use Hedron.
 ## Sketches
 Sketches are created with [three.js](https://github.com/mrdoob/three.js/). They are a Javascript module that exports a single [THREE.Group](https://threejs.org/docs/#api/objects/Group), to be placed in the main scene. The different aspects of a sketch can be controlled using "params" and "shots".
 
-### Adding and removing sketches
 Many sketches can be added to the same Hedron scene. These can be multiple instances of the same sketch, or different types of sketches.
 
 In order to add sketches, click on the "+" in the right sidebar. If you're starting from scratch, you'll need to tell Hedron where your sketch folder is.
 
 To remove a sketch, click the delete button at the bottom of the view for that sketch.
 
+Use the dropdown menu on the Add Sketch scene to organise your sketches. If the author of the sketch has provided the correct meta data, you'll be able to organise based on category or author. Otherwise you can organise based on the folder structure of your sketches.
+
 ### Switching between sketches
 You can switch between different sketches that are already added to Hedron using the right sidebar.
 
 ## Params
-Params are the variables of a sketch. They are always a value between 0 and 1 (although more types of param are [planned](https://github.com/nudibranchrecords/hedron/issues/13)). The simplest way to control a param is to click and drag the value bar.
+Params are the variables of a sketch. They default to a value between 0 and 1 (although more types of param are [planned](https://github.com/nudibranchrecords/hedron/issues/13)). The simplest way to control a param is to click and drag the value bar.
 
 ### Adding an input to a param
 The real power of Hedron is the ability to link different inputs to a param. This can be audio, LFO or MIDI.
@@ -35,6 +36,15 @@ Some things to note:
 
  - Adding a MIDI input will involve a "MIDI learn" step
  - MIDI inputs are always active, they do not have an active/disabled state
+
+### Editing the range of a param
+Params can have their range extended or decreased, this can be useful if you want to change the range for a particular instance of a sketch, but not affect all other instances of the sketch, or change the default range of the script
+
+To edit the range of a param:
+
+ 1. Open the param by clicking on the area below the value bar
+ 2. Open the advanced options by clicking "Advanced"
+ 3. Edit the minimum/maximum fields, the fields update when you press Enter or the field loses focus
 
 ## Shots
 Shots are functions that the sketch has exposed for the user to have fun with. These could be things such as explosions, pre scripted animations, etc. The simplest way to control a shot is to click on the hit area for that shot.
@@ -46,8 +56,12 @@ Shots have a very similar system to adding inputs as params, so please refer to
  - MIDI should be a "note on" type control
  - Instead of LFO, shots have a "sequencer". The rows of the sequencer are **one beat** (quarter note) split into 8. Click on each step for when you want the shot to fire.
 
-## Reimporting shots and params
-If you've already got a project going with some sketches and then make edits to a sketch, Hedron automatically loads in the new content. However, if you've made changes to config.js, you'll need to "reimport" to see the new params and shots. Do this by clicking the button at the bottom of the view for that sketch.
+## Reloading sketches / Auto reload
+If you have the "Watch sketches" setting enabled, Hedron will automatically refresh your sketches. However, if you don't have this enabled or something went wrong with the file watch (e.g. your sketch imports a file outside of its own folder) you'll need to click "Reload File" to see changes made to sketch files.
+
+This refresh will remove the sketch from the scene, import any new params or shots, remove and old params and shots, and then add the new sketch back into the scene.
+
+**Please note: File change detection may not work with all text editors. (e.g. Atom on OSX is reported to be inconsistent).**
 
 ## Macros
 Macros make it possible to control many params at once. To start using macros, click on "Macros" on the right sidebar.
@@ -68,9 +82,6 @@ Improvements to macros are [planned](https://github.com/nudibranchrecords/hedron
 ## MIDI Devices
 Midi devices display on the left hand side, underneath the preview.
 
-### MIDI Banks
-You can change the current bank you are using for each device using the list of numbers next to that device. When assigning MIDI anywhere, it will default to the current bank you are on for that device.
-
 ## MIDI Clock
 By default, MIDI clock is generated by Hedron.
 
@@ -79,6 +90,15 @@ By default, MIDI clock is generated by Hedron.
 - You can manually edit the generated clock BPM, or disable it completely in the settings. (Project > Settings)
 - If you have an external MIDI clock connected, Hedron will detect it automatically. You should disable the generated clock if you are using an external one.
 
+## Audio Parameters
+By clicking on the audio level bars left of the clock controls you can edit parameters to change the shaping of the incoming audio. The controls affect the audio as follows.
+
+- **Levels Falloff** - This is the amount that the value passed on to the parameters gets reduced by each frame, when this number is low the value will quickly jump up with a sound, but take time to come back down to zero.
+- **Levels Smoothing** - This is how much the prior frames value will be blended with the current incoming audio value, adding smoothing will cause quick changes in volume, up or down, to change more slowly. When this number is at 0 there is no smoothing, and at 1 it will lock the current value of the audio levels.
+- **Levels Power** - This value controls a power function with an exponent between .5 and 3. When this parameter is low it will cause low audio levels to get boosted higher when this parameter is high, low levels will be passed through even lower, causing only values that were high to begin with to remain high.
+- **Normalize Levels** - This causes each frequency band to be normalized based on it's highest and lowest recorded values, this will help the parameters connected to audio move within their full range, as often the low end tends to be louder while the high end is quieter.
+- **Normalized Range Falloff** - This is how much the recorded high and low of each frequency band decreases/increases respectively each frame.
+
 ## Other features
 
 * Save or load using "Project > Save/Load/Save As..."

example-projects/logo/sketches/logo/config.js

@@ -0,0 +1,64 @@
+module.exports = {
+  defaultTitle: 'Hedron Logo',
+  params: [
+    {
+      key: 'colorH',
+      title: 'Color H',
+      defaultValue: 0.5,
+    },
+    {
+      key: 'colorS',
+      title: 'Color S',
+      defaultValue: 0.5,
+    },
+    {
+      key: 'colorL',
+      title: 'Color L',
+      defaultValue: 0.5,
+    },
+    {
+      key: 'aInt',
+      title: 'Ambient Light Intensity',
+      defaultValue: 0.1,
+    },
+    {
+      key: 'pInt',
+      title: 'Point Light Intensity',
+      defaultValue: 0.5,
+      defaultMin: 0,
+      defaultMax: 5,
+    },
+    {
+      key: 'logoRotSpeedX',
+      title: 'Logo Rot Speed X',
+      defaultValue: 0,
+    },
+    {
+      key: 'logoRotSpeedY',
+      title: 'Logo Rot Speed Y',
+      defaultValue: 0,
+    },
+    {
+      key: 'logoRotSpeedZ',
+      title: 'Logo Rot Speed Z',
+      defaultValue: 0,
+    },
+    {
+      key: 'logoScale',
+      title: 'Logo Scale',
+      defaultValue: 0.7,
+    },
+    {
+      key: 'sphereScale',
+      title: 'Sphere Scale',
+      defaultValue: 1,
+    },
+  ],
+  shots: [
+    {
+      method: 'resetLogoRot',
+      title: 'Reset Logo Rot',
+    },
+  ],
+}
+