Merge pull request #18 from zarocknz/firework-designer

WIP: Firework designer

Author: zarocknz

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 DouG
+Copyright (c) 2017 Douglas McKechie.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,23 +2,41 @@
 Create fireworks on HTML canvas with Skyrocket.js
 
 ## Description
-Skyrocket.js is a JavaScript library which displays skyrocket fireworks on HTML canvas.
+Skyrocket.js is a JavaScript library which displays skyrocket fireworks on HTML canvas. Skyrockets launch from the bottom center of the screen, fly up, explode, then fade. There is a code generated background of a city skyline which is different each time the page is loaded. The message at the bottom center of the screen can easily be changed to fit the occasion.
 
-Skyrockets launch from the bottom center of the screen, fly up, explode, then fade.
+![Example](docs/img/Screenshot-Fireworks.png)
 
-Rocket properties are defined in rocket_definitions.js with rockets being picked at random.
+GreenSock's Animation Platform (GSAP) is used to power the rocket and explosion animations, the rest is plain JavaScript
+so you should be able to include this library in any web project you like.
 
-Also there is a code generated background of a city skyline which is different each time the page is loaded.
+## Design your own Skyrockets!
+One of the big features of this library is that you can create your own skyrockets using the visual designer
 
-GreenSock's Animation Platform (GSAP) is used to power the rocket and explosion animations.
+![Example](docs/img/Screenshot-Designer.png)
 
-## Example
-For an example, load the included index.html file in your browser.
+This allows you to visually design the explosion shapes and set the animation properties, then click a button to generate the JSON config needed by the skyrocket.js to use these in the fireworks show.
+
+Note: place the generated config in skyrockets/explosions.js
+
+Open tools/designer.html to get creating your own skyrocket explosions or edit existing ones.
+
+Another important file is skyrockets/colors.js which defines sets of colours used by the rockets. Add your own or adjust the existing colours by specifying the RGB values for the colours.
+
+## How to use
+For an example of how to use this library, load the included index.html file in your browser.
+
+A canvas must be included, along with the js files needed for the backdrop, skyrockets and their definition.
 
 As you will see there is a function called addFirework() which is called repeatedly to spawn new fireworks at a random interval.
 
+An explosion and colour are selected at random from those defined in skyrockets/colors.js and skyrockets/explosions.js
+
+You could choose specific colours and explosions if desired to suit a particular occasion. You will likely need to create your own as well because there are only a small number of included types.
+
 ## Tutorials and other documentation
-Sorry, there are none at this time. Currently this library is in a alpha state with the inital 0.0.1 created during a hackday. Please look at the included index.html and other source code for what is required.
+Sorry, there are none at this time. Currently this library is in a alpha state with the initial 0.0.1 created during a hackday. Please look at the included index.html and other source code for what is required and to read the comments.
+
+The visual designer in tools/designer.html should be pretty straightforward to use, just follow the on-screen instructions.
 
 ## Maintainer
 Douglas McKechie https://github.com/zarocknz
@@ -35,13 +53,13 @@ Special thanks to these people who collaborated with me on this during the hackd
 Also a big thank you to Catalyst http://www.catalyst.net.nz/ for having a hackday to celebrate 20 years and allowing us to get this open source library off off the ground.
 
 ## TODO
-Heaps, which may include the following (not in any particular order)...
-
-* Define more and better firework explosion shapes and colours
-* Perhaps de-couple firework explosion shapes from the colours so users can pick a shape and specify any colour
-* Allow images to be used for the rockets
-* Add launch and explosion sounds, either pre-recorded or perhaps audio API generated
-* Allow explosion particles to have tails (will aid in creating different looking explosions)
-* Allow the user to specify where along the screen (x axis) the rocket launches from rather than always in the center, perhaps there is an option for this to be random
-* Ensure that backdrop is optional and there are some config parameters for it
+May include the following...
+
+* Allow an image to be placed in the background of the designer (as a guide) which will make it easier to create complex shapes by "tracing" particles over the top.
+* Allow explosion particles to have tails which are lines (will allow for more interesting shapes).
+* Even more firework shapes and colour combinations.
+* Allow images to be used for the rocket bodies?
+* Add launch and explosion sounds, either pre-recorded or perhaps audio API generated?
+* Simplify the use of the library even more, ensuring things are nice an configurable.
+* Add the ability to queue up skyrockets in a particular order so can chain them to say particular messages such as "happy, 2018, everyone"
 * Create some documentation and examples

docs/img/Screenshot-Designer.png

@@ -22,7 +22,8 @@ <h3>Merry new year!</h3>
 
         <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/1.20.2/TweenMax.min.js"></script>
         <script src="js/backdrop.js"></script>
-        <script src="js/rocket_definitions.js"></script>
+        <script src="skyrockets/colors.js"></script>
+        <script src="skyrockets/explosions.js"></script>
         <script src="js/skyrocket.js"></script>
         <script>
         var canvas = document.getElementById('canvas');
@@ -33,11 +34,14 @@ <h3>Merry new year!</h3>
             // Check if the window has focus, only if yes then add more skyrockets. This is to prevent 100s of rockets
             // firing off if the browser tab has been in the background for some time.
             if (document.hasFocus()) {
-                // Choose a random firework from the definition of the fireworks above.
-                var randWork = Math.floor(Math.random() * skyrockets.length);
+                // Choose a random explosion and firework colour from those defined in the /skyrockets directory.
+                var randExplosion = Math.floor(Math.random() * explosions.length);
+                var randColor = Math.floor(Math.random() * colors.length);
 
                 // Create a new firework and launch it straight away.
-                fireworks[fireCount] = new Firework(fireCount, skyrockets[randWork]);
+                //++ @TODO it might be nice if the firework added itelf to the array and incremented the fireCount in
+                //++ its constructor rather than the developer having to worry about this.
+                fireworks[fireCount] = new Firework(fireCount, explosions[randExplosion], colors[randColor]);
                 fireworks[fireCount].launch();
 
                 // Increment this for next time.
@@ -53,10 +57,11 @@ <h3>Merry new year!</h3>
         canvas.onclick = function (e)
         {
             // Choose a random skyrocket.
-            var randWork = Math.floor(Math.random() * skyrockets.length);
+            var randExplosion = Math.floor(Math.random() * explosions.length);
+            var randColor = Math.floor(Math.random() * colors.length);
 
             // Create a new firework.
-            var rocket = new Firework(fireCount, skyrockets[randWork]);
+            var rocket = new Firework(fireCount, explosions[randExplosion], colors[randColor]);
 
             // Set target x and y to mouse poistion.
             rocket.targetX = e.clientX;

docs/img/Screenshot-Fireworks.png

@@ -1,3 +1,8 @@
+/*
+    This file contains the code which generates the sky scraper background. If you want to do your own custom
+    background, perhaps an SVG, then simply don't include this file on the index.html page.
+ */
+
 // Calculate the skyscraper dimensions
 function skyline() {
     // Get all backdrop divs by class name.