adds jsdoc comments to client package

core/client/src/client.ts

@@ -134,6 +134,9 @@ export default class MagicCircle {
     });
   }
 
+  /**
+   * Tries to make connection between frame and editor
+   */
   async connect() {
     if (!this.ipc) {
       throw new Error('IPC not defined');
@@ -176,6 +179,11 @@ export default class MagicCircle {
     this.ipc.send('ready', true);
   }
 
+  /**
+   * Provide initial setup script
+   *
+   * @param handle Function that will run on setup, return a html element (canvas/svg) for enabling screenshots.
+   */
   setup(fn?: setupFn) {
     if (this.setupDone) {
       throw new Error('Can not change setup function after it has already run');
@@ -196,6 +204,11 @@ export default class MagicCircle {
     return this;
   }
 
+  /**
+   * Provide script that will run on every tick
+   *
+   * @param handle Function that will run on every tick. Provides a time delta since previous tick.
+   */
   loop(fn: loopFn) {
     this.hooks.loop = fn;
 
@@ -207,11 +220,20 @@ export default class MagicCircle {
   resize(): resizeFn;
   resize(fn: resizeFn): MagicCircle;
 
+  /**
+   * Provide script that will run on a resize of the element.
+   *
+   * @param handle Function that will run on resize
+   */
   resize(fn?: resizeFn): unknown {
     if (fn) this.hooks.resize = fn;
     return fn ? this : this.hooks.resize;
   }
 
+  /**
+   * Trigger a (manual) sync between frame and client.
+   * Debounced to prevent sending too many messages.
+   */
   sync() {
     if (!this.setupDone) return;
 
@@ -225,6 +247,9 @@ export default class MagicCircle {
     }, 12);
   }
 
+  /**
+   * Trigger an immediate sync between frame and client
+   */
   flush() {
     (this.plugins || []).forEach((p) => {
       if (p.sync) {
@@ -233,6 +258,9 @@ export default class MagicCircle {
     });
   }
 
+  /**
+   * Start running the loop function (whenever the setup is ready)
+   */
   start() {
     if (!this.setupCalled) {
       throw new Error(
@@ -269,6 +297,9 @@ export default class MagicCircle {
     return this;
   }
 
+  /**
+   * Stop running the loop function
+   */
   stop() {
     if (this.ipc) this.ipc.send('play', false);
     this.isPlaying = false;
@@ -288,6 +319,12 @@ export default class MagicCircle {
     return this;
   }
 
+  /**
+   * Triggers one tick of the loop.
+   * Will not trigger a new step after completion.
+   *
+   * @param customDelta Manually set the time delta
+   */
   step(customDelta?: number) {
     // calculate delta
     const newTime = (
@@ -314,6 +351,9 @@ export default class MagicCircle {
     });
   }
 
+  /**
+   * Trigger a tick
+   */
   tick() {
     this.step();
 
@@ -323,7 +363,12 @@ export default class MagicCircle {
     }
   }
 
-  destroy() {
+  /**
+   * Destroys this instance and all memory associated with it
+   *
+   * @param removeChildren Removes and destroys all children when true
+   */
+  destroy(removeChildren = false) {
     this.stop();
     this.hooks = {};
 
@@ -341,10 +386,20 @@ export default class MagicCircle {
       }
     });
 
+    if (removeChildren) {
+      this.layer.destroy(true);
+    }
+
     this.plugins = [];
     this.arguments = {};
+    this.layer.children = [];
   }
 
+  /**
+   * Find a plugin
+   *
+   * @param name Name of plugin
+   */
   plugin<T extends PluginBase>(name: string): T {
     if (!this.plugins) {
       throw new Error('Plugins not created yet, first run the setup() call');
@@ -353,6 +408,11 @@ export default class MagicCircle {
     return this.plugins.find((p) => p.name === name) as T;
   }
 
+  /**
+   * Adds one or more layers
+   *
+   * @param layer Single or multiple layers to add
+   */
   add(layer: Child | Child[]) {
     this.layer.add(layer);
   }

core/client/src/control.ts

@@ -20,6 +20,12 @@ export default class Control<T, U extends options = options> {
 
   private updateHooks: Set<UpdateHook<T>>;
 
+  /**
+   * Creates control instance
+   *
+   * @param reference Object to reference
+   * @param key Key in object to read for value
+   */
   constructor(reference: Reference, key: string) {
     if (!reference) {
       throw new Error('Reference object does not exist');
@@ -60,15 +66,26 @@ export default class Control<T, U extends options = options> {
     this.updateHooks.forEach((fn) => fn(value));
   }
 
+  /**
+   * Sets label in UI
+   *
+   * @param label
+   */
   label(label: string) {
     this.options.label = label;
     return this;
   }
 
+  /**
+   * Resets to the initial value
+   */
   reset() {
     this.value = this.initialValue;
   }
 
+  /**
+   * Sets current value as default
+   */
   setDefault() {
     let newValue:
       | T
@@ -97,25 +114,54 @@ export default class Control<T, U extends options = options> {
     this.initialValue = newValue;
   }
 
+  /**
+   * Get path in tree
+   *
+   * @param basePath Base path to prepend
+   * @param paths Reference to all paths to prevent duplicates
+   */
   getPath(basePath: string, paths: Paths) {
     return paths.get(basePath, this.key);
   }
 
+  /**
+   * Watch value changes,
+   * needed if external changes happen to this variable.
+   *
+   * @param watch Enable/disable watching
+   */
   watch(watch = true) {
     this.watchChanges = watch;
     return this;
   }
 
+  /**
+   * (if possible) interpolates values
+   *
+   * @param from
+   * @param to
+   * @param alpha Value between 0-1
+   */
   // eslint-disable-next-line
   interpolate(from: T, to: T, alpha: number) {
     return from;
   }
 
+  /**
+   * Function to run on update of values, triggered by the editor.
+   *
+   * @param hook Function to run
+   */
   onUpdate(fn: UpdateHook<T>) {
     this.updateHooks.add(fn);
     return this;
   }
 
+  /**
+   * Add this control to a layer or folder
+   *
+   * @param layer Layer/folder to add to
+   */
   addTo(layer: Layer) {
     if (this.parent) {
       this.removeFromParent();
@@ -127,12 +173,21 @@ export default class Control<T, U extends options = options> {
     return this;
   }
 
+  /**
+   * Trigger a sync of the root Magic Circle instance (if possible)
+   */
   sync() {
     if (this.parent) {
       this.parent.getMagicInstance()?.sync();
     }
   }
 
+  /**
+   * Exports settings to JSON
+   *
+   * @param basePath Base path to prepend
+   * @param paths Reference to all paths to prevent duplicates
+   */
   toJSON(basePath: string, paths: Paths) {
     const path = this.getPath(basePath, paths);
     return {
@@ -147,13 +202,19 @@ export default class Control<T, U extends options = options> {
     };
   }
 
+  /**
+   * Removes this control from parent
+   */
   removeFromParent() {
     if (this.parent) {
       this.parent.remove(this);
       this.parent = undefined;
     }
   }
 
+  /**
+   * Destroys this instance and all memory associated with it
+   */
   destroy() {
     if (this.parent) {
       this.removeFromParent();

core/client/src/controls/color.ts

@@ -26,12 +26,21 @@ export default class ColorControl extends Control<
 > {
   type = 'color';
 
+  /**
+   * Loop through all children recursively.
+   *
+   * @param range Sets the range for the color channels. Default is 255.
+   * @param alpha Sets the range for the alpha channel, if used. Default is 1.
+   */
   range(range = 255, alpha = 1) {
     this.options.range = range;
     this.options.rangeAlpha = alpha;
     return this;
   }
 
+  /**
+   * Determines if the alpha channel is used for this control
+   */
   alpha(alpha = true) {
     this.options.alpha = alpha;
     return this;

core/client/src/controls/number.ts

@@ -9,11 +9,17 @@ type options = {
 export default class NumberControl extends Control<number, options> {
   type = 'number';
 
+  /**
+   * Sets range for control. User can set the value between these two values.
+   */
   range(start: number, end: number) {
     this.options.range = [start, end];
     return this;
   }
 
+  /**
+   * Sets step size for control
+   */
   stepSize(size: number) {
     this.options.stepSize = size;
     return this;

core/client/src/controls/rotation.ts

@@ -10,16 +10,28 @@ type options = {
 export default class RotationControl extends Control<number, options> {
   type = 'rotation';
 
+  /**
+   * Sets rotation mode for control. Either radians or degrees.
+   */
   mode(mode: options['mode']) {
     this.options.mode = mode;
     return this;
   }
 
+  /**
+   * Sets range of values,
+   * user can only set values between start and end value.
+   *
+   * @param hook Function that has child and path as arguments
+   */
   range(start: number, end: number) {
     this.options.range = [start, end];
     return this;
   }
 
+  /**
+   * Sets step size for control
+   */
   stepSize(stepSize: number) {
     this.options.stepSize = stepSize;
     return this;

core/client/src/controls/text.ts

@@ -10,6 +10,12 @@ type options = {
 export default class TextControl extends Control<string, options> {
   type = 'text';
 
+  /**
+   * Limits values of text to a list displayed in a selection box
+   *
+   * @param keys List of values
+   * @param keys List of labels for values (optional)
+   */
   selection(keys: string[], labels?: string[]) {
     this.options.selection = {
       keys,

core/client/src/controls/vector.ts

@@ -32,16 +32,25 @@ export default class VectorControl extends Control<vector, options> {
     }
   }
 
+  /**
+   * Sets range for control. User can set the value between these two values.
+   */
   range(start: number, end: number) {
     this.options.range = [start, end];
     return this;
   }
 
+  /**
+   * Sets the precision in digits
+   */
   precision(digits: number) {
     this.options.precision = digits;
     return this;
   }
 
+  /**
+   * Sets the default secondary axis, either the y or z-axis
+   */
   defaultSecondaryAxis(axis: 'y' | 'z') {
     this.options.defaultSecondaryAxis = axis;
     return this;