add missing args param to executeLuaFunction

declaration/openspace-api-js.d.ts

@@ -22,7 +22,7 @@
  * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                         *
  ****************************************************************************************/
 
-declare module 'openspace-api-js' {
+declare module "openspace-api-js" {
   export class OpenSpaceApi {
     /**
      * Construct an instance of the OpenSpace API.
@@ -118,21 +118,23 @@ declare module 'openspace-api-js' {
     executeLuaScript(
       script: string,
       getReturnValue: boolean,
-      shouldBeSynchronized: boolean
+      shouldBeSynchronized: boolean,
     ): Promise<unknown | undefined>;
 
     /**
      * Execute a lua function from the OpenSpace library
      * @param function The lua function to execute (for example
      *                 `openspace.addSceneGraphNode`).
+     * @param args The function arguments.
      * @param getReturnValue Specified whether the return value should be collected.
      *
      * @return The return value of the script, if `getReturnValue` is true, otherwise
      *         undefined.
      */
     executeLuaFunction(
       fun: string,
-      getReturnValue: boolean
+      args: unknown[],
+      getReturnValue: boolean,
     ): Promise<unknown | undefined>;
 
     /**
@@ -189,7 +191,7 @@ declare module 'openspace-api-js' {
     constructor(
       iterator: AsyncGenerator<any, void, unknown>,
       talk: (payload: any) => void,
-      cancel: () => void
+      cancel: () => void,
     );
     /**
      * Send data within a topic
@@ -330,7 +332,7 @@ export interface openspace {
   /**
    * Downloads a file from Lua interpreter
    */
-  downloadFile: (url: string, savePath: string, waitForCompletion?: boolean) => Promise<void>
+  downloadFile: (url: string, savePath: string, waitForCompletion?: boolean, overrideExistingFile?: boolean) => Promise<void>
   /**
    * Extracts the DPI scaling for either the GUI window or if there is no dedicated GUI window, the first window.
    */
@@ -553,7 +555,7 @@ export interface openspace {
 
 \\param filePath The location where the data will be saved. Any file that already exists in that location will be overwritten \\param base64Data The base64 encoded data that should be saved to the provided file
    */
-  saveBase64File: (filepath: path, base64Data: string) => Promise<void>
+  saveBase64File: (filePath: path, base64Data: string) => Promise<void>
   /**
    * Collects all changes that have been made since startup, including all property changes and assets required, requested, or removed. All changes will be added to the profile that OpenSpace was started with, and the new saved file will contain all of this information. If the argument is provided, the settings will be saved into new profile with that name. If the argument is blank, the current profile will be saved to a backup file and the original profile will be overwritten. The second argument determines if a file that already exists should be overwritten, which is 'false' by default.
    */
@@ -848,13 +850,13 @@ interface audioLibrary {
   /**
    * Starts playing the audio file located and the provided \\p path. The \\p loop parameter determines whether the file is only played once, or on a loop. The sound is later referred to by the \\p identifier name. The audio file will be played in \"background\" mode, which means that each channel will be played at full volume. To play a video using spatial audio, use the #playAudio3d function instead.
 
-\\param path The audio file that should be played \\param identifier The name for the sound that is used to refer to the sound \\param loop If `Yes` then the song will be played in a loop until the program is closed or the playing is stopped through the #stopAudio function
+\\param path The audio file that should be played \\param identifier The name for the sound that is used to refer to the sound \\param shouldLoop If `Yes` then the song will be played in a loop until the program is closed or the playing is stopped through the #stopAudio function
    */
   playAudio: (path: path, identifier: string, shouldLoop?: boolean) => Promise<void>
   /**
    * Starts playing the audio file located and the provided \\p path. The \\p loop parameter determines whether the file is only played once, or on a loop. The sound is later referred to by the \\p identifier name. The \\p position parameter determines the spatial location of the sound in a meter-based coordinate system. The position of the listener is (0,0,0) with the forward direction along the +y axis. This means that the \"left\" channel in a stereo setting is towards -x and the \"right\" channel towards x. This default value can be customized through the #set3dListenerParameters function. If you want to play a video without spatial audio, use the #playAudio function instead.
 
-\\param path The audio file that should be played \\param identifier The name for the sound that is used to refer to the sound \\param position The position of the audio file in the 3D environment \\param loop If `Yes` then the song will be played in a loop until the program is closed or the playing is stopped through the #stopAudio function
+\\param path The audio file that should be played \\param identifier The name for the sound that is used to refer to the sound \\param position The position of the audio file in the 3D environment \\param shouldLoop If `Yes` then the song will be played in a loop until the program is closed or the playing is stopped through the #stopAudio function
    */
   playAudio3d: (path: path, identifier: string, position: vec3, shouldLoop?: boolean) => Promise<void>
   /**
@@ -876,7 +878,7 @@ interface audioLibrary {
   /**
    * Updates the 3D position of a track started through the #playAudio3d function. See that function and the #set3dListenerParameters function for a complete description. The \\p identifier must be a name for a sound that was started through the #playAudio3d function.
 
-\\param handle A valid handle for a track started through the #playAudio3d function \\param position The new position from which the track originates
+\\param identifier A valid identifier for a track started through the #playAudio3d function \\param position The new position from which the track originates
    */
   set3dSourcePosition: (identifier: string, position: vec3) => Promise<void>
   /**
@@ -888,25 +890,27 @@ interface audioLibrary {
   /**
    * Controls whether the track referred to by the \\p identifier should be looping or just be played once. If a track is converted to not looping, it will finish playing until the end of the file. The \\p identifier must be a name for a sound that was started through the #playAudio or #playAudio3d functions.
 
-\\param identifier The identifier to the track that should be stopped \\param loop If `Yes` then the song will be played in a loop until the program is closed or the playing is stopped through the #stopAudio function
+\\param identifier The identifier to the track that should be stopped \\param shouldLoop If `Yes` then the song will be played in a loop until the program is closed or the playing is stopped through the #stopAudio function
    */
   setLooping: (identifier: string, shouldLoop: boolean) => Promise<void>
   /**
    * Sets the position of the speaker for the provided \\p channel to the provided \\p position. In general, this is considered an advanced feature to accommodate non-standard audio environments.
 
 \\param channel The channel whose speaker's position should be changed \\param position The new position for the speaker
    */
-  setSpeakerPosition: (handle: integer, position: vec3) => Promise<void>
+  setSpeakerPosition: (channel: integer, position: vec3) => Promise<void>
   /**
    * Sets the volume of the track referred to by \\p handle to the new \\p volume. The volume should be a number bigger than 0, where 1 is the maximum volume level. The \\p fade controls whether the volume change should be immediately (if it is 0) or over how many seconds it should change. The default is for it to change over 500 ms.
 
-\\param handle The handle to the track whose volume should be changed \\param volume The new volume level. Must be greater or equal to 0 \\param fade How much time the fade from the current volume to the new volume should take
+\\param identifier The identifier to the track whose volume should be changed \\param volume The new volume level. Must be greater or equal to 0 \\param fade How much time the fade from the current volume to the new volume should take
    */
   setVolume: (identifier: string, volume: number, fade?: number) => Promise<void>
   /**
-   * Returns the position for the speaker of the provided \\p channel. \\return The position for the speaker of the provided \\p channel
+   * Returns the position for the speaker of the provided \\p channel.
+
+\\param channel The channel for which the position should be returned \\return The position for the speaker of the provided \\p channel
    */
-  speakerPosition: (handle: integer) => Promise<vec3>
+  speakerPosition: (channel: integer) => Promise<vec3>
   /**
    * Stops all currently playing tracks. After this function, none of the identifiers used to previously play a sound a valid any longer, but can still be used by the #playAudio or #playAudio3d functions to start a new sound. This function behaves the same way as if manually calling #stopAudio on all of the sounds that have been started.
    */
@@ -920,7 +924,7 @@ interface audioLibrary {
   /**
    * Returns the volume for the track referred to by the \\p handle. The number returned will be greater or equal to 0.
 
-\\return The volume for the track referred to by the \\p handle, which will be greater or equal to 0
+\\param identifier The identifier to the track whose volume should be returned \\return The volume for the track referred to by the \\p handle, which will be greater or equal to 0
    */
   volume: (identifier: string) => Promise<number>
 } // interface audioLibrary
@@ -1437,35 +1441,33 @@ interface modulesLibrary {
 
 interface navigationLibrary {
   /**
-   * Directly adds to the global roll of the camera. This is a rotation around the line between the focus node and the camera (not always the same as the camera view direction)
+   * Adds an instantaneous impulse to the global roll of the camera. This is a rotation around the line between the focus node and the camera. This is almost always the same as the forward direction of the camera, unless a local rotation has panned the camera away from the focus object. The global roll corresponds to using the middle mouse button and moving the mouse left and right. The unit for the provided parameter is somewhat arbitrary and the magnitude depends on the explicit use-case (continuously executing this function vs an individual impulse), but typically a range of [-250, 250] produces reasonable results.
 
-\\param value the value to add
+\\param value A positive value rolls the camera to the left and a negative value rolls the camera to the right
    */
   addGlobalRoll: (value: number) => Promise<void>
   /**
-   * Directly add to the global rotation of the camera (around the focus node).
+   * Adds an instantaneous impulse to the global rotation of the camera (around the focus node). This type of rotation corresponds to using the left mouse button and moving the mouse to rotate around the current focus object. The units for the provided parameters are somewhat arbitrary and the magnitude depends on the explicit use-case (continuously executing this function vs an individual impulse), but typically a range of [-500, 500] produces reasonable results.
 
-\\param xValue the value to add in the x-direction (a positive value rotates to the right and a negative value to the left) \\param yValue the value to add in the y-direction (a positive value rotates the focus upwards and a negative value downwards)
+\\param horizontal The value to add in the x-direction (a positive value rotates to the right and a negative value to the left) \\param vertical The value to add in the y-direction (a positive value rotates the focus upwards and a negative value downwards)
    */
-  addGlobalRotation: (xValue: number, yValue: number) => Promise<void>
+  addGlobalRotation: (horizontal: number, vertical: number) => Promise<void>
   /**
-   * Directly adds to the local roll of the camera. This is the rotation around the camera's forward/view direction.
+   * Adds an instantaneous impulse to the local roll of the camera. This is the rotation around the camera's forward direction and corresponds to using the middle mouse button and pressing and holding the middle mouse button while moving the mouse to the left and right. The unit for the provided parameter is somewhat arbitrary and the magnitude depends on the explicit use-case (continuously executing this function vs an individual impulse), but typically a range of [-250, 250] produces reasonable results.
 
-\\param value the value to add
+\\param value A positive value rolls the camera to the left and a negative value rolls the camera to the right
    */
   addLocalRoll: (value: number) => Promise<void>
   /**
-   * Directly adds to the local rotation of the camera (around the camera's current position).
+   * Adds an instantaneous impulse to the local rotation of the camera (around the camera's current position). This type of rotation corresponds to using the left mouse button and pressing the Ctrl key while moving mouse to rotate around the current camera position. The units for the provided parameters are somewhat arbitrary and the magnitude depends on the explicit use-case (continuously executing this function vs an individual impulse), but typically a range of [-250, 250] produces reasonable results.
 
-\\param xValue the value to add in the x-direction (a positive value rotates to the left and a negative value to the right) \\param yValue the value to add in the y-direction (a positive value rotates the camera upwards and a negative value downwards)
+\\param horizontal The value to add in the x-direction (a positive value rotates to the left and a negative value to the right) \\param vertical The value to add in the y-direction (a positive value rotates the camera upwards and a negative value downwards)
    */
-  addLocalRotation: (xValue: number, yValue: number) => Promise<void>
+  addLocalRotation: (horizontal: number, vertical: number) => Promise<void>
   /**
-   * Directly adds to the truck movement of the camera. This is the movement along the line from the camera to the focus node.
-
-A positive value moves the camera closer to the focus, and a negative value moves the camera further away.
+   * Adds an instantaneous impulse to create a truck movement of the camera. This is the movement along the line from the camera to the focus node and corresponds to using the right mouse button and moving the mous up and down. The unit for the provided parameter is somewhat arbitrary and the magnitude depends on the explicit use-case (continuously executing this function vs an individual impulse), but typically a range of [-1000, 1000] produces reasonable results.
 
-\\param value the value to add
+\\param value A positive value moves the camera closer to the focus node, and a negative value moves the camera further away.
    */
   addTruckMovement: (value: number) => Promise<void>
   /**
@@ -2241,7 +2243,7 @@ Note that providing time zone using the Z format is not supported. UTC is assume
 
 \\param time The time to set. If the parameter is a number, the value is the number of seconds past the J2000 epoch. If it is a string, it has to be a valid ISO 8601-like date string of the format YYYY-MM-DDTHH:MN:SS. \\param interpolationDuration The number of seconds that the interpolation should be done over. If excluded, the time is decided based on the default value for time interpolation specified in the TimeManager.
    */
-  interpolateTime: (time: string | number, interpolationDutation?: number) => Promise<void>
+  interpolateTime: (time: string | number, interpolationDuration?: number) => Promise<void>
   /**
    * Increment the current simulation time by the specified number of seconds, using interpolation.
 
@@ -2311,11 +2313,11 @@ Note that providing time zone using the Z format is not supported. UTC is assume
    */
   setTime: (time: number | string) => Promise<void>
   /**
-   * Returns the current time as an date string of the form (YYYY MON DDTHR:MN:SC.### ::RND) as returned by SPICE.
+   * Returns the current time as an date string. The format of the returned string can be adjusted by providing the format picture. The default picture that is used will be (YYYY MON DDTHR:MN:SC.### ::RND). See https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/timout_c.html for documentation on how the format string can be formatted
 
 \\return The current time, in the format used by SPICE (YYYY MON DDTHR:MN:SC.### ::RND)
    */
-  SPICE: () => Promise<string>
+  SPICE: (format?: string) => Promise<string>
   /**
    * Toggle the pause function, i.e. if the simulation is paused it will resume, and otherwise it will be paused. Note that to pause means temporarily setting the delta time to 0, and unpausing means restoring it to whatever delta time value is set.
    */

script/openspace-api-static.txt

@@ -22,7 +22,7 @@
  * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                         *
  ****************************************************************************************/
 
-declare module 'openspace-api-js' {
+declare module "openspace-api-js" {
   export class OpenSpaceApi {
     /**
      * Construct an instance of the OpenSpace API.
@@ -118,21 +118,23 @@ declare module 'openspace-api-js' {
     executeLuaScript(
       script: string,
       getReturnValue: boolean,
-      shouldBeSynchronized: boolean
+      shouldBeSynchronized: boolean,
     ): Promise<unknown | undefined>;
 
     /**
      * Execute a lua function from the OpenSpace library
      * @param function The lua function to execute (for example
      *                 `openspace.addSceneGraphNode`).
+     * @param args The function arguments.
      * @param getReturnValue Specified whether the return value should be collected.
      *
      * @return The return value of the script, if `getReturnValue` is true, otherwise
      *         undefined.
      */
     executeLuaFunction(
       fun: string,
-      getReturnValue: boolean
+      args: unknown[],
+      getReturnValue: boolean,
     ): Promise<unknown | undefined>;
 
     /**
@@ -189,7 +191,7 @@ declare module 'openspace-api-js' {
     constructor(
       iterator: AsyncGenerator<any, void, unknown>,
       talk: (payload: any) => void,
-      cancel: () => void
+      cancel: () => void,
     );
     /**
      * Send data within a topic

src/api.js

@@ -245,6 +245,7 @@ class OpenSpaceApi {
   /**
    * Execute a lua function from the OpenSpace library
    * @param {string} function - The lua function to execute (for example `openspace.addSceneGraphNode`).
+   * @param {*[]} args - The function arguments.
    * @param {string} getReturnValue - Specified whether the return value should be collected.
    * @return {*} The return value of the script, if `getReturnValue` is true, otherwise undefined.
    */
@@ -357,4 +358,4 @@ class OpenSpaceApi {
   }
 }
 
-module.exports = OpenSpaceApi;
+module.exports = OpenSpaceApi;