graphico 0.0.5 → 1.1.0

package/README.md

@@ -1,3 +1,23 @@
 ## Getting Started
 
-!!! THIS PACKAGE IS STILL UNDER DEVELOPMENT AND WILL BE UNSTABLE !!!
+`graphico` is a package used for creating games, animations, and other visual projects. It simplifies canvas 2D rendering within the browser and provides the foundation for user interaction.
+
+## Features
+
+`graphico` boasts several features that make it an extremely versatile package for several project types.
+
+- Simple, **object-oriented canvas API** for organized graphics programming
+- Easy debugging and extensive configuration for **complete customizability**
+- Supports multiple independent **canvas layers** with transparency
+- **Hardware-accelerated graphics** for fast and smooth animation
+- **User interaction** captured via keyboard inputs or mouse movements or clicks
+- Multiple audio tracks supported by system **audio player** with volume, mute, and loop toggle
+- Built-in logic for **screenshots** and **screen recordings** that capture both video and audio
+
+## Caveats
+
+By default, many browsers prevent autoplay, which arguably is a good thing. (Don't you hate it when you have several tabs open and one of them starts making noise?) This security feature blocks API calls to `Canvas.playAudio()` from being called automatically on page load. It needs to be triggered manually (initially) by some form of user interaction; either a key press or a mouse click. After this initial interaction step, calls to `playAudio()` can be performed automatically. If you wanted to have background music looping for a game, it would need to be triggered after pressing the "start" button, for example.
+
+## Learn More
+
+The best way to learn and experience its features is to try it out yourself. See the examples to learn how to use `graphico`!

package/dist/canvas.js

@@ -13,9 +13,9 @@ var Canvas = /** @class */ (function () {
         if (options === void 0) { options = {}; }
         var _this = this;
         /**
-         * Can be used to render 2D graphics onto the canvas
+         * Can be used to render 2D graphics onto layers of the canvas
          */
-        this.graphics = [];
+        this.layers = [];
         /**
          * Contains a list of current keys pressed
          */
@@ -44,43 +44,60 @@ var Canvas = /** @class */ (function () {
          * Determine whether the client is focused or not
          */
         this.focused = false;
+        /**
+         * Determine whether the user has interacted with this canvas
+         */
+        this.interacted = false;
+        /**
+         * Determine whether audio is allowed or muted
+         */
+        this.muted = false;
+        /**
+         * Contains the list of all active audio elements
+         */
+        this.audios = [];
         this.config = Canvas.setDefaults(options, Canvas.defaults);
         this.width = this.config.width;
         this.height = this.config.height;
-        // Create the container <div> element and set properties
-        var container = document.createElement('div');
-        container.tabIndex = 1; // For element focus
-        container.style.outline = 'none';
-        container.style.width = "".concat(this.config.width * this.config.scale, "px");
-        container.style.height = "".concat(this.config.height * this.config.scale, "px");
-        container.style.border = "".concat(this.config.scale, "px solid ").concat(this.config.border);
-        container.style.background = this.config.background;
-        container.style.cursor = this.config.showMouse ? 'default' : 'none';
-        container.style.position = 'relative';
-        this.config.parent.appendChild(container);
+        // Create the main <canvas> element and set properties
+        var main = document.createElement('canvas');
+        main.tabIndex = 1; // For element focus
+        main.style.outline = 'none';
+        main.style.imageRendering = 'pixelated';
+        main.width = this.config.width;
+        main.height = this.config.height;
+        main.style.width = "".concat(this.config.width * this.config.scale, "px");
+        main.style.height = "".concat(this.config.height * this.config.scale, "px");
+        main.style.border = "".concat(this.config.scale, "px solid ").concat(this.config.border);
+        main.style.cursor = this.config.showMouse ? 'default' : 'none';
+        this.config.parent.appendChild(main);
+        // Create main canvas graphics object
+        var graphics = main.getContext('2d');
+        if (graphics) {
+            this.graphic = graphics;
+        }
+        else {
+            throw new Error('Could not initialize canvas graphics.');
+        }
+        graphics.imageSmoothingEnabled = false;
         // Create canvas layers
         for (var i = 0; i < this.config.numLayers; i++) {
             var canvas = document.createElement('canvas');
-            var graphics = canvas.getContext('2d');
-            if (graphics) {
-                this.graphics.push(graphics);
+            var layer = canvas.getContext('2d');
+            if (layer) {
+                this.layers.push(layer);
             }
             else {
                 throw new Error('Could not initialize canvas graphics.');
             }
             // Set properties for canvas
             canvas.style.imageRendering = 'pixelated';
-            canvas.style.boxSizing = 'border-box';
             canvas.width = this.config.width;
             canvas.height = this.config.height;
-            canvas.style.width = '100%';
-            canvas.style.height = '100%';
-            canvas.style.position = 'absolute';
-            graphics.imageSmoothingEnabled = false;
-            container.appendChild(canvas);
+            layer.imageSmoothingEnabled = false;
         }
         // Event listeners
-        container.addEventListener('mousemove', function (e) {
+        main.addEventListener('mousemove', function (e) {
             if (!_this.focused) {
                 return;
             }
@@ -89,7 +106,9 @@ var Canvas = /** @class */ (function () {
             _this.log(e.type, _this.mouseX, _this.mouseY);
             _this.config.mousemove(_this.mouseX, _this.mouseY);
         });
-        container.addEventListener('keydown', function (e) {
+        main.addEventListener('keydown', function (e) {
+            audioContext.resume();
+            _this.interacted = true;
             if (!_this.focused) {
                 return;
             }
@@ -101,7 +120,7 @@ var Canvas = /** @class */ (function () {
                 _this.config.keydown(key);
             }
         });
-        container.addEventListener('keyup', function (e) {
+        main.addEventListener('keyup', function (e) {
             if (!_this.focused) {
                 return;
             }
@@ -113,7 +132,9 @@ var Canvas = /** @class */ (function () {
                 _this.config.keyup(key);
             }
         });
-        container.addEventListener('mousedown', function (e) {
+        main.addEventListener('mousedown', function (e) {
+            audioContext.resume();
+            _this.interacted = true;
             if (!_this.focused) {
                 return;
             }
@@ -124,7 +145,7 @@ var Canvas = /** @class */ (function () {
                 _this.config.mousedown(button);
             }
         });
-        container.addEventListener('mouseup', function (e) {
+        main.addEventListener('mouseup', function (e) {
             if (!_this.focused) {
                 return;
             }
@@ -136,15 +157,15 @@ var Canvas = /** @class */ (function () {
                 _this.config.mouseup(button);
             }
         });
-        container.addEventListener('focusin', function (e) {
+        main.addEventListener('focusin', function (e) {
             _this.focused = true;
-            container.style.borderColor = _this.config.border;
+            main.style.borderColor = _this.config.border;
             _this.log(e.type, _this.focused);
             _this.animation = requestAnimationFrame(function (time) { return _this.startAnimate(time); });
         });
-        container.addEventListener('focusout', function (e) {
+        main.addEventListener('focusout', function (e) {
             _this.focused = false;
-            container.style.borderColor = _this.config.borderBlur;
+            main.style.borderColor = _this.config.borderBlur;
             _this.log(e.type, _this.focused);
             cancelAnimationFrame(_this.animation);
         });
@@ -152,9 +173,46 @@ var Canvas = /** @class */ (function () {
             _this.log(e.type);
             cancelAnimationFrame(_this.animation);
         });
-        container.addEventListener('contextmenu', function (e) { return e.preventDefault(); });
+        main.addEventListener('contextmenu', function (e) { return e.preventDefault(); });
+        // Initialize audio tracks for recording
+        var stream = new MediaStream(main.captureStream()); // video stream
+        var audioContext = new window.AudioContext();
+        for (var track = 0; track < this.config.numTracks; track++) {
+            var audio = new Audio();
+            var source = audioContext.createMediaElementSource(audio);
+            var destination = audioContext.createMediaStreamDestination();
+            source.connect(destination); // contains the audio stream for recording
+            source.connect(audioContext.destination); // so the user can hear
+            this.audios.push(audio);
+            for (var _i = 0, _a = destination.stream.getAudioTracks(); _i < _a.length; _i++) {
+                var audioTrack = _a[_i];
+                this.log("Adding ".concat(audioTrack.id, " to track ").concat(track, "."));
+                stream.addTrack(audioTrack); // add audio track
+            }
+        }
+        // Initialize the media recorder
+        var recordPart = [];
+        this.recorder = new MediaRecorder(stream);
+        this.recorder.addEventListener('dataavailable', function (e) {
+            _this.log(e.type);
+            recordPart.push(e.data);
+        });
+        this.recorder.addEventListener('stop', function (e) {
+            _this.log(e.type);
+            var recording = new Blob(recordPart, { type: 'video/webm;codecs=h264' });
+            var url = URL.createObjectURL(recording);
+            var downloadLink = document.createElement('a');
+            downloadLink.setAttribute('href', url);
+            downloadLink.setAttribute('download', "recording-".concat(Date.now()));
+            downloadLink.click();
+            // Clear out the existing blob parts for recording a new capture
+            recordPart.splice(0);
+            // Remove all keys and mouse buttons down because we lose focus
+            _this.keys.splice(0);
+            _this.mouseButtons.splice(0);
+        });
         // Focus on the canvas
-        container.focus();
+        main.focus();
     }
     /**
      * Start the animation.
@@ -173,8 +231,14 @@ var Canvas = /** @class */ (function () {
         var currentFrame = time;
         var dt = currentFrame - this.lastFrame;
         this.lastFrame = currentFrame;
-        this.log('animate', dt, currentFrame);
         this.config.loop(dt);
+        // Draw all the layers onto the main canvas
+        this.graphic.fillStyle = this.config.background;
+        this.graphic.fillRect(0, 0, this.width, this.height);
+        for (var _i = 0, _a = this.layers; _i < _a.length; _i++) {
+            var layer = _a[_i];
+            this.graphic.drawImage(layer.canvas, 0, 0);
+        }
         this.animation = requestAnimationFrame(function (time) { return _this.animate(time); });
     };
     /**
@@ -206,22 +270,8 @@ var Canvas = /** @class */ (function () {
      */
     Canvas.prototype.screenshot = function (name) {
         if (name === void 0) { name = 'screenshot'; }
-        // Create an offscreen canvas
-        var screen = new Canvas({
-            parent: document.createElement('div'),
-            height: this.config.height,
-            width: this.config.width,
-            scale: this.config.scale,
-        });
-        // Draw the background and each layer
-        screen.graphics[0].fillStyle = this.config.background;
-        screen.graphics[0].fillRect(0, 0, screen.width, screen.height);
-        for (var _i = 0, _a = this.graphics; _i < _a.length; _i++) {
-            var graphic = _a[_i];
-            screen.graphics[0].drawImage(graphic.canvas, 0, 0);
-        }
         // Generate a data URL and set it as the download parameter for <a>
-        var dataURL = screen.graphics[0].canvas.toDataURL();
+        var dataURL = this.graphic.canvas.toDataURL();
         var downloadLink = document.createElement('a');
         downloadLink.setAttribute('href', dataURL);
         downloadLink.setAttribute('download', name);
@@ -230,6 +280,99 @@ var Canvas = /** @class */ (function () {
         this.keys.splice(0);
         this.mouseButtons.splice(0);
     };
+    /**
+     * Start recording all layers on the canvas
+     */
+    Canvas.prototype.startRecording = function () {
+        if (!this.interacted) {
+            throw new Error('The user has not yet interacted with this canvas.');
+        }
+        this.recorder.start();
+    };
+    /**
+     * Stop recording and download screen capture
+     */
+    Canvas.prototype.stopRecording = function () {
+        this.recorder.stop();
+    };
+    /**
+     * Determines whether the media recorder is active
+     * @returns True if currently recording
+     */
+    Canvas.prototype.isRecording = function () {
+        return this.recorder.state === 'recording';
+    };
+    /**
+     * Play an audio file
+     * @param src The path of the audio file
+     * @param loop Whether to play the audio on loop
+     * @param volume The normalized [0-1] volume
+     * @param track The track number to play on
+     */
+    Canvas.prototype.playAudio = function (src, loop, volume, track) {
+        if (loop === void 0) { loop = false; }
+        if (volume === void 0) { volume = 1; }
+        if (track === void 0) { track = 0; }
+        this.log("Playing audio on track ".concat(track, "."));
+        if (!this.interacted) {
+            throw new Error('The user has not yet interacted with this canvas.');
+        }
+        if (track < 0 || track >= this.config.numTracks) {
+            throw new Error("Track ".concat(track, " is out of range. [0,").concat(this.config.numTracks, ")"));
+        }
+        var audio = this.audios[track];
+        audio.src = src;
+        audio.loop = loop;
+        audio.volume = volume;
+        audio.muted = this.muted;
+        audio.play();
+    };
+    /**
+     * Stop all audio tracks from playing
+     */
+    Canvas.prototype.stopAudio = function (track) {
+        if (track === void 0) { track = -1; }
+        this.log("Stopping audio on track ".concat(track, "."));
+        if (track >= this.config.numTracks) {
+            throw new Error("Track ".concat(track, " is out of range. [0,").concat(this.config.numTracks, ")"));
+        }
+        if (track < 0) {
+            for (var _i = 0, _a = this.audios; _i < _a.length; _i++) {
+                var audio = _a[_i];
+                audio.pause();
+            }
+        }
+        else {
+            this.audios[track].pause();
+        }
+    };
+    /**
+     * Mute all audio
+     */
+    Canvas.prototype.mute = function () {
+        this.muted = true;
+        for (var _i = 0, _a = this.audios; _i < _a.length; _i++) {
+            var audio = _a[_i];
+            audio.muted = this.muted;
+        }
+    };
+    /**
+     * Unmute all audio
+     */
+    Canvas.prototype.unmute = function () {
+        this.muted = false;
+        for (var _i = 0, _a = this.audios; _i < _a.length; _i++) {
+            var audio = _a[_i];
+            audio.muted = this.muted;
+        }
+    };
+    /**
+     * Determines whether audio is muted
+     * @returns True if currently muted
+     */
+    Canvas.prototype.isMuted = function () {
+        return this.muted;
+    };
     /**
      * Draw an object onto the canvas.
      * @param drawable Any drawable object
@@ -237,7 +380,10 @@ var Canvas = /** @class */ (function () {
      */
     Canvas.prototype.draw = function (drawable, layer) {
         if (layer === void 0) { layer = 0; }
-        drawable.draw(this.graphics[layer]);
+        if (layer < 0 || layer >= this.config.numLayers) {
+            throw new Error("Layer ".concat(layer, " is out of range. [0,").concat(this.config.numLayers, ")"));
+        }
+        drawable.draw(this.layers[layer]);
     };
     /**
      * Completely clears the canvas.
@@ -245,14 +391,17 @@ var Canvas = /** @class */ (function () {
      */
     Canvas.prototype.clear = function (layer) {
         if (layer === void 0) { layer = -1; }
+        if (layer >= this.config.numLayers) {
+            throw new Error("Layer ".concat(layer, " is out of range. [0,").concat(this.config.numLayers, ")"));
+        }
         if (layer < 0) {
-            for (var _i = 0, _a = this.graphics; _i < _a.length; _i++) {
-                var graphic = _a[_i];
-                graphic.clearRect(0, 0, this.config.width, this.config.height);
+            for (var _i = 0, _a = this.layers; _i < _a.length; _i++) {
+                var layer_1 = _a[_i];
+                layer_1.clearRect(0, 0, this.config.width, this.config.height);
             }
         }
         else {
-            this.graphics[layer].clearRect(0, 0, this.config.width, this.config.height);
+            this.layers[layer].clearRect(0, 0, this.config.width, this.config.height);
         }
     };
     /**
@@ -288,11 +437,12 @@ var Canvas = /** @class */ (function () {
         width: 600,
         height: 400,
         scale: 1,
-        background: 'transparent',
+        background: 'white',
         border: 'transparent',
         borderBlur: 'transparent',
         showMouse: true,
         numLayers: 1,
+        numTracks: 1,
         keydown: function () { return; },
         keyup: function () { return; },
         mousemove: function () { return; },

package/dist/index.js

@@ -22,3 +22,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * ![NPM Last Update](https://img.shields.io/npm/last-update/graphico)
  */
 __exportStar(require("./canvas"), exports);
+__exportStar(require("./types"), exports);

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphico",
-  "version": "0.0.5",
+  "version": "1.1.0",
   "description": "Canvas 2D rendering toolkit for games and visual projects",
   "homepage": "https://npm.nicfv.com/",
   "bin": "",
@@ -23,7 +23,12 @@
     "drawing",
     "art",
     "render",
-    "2D"
+    "2D",
+    "layer",
+    "audio",
+    "track",
+    "animate",
+    "visual"
   ],
   "author": {
     "name": "Nicolas Ventura",

package/types/canvas.d.ts

@@ -1,3 +1,4 @@
+import { Drawable, Options } from '.';
 /**
  * Represents a canvas for drawing and animating
  */
@@ -11,9 +12,13 @@ export declare class Canvas {
      */
     private readonly config;
     /**
-     * Can be used to render 2D graphics onto the canvas
+     * Used to render 2D objects onto the main canvas
      */
-    private readonly graphics;
+    private readonly graphic;
+    /**
+     * Can be used to render 2D graphics onto layers of the canvas
+     */
+    private readonly layers;
     /**
      * Contains a list of current keys pressed
      */
@@ -50,6 +55,22 @@ export declare class Canvas {
      * Determine whether the client is focused or not
      */
     private focused;
+    /**
+     * Determine whether the user has interacted with this canvas
+     */
+    private interacted;
+    /**
+     * The media recording object for screen captures
+     */
+    private readonly recorder;
+    /**
+     * Determine whether audio is allowed or muted
+     */
+    private muted;
+    /**
+     * Contains the list of all active audio elements
+     */
+    private readonly audios;
     /**
      * Create a new canvas with the provided options
      * @param options Configuration options
@@ -86,109 +107,60 @@ export declare class Canvas {
      */
     screenshot(name?: string): void;
     /**
-     * Draw an object onto the canvas.
-     * @param drawable Any drawable object
-     * @param layer The zero-indexed layer to draw to
-     */
-    draw(drawable: Drawable, layer?: number): void;
-    /**
-     * Completely clears the canvas.
-     * @param layer The zero-indexed layer to clear, if unset, will clear all layers
-     */
-    clear(layer?: number): void;
-    /**
-     * Log a message to the debug console.
-     */
-    private log;
-    /**
-     * Set defaults for all undefined options.
-     */
-    private static setDefaults;
-}
-/**
- * Configuration Options for Canvas
- */
-export interface Options {
-    /**
-     * Optionally print debug messages to the console
-     */
-    readonly debug: boolean;
-    /**
-     * Appends the canvas onto the parent element
-     */
-    readonly parent: Node;
-    /**
-     * The width of the drawing area, in pixels
-     */
-    readonly width: number;
-    /**
-     * The height of the drawing area, in pixels
-     */
-    readonly height: number;
-    /**
-     * The scale of the drawing area to the actual size of the canvas element
-     */
-    readonly scale: number;
-    /**
-     * The background color of the canvas
+     * Start recording all layers on the canvas
      */
-    readonly background: string;
+    startRecording(): void;
     /**
-     * The border color for the canvas (when focused)
+     * Stop recording and download screen capture
      */
-    readonly border: string;
+    stopRecording(): void;
     /**
-     * The border color for the canvas (when not focused)
+     * Determines whether the media recorder is active
+     * @returns True if currently recording
      */
-    readonly borderBlur: string;
+    isRecording(): boolean;
     /**
-     * Optionally show or hide the mouse when hovering over the canvas
+     * Play an audio file
+     * @param src The path of the audio file
+     * @param loop Whether to play the audio on loop
+     * @param volume The normalized [0-1] volume
+     * @param track The track number to play on
      */
-    readonly showMouse: boolean;
+    playAudio(src: string, loop?: boolean, volume?: number, track?: number): void;
     /**
-     * The number of layers in this canvas
+     * Stop all audio tracks from playing
      */
-    readonly numLayers: number;
+    stopAudio(track?: number): void;
     /**
-     * Event listener for when a key is pressed
-     * @param key The key that was pressed
+     * Mute all audio
      */
-    readonly keydown: (key: string) => void;
+    mute(): void;
     /**
-     * Event listener for when a key is released
-     * @param key The key that was released
+     * Unmute all audio
      */
-    readonly keyup: (key: string) => void;
+    unmute(): void;
     /**
-     * Event listener for when the mouse is moved
-     * @param x Cursor X-coordinate
-     * @param y Cursor Y-coordinate
+     * Determines whether audio is muted
+     * @returns True if currently muted
      */
-    readonly mousemove: (x: number, y: number) => void;
+    isMuted(): boolean;
     /**
-     * Event listener for when a button on the mouse is pressed
-     * @param button The button that was pressed
+     * Draw an object onto the canvas.
+     * @param drawable Any drawable object
+     * @param layer The zero-indexed layer to draw to
      */
-    readonly mousedown: (button: number) => void;
+    draw(drawable: Drawable, layer?: number): void;
     /**
-     * Event listener for when a button on the mouse is released
-     * @param button The button that was released
+     * Completely clears the canvas.
+     * @param layer The zero-indexed layer to clear, if unset, will clear all layers
      */
-    readonly mouseup: (button: number) => void;
+    clear(layer?: number): void;
     /**
-     * Event listener for a the main animation loop
-     * @param dt The number of milliseconds in between frames
-     * @returns An array of `Drawable` to render on layer 0, or void
+     * Log a message to the debug console.
      */
-    readonly loop: (dt: number) => void;
-}
-/**
- * Represents an object that can be drawn on the canvas.
- */
-export interface Drawable {
+    private log;
     /**
-     * Draw this object onto the canvas.
-     * @param graphics Canvas 2D rendering interface
+     * Set defaults for all undefined options.
      */
-    draw(graphics: CanvasRenderingContext2D): void;
+    private static setDefaults;
 }

package/types/index.d.ts

@@ -6,3 +6,4 @@
  * ![NPM Last Update](https://img.shields.io/npm/last-update/graphico)
  */
 export * from './canvas';
+export * from './types';

package/types/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Configuration Options for Canvas
+ */
+export interface Options {
+    /**
+     * Optionally print debug messages to the console
+     */
+    readonly debug: boolean;
+    /**
+     * Appends the canvas onto the parent element
+     */
+    readonly parent: Node;
+    /**
+     * The width of the drawing area, in pixels
+     */
+    readonly width: number;
+    /**
+     * The height of the drawing area, in pixels
+     */
+    readonly height: number;
+    /**
+     * The scale of the drawing area to the actual size of the canvas element
+     */
+    readonly scale: number;
+    /**
+     * The background color of the canvas
+     */
+    readonly background: string;
+    /**
+     * The border color for the canvas (when focused)
+     */
+    readonly border: string;
+    /**
+     * The border color for the canvas (when not focused)
+     */
+    readonly borderBlur: string;
+    /**
+     * Optionally show or hide the mouse when hovering over the canvas
+     */
+    readonly showMouse: boolean;
+    /**
+     * The number of layers in this canvas
+     */
+    readonly numLayers: number;
+    /**
+     * The number of audio tracks
+     */
+    readonly numTracks: number;
+    /**
+     * Event listener for when a key is pressed
+     * @param key The key that was pressed
+     */
+    readonly keydown: (key: string) => void;
+    /**
+     * Event listener for when a key is released
+     * @param key The key that was released
+     */
+    readonly keyup: (key: string) => void;
+    /**
+     * Event listener for when the mouse is moved
+     * @param x Cursor X-coordinate
+     * @param y Cursor Y-coordinate
+     */
+    readonly mousemove: (x: number, y: number) => void;
+    /**
+     * Event listener for when a button on the mouse is pressed
+     * @param button The button that was pressed
+     */
+    readonly mousedown: (button: number) => void;
+    /**
+     * Event listener for when a button on the mouse is released
+     * @param button The button that was released
+     */
+    readonly mouseup: (button: number) => void;
+    /**
+     * Event listener for a the main animation loop
+     * @param dt The number of milliseconds in between frames
+     * @returns An array of `Drawable` to render on layer 0, or void
+     */
+    readonly loop: (dt: number) => void;
+}
+/**
+ * Represents an object that can be drawn on the canvas.
+ */
+export interface Drawable {
+    /**
+     * Draw this object onto the canvas.
+     * @param graphics Canvas 2D rendering interface
+     */
+    draw(graphics: CanvasRenderingContext2D): void;
+}