GlobalAPI.js

  1. /*
  2.  * Copyright 2020 WICKLETS LLC
  3.  *
  4.  * This file is part of Wick Engine.
  5.  *
  6.  * Wick Engine is free software: you can redistribute it and/or modify
  7.  * it under the terms of the GNU General Public License as published by
  8.  * the Free Software Foundation, either version 3 of the License, or
  9.  * (at your option) any later version.
  10.  *
  11.  * Wick Engine is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with Wick Engine.  If not, see <https://www.gnu.org/licenses/>.
  18.  */
  20. GlobalAPI = class {
  21.     /**
  22.      * Defines all api members such as functions and properties.
  23.      * @type {string[]}
  24.      */
  25.     static get apiMemberNames () {
  26.         return [
  27.             'stop','play','gotoAndStop','gotoAndPlay','gotoNextFrame','gotoPrevFrame',
  28.             // These are currently disabled, they are very slow for some reason.
  29.             // They are currently hacked in inside Tickable._runFunction
  30.             //'project','root','parent','parentObject',
  31.             'isMouseDown','mouseX','mouseY','mouseMoveX','mouseMoveY',
  32.             'key','keys','isKeyDown','keyIsDown','isKeyJustPressed','keyIsJustPressed',
  33.             'random',
  34.             'playSound','stopAllSounds',
  35.             'onEvent',
  36.             'hideCursor','showCursor',
  37.             'hitTestOptions',
  38.         ];
  39.     }
  41.     /**
  42.      * @param {object} scriptOwner The tickable object which owns the script being evaluated.
  43.      */
  44.     constructor (scriptOwner) {
  45.         this.scriptOwner = scriptOwner;
  46.     }
  48.     /**
  49.      * Returns a list of api members bound to the script owner.
  50.      * @returns {object[]} Array of functions, properties, and api members.
  51.      */
  52.     get apiMembers () {
  53.         var members = [];
  55.         GlobalAPI.apiMemberNames.forEach(name => {
  56.             var fn = this[name];
  57.             if(fn instanceof Function) {
  58.                 fn = fn.bind(this);
  59.             }
  60.             members.push({
  61.                 name: name,
  62.                 fn: fn,
  63.             })
  64.         });
  66.         return members;
  67.     }
  69.     /**
  70.      * Stops the timeline of the object's parent clip.
  71.      */
  72.     stop () {
  73.         this.scriptOwner.parentClip.stop();
  74.     }
  76.     /**
  77.      * Plays the timeline of the object's parent clip.
  78.      */
  79.     play () {
  80.         this.scriptOwner.parentClip.play();
  81.     }
  83.     /**
  84.      * Moves the plahead of the parent clip to a frame and stops the timeline of that parent clip.
  85.      * @param {string | number} frame Frame name or number to move playhead to.
  86.      */
  87.     gotoAndStop (frame) {
  88.         this.scriptOwner.parentClip.gotoAndStop(frame);
  89.     }
  91.     /**
  92.      * Moves the plahead of the parent clip to a frame and plays the timeline of that parent clip.
  93.      * @param {string | number} frame Frame name or number to move playhead to.
  94.      */
  95.     gotoAndPlay (frame) {
  96.         this.scriptOwner.parentClip.gotoAndPlay(frame);
  97.     }
  99.     /**
  100.      * Moves the playhead of the parent clip of the object to the next frame.
  101.      */
  102.     gotoNextFrame () {
  103.         this.scriptOwner.parentClip.gotoNextFrame();
  104.     }
  106.     /**
  107.      * Moves the playhead of the parent clip of this object to the previous frame.
  108.      */
  109.     gotoPrevFrame () {
  110.         this.scriptOwner.parentClip.gotoPrevFrame();
  111.     }
  113.     hitTestOptions (options) {
  114.         this.scriptOwner.project.hitTestOptions = options;
  115.     }
  117.     /**
  118.      * Returns an object representing the project with properties such as width, height, framerate, background color, and name.
  119.      * @returns {object} Project object.
  120.      */
  121.     get project () {
  122.         var project = this.scriptOwner.project && this.scriptOwner.project.root;
  123.         if(project) {
  124.             // Attach some aliases to the project settings
  125.             project.width = this.scriptOwner.project.width;
  126.             project.height = this.scriptOwner.project.height;
  127.             project.framerate = this.scriptOwner.project.framerate;
  128.             project.backgroundColor = this.scriptOwner.project.backgroundColor;
  129.             project.name = this.scriptOwner.project.name;
  130.             project.hitTestOptions = this.scriptOwner.project.hitTestOptions;
  131.         }
  132.         return project;
  133.     }
  135.     /**
  136.      * @deprecated
  137.      * Legacy item which returns the project. Use 'project' instead.
  138.      */
  139.     get root () {
  140.         return this.project;
  141.     }
  143.     /**
  144.      * Returns a reference to the current object's parent.
  145.      * @returns Current object's parent.
  146.      */
  147.     get parent () {
  148.         return this.scriptOwner.parentClip;
  149.     }
  151.     /**
  152.      * @deprecated
  153.      * Legacy item which returns the parent clip. Use 'parent' instead.
  154.      */
  155.     get parentObject () {
  156.         return this.scriptOwner.parentClip;
  157.     }
  159.     /**
  160.      * Returns the last key pressed down.
  161.      * @returns {string | null} Returns null if no key has been pressed yet.
  162.      */
  163.     get key () {
  164.         if(!this.scriptOwner.project) return null;
  165.         return this.scriptOwner.project.currentKey;
  166.     }
  168.     /**
  169.      * Returns a list of all keys currently pressed down.
  170.      * @returns {string[]} All keys represented as strings. If no keys are pressed, an empty array is returned.
  171.      */
  172.     get keys () {
  173.         if(!this.scriptOwner.project) return null;
  174.         return this.scriptOwner.project.keysDown;
  175.     }
  177.     /**
  178.      * Returns true if the given key is currently down.
  179.      * @param {string} key
  180.      * @returns {bool}
  181.      */
  182.     isKeyDown (key) {
  183.         if(!this.scriptOwner.project) return null;
  184.         return this.scriptOwner.project.isKeyDown(key);
  185.     }
  187.     /**
  188.      * @deprecated
  189.      * Legacy item, use 'isKeyDown' instead.
  190.      */
  191.     keyIsDown (key) {
  192.         return this.isKeyDown(key.toLowerCase());
  193.     }
  195.     /**
  196.      * Returns true if the given key was just pressed within the last tick.
  197.      * @param {string} key
  198.      * @returns {bool}
  199.      */
  200.     isKeyJustPressed (key) {
  201.         if(!this.scriptOwner.project) return null;
  202.         return this.scriptOwner.project.isKeyJustPressed(key);
  203.     }
  205.     /**
  206.      * @deprecated
  207.      * Legacy item, use 'isKeyJustPressed' instead.
  208.      */
  209.     keyIsJustPressed (key) {
  210.         return this.keyIsJustPressed(key.toLowerCase());
  211.     }
  213.     /**
  214.      * Returns true if the mouse is currently held down.
  215.      * @returns {bool | null} Returns null if the object does not have a project.
  216.      */
  217.     isMouseDown () {
  218.         if(!this.scriptOwner.project) return null;
  219.         return this.scriptOwner.project.isMouseDown;
  220.     }
  222.     /**
  223.      * Returns the current x position of the mouse in relation to the canvas.
  224.      * @returns {number}
  225.      */
  226.     get mouseX () {
  227.         if(!this.scriptOwner.project) return null;
  228.         return this.scriptOwner.project.mousePosition.x;
  229.     }
  231.     /**
  232.      * Returns the current y position of the mouse in relation to the canvas.
  233.      * @returns {number}
  234.      */
  235.     get mouseY () {
  236.         if(!this.scriptOwner.project) return null;
  237.         return this.scriptOwner.project.mousePosition.y;
  238.     }
  240.     /**
  241.      * Returns the amount the mouse moved in the last tick on the x axis.
  242.      * @returns {number}
  243.      */
  244.     get mouseMoveX () {
  245.         if(!this.scriptOwner.project) return null;
  246.         return this.scriptOwner.project.mouseMove.x;
  247.     }
  249.     /**
  250.      * Returns the amount the mouse moved in the last tick on the y axis.
  251.      * @returns {number}
  252.      */
  253.     get mouseMoveY () {
  254.         if(!this.scriptOwner.project) return null;
  255.         return this.scriptOwner.project.mouseMove.y;
  256.     }
  258.     /**
  259.      * Returns a new random object.
  260.      * @returns {GlobalAPI.Random}
  261.      */
  262.     get random () {
  263.         return new GlobalAPI.Random();
  264.     }
  266.     /**
  267.      * Plays a sound which is currently in the asset library.
  268.      * @param {string} name - name of the sound asset in the library.
  269.      * @param {Object} options - options for the sound. See Wick.SoundAsset.play
  270.      * @returns {object} object representing the sound which was played.
  271.      */
  272.     playSound (assetName, options) {
  273.         if(!this.scriptOwner.project) return null;
  274.         return this.scriptOwner.project.playSound(assetName, options);
  275.     }
  277.     /**
  278.      * Stops sound(s) currently playing.
  279.      * @param {string} assetName - The name of the SoundAsset to stop.
  280.      * @param {number} id - (optional) The ID of the sound to stop. Returned by playSound. If an ID is not given, all instances of the given sound asset will be stopped.
  281.      */
  282.     stopSound (assetName, id) {
  283.         if(!this.scriptOwner.project) return null;
  284.         return this.scriptOwner.project.stopSound(assetName, id);
  285.     }
  286.     
  287.     /**
  288.      * Stops all currently playing sounds.
  289.      */
  290.     stopAllSounds () {
  291.         if(!this.scriptOwner.project) return null;
  292.         this.scriptOwner.project.stopAllSounds();
  293.     }
  295.     /**
  296.      * Attach a function to an event with a given name.
  297.      * @param {string} name - the name of the event to attach the function to
  298.      * @param {function} fn - the function to attach to the event
  299.      */
  300.     onEvent (name, fn) {
  301.         this.scriptOwner.onEvent(name, fn);
  302.     }
  304.     /**
  305.      * Hide the cursor while the project is running.
  306.      */
  307.     hideCursor () {
  308.         if(!this.scriptOwner.project) return null;
  309.         this.scriptOwner.project.hideCursor = true;
  310.     }
  312.     /**
  313.      * Don't hide the cursor while the project is running.
  314.      */
  315.     showCursor () {
  316.         if(!this.scriptOwner.project) return null;
  317.         this.scriptOwner.project.hideCursor = false;
  318.     }
  319. }
  321. GlobalAPI.Random = class {
  322.     constructor () {
  324.     }
  326.     /**
  327.      * Returns a random integer (whole number) between two given numbers, 0 and a given number, or 0 and 1. The random number is inclusive of the maximum range.
  328.      * @param {number} min The minimum of the returned integer, or the maximum of the returned number if it is the only argument.
  329.      * @param {number} max The maximum of the returned integer.
  330.      * @returns {number} A random number between num1 and num2, 0 and num1, or 0 and 1. Will return 0 if max is greater than min.
  331.      * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random
  332.      */
  333.     integer(min,max) {
  335.         if (typeof min === 'undefined' && typeof max === 'undefined') {
  336.             min = 0;
  337.             max = 1;
  338.         } else if (typeof min === 'number' && typeof max === 'undefined') {
  339.             max = Math.ceil(min);
  340.             min = 0;
  341.         } 
  343.         if (max < min) return 0;
  345.         // The maximum is inclusive and the minimum is inclusive
  346.         return Math.floor(Math.random() * (max - min + 1) + min); 
  347.     }
  349.     /**
  350.      * Returns a random floating point (decimal) number between two given numbers, 0 and a given number, or 0 and 1.
  351.      * @param {number} num1 The minimum of the returned number, or the maximum of the returned number if it is the only argument.
  352.      * @param {number} num2 The maximum of the returned number.
  353.      * @returns {number} A random number between num1 and num2, 0 and num1, or 0 and 1.
  354.      * https://stackoverflow.com/questions/4959975/generate-random-number-between-two-numbers-in-javascript
  355.      */
  356.     float(num1, num2) {
  357. 		if ((typeof num1 !== "undefined") && (typeof num2 !== "undefined")) {
  358. 			return (Math.random()*(num2-num1)+num1);
  359. 		} else if ((typeof num1 !== "undefined") && (typeof num2 == "undefined")) {
  360. 			return Math.random()*num1;
  361. 		} else {
  362. 			return Math.random();
  363. 		}
  364.     }
  366.     /**
  367.      * Returns a random item from an array of items.
  368.      * @param {array} An array of objects.
  369.      * @returns {object | null} A random item contained in the array. Returns null if the given array has no items.
  370.      * https://stackoverflow.com/questions/4550505/getting-a-random-value-from-a-javascript-array
  371.      */
  372.     choice(array) {
  373.         if (array.length <= 0) return null;
  374.         return array[Math.floor(Math.random() * array.length)]
  375.     }
  376. }