Package gaiasky.script.v2.api

Interface BaseAPI

All Known Implementing Classes:
BaseModule
public interface BaseAPI
Public API definition for the BaseModule, which contains methods and functions that perform essential or basic functionality.

  • Method Details

    • get_version

      String get_version()
      Return a string with the version number, the build string, the system, the builder, and the build time.
      Returns:
      A string with the full version information.

    • get_version_number

      String get_version_number()
      Return the version number string.
      Returns:
      The version number string.

    • get_build_string

      String get_build_string()
      Return the build string.
      Returns:
      The build string.

    • get_assets_dir

      String get_assets_dir()
      Gets the location of the asset directory. The asset directory contains some internal files essential for Gaia Sky to function properly, like the default versions of the configuration file, or the UI theme files.

      This location depends on the operating system and launch method.

    • get_default_frame_output_dir

      String get_default_frame_output_dir()
      Get the absolute path of the default output directory for the frame output system. This may be different from where the actual frames are saved, as this is specified in a setting in the configuration file.

      In order to get the actual current output location for the frame output system, use OutputModule.get_current_frame_output_dir().

      Returns:
      Absolute path of directory where still frames are saved.

    • get_default_screenshots_dir

      String get_default_screenshots_dir()
      Get the absolute path of the default directory where the screenshots are saved. This may be different from where the actual screenshots are saved, as this is specified in a setting in the configuration file.

      In order to get the actual current output location for screenshots, use OutputModule.get_current_screenshots_dir().

      Returns:
      Absolute path of directory where screenshots are saved.

    • get_camcorder_dir

      String get_camcorder_dir()
      Get the absolute path of the default directory where the camcorder files are saved.
      Returns:
      Absolute path of directory where camcorder files are saved.

    • get_mappings_dir

      String get_mappings_dir()
      Get the absolute path to the location of the inputListener mappings.
      Returns:
      Absolute path to the location of the inputListener mappings.

    • get_data_dir

      String get_data_dir()
      Get the absolute path of the local data directory, configured in your config.yaml file.
      Returns:
      Absolute path to the location of the data files.

    • get_config_dir

      String get_config_dir()
      Get the absolute path to the location of the configuration directory.
      Returns:
      Absolute path of config directory.

    • get_default_datasets_dir

      String get_default_datasets_dir()
      Get the absolute path to the default datasets directory. This is ~/.gaiasky/ in Windows and macOS, and ~/.local/share/gaiasky in Linux.

      Note that the actual datasets directory may be different, as it is stored in a setting in the configuration file. This only returns the default location. You can get the actual location where datasets are stored with DataModule.get_datasets_directory().

      Returns:
      Absolute path to the default data directory.

    • sleep

      void sleep(float secs)
      Sleep for the given number of seconds in the application time (FPS), so if we are capturing frames and the frame rate is set to 30 FPS, the command sleep(1) will put the script to sleep for 30 frames.
      Parameters:
      secs - The number of seconds to wait.

    • sleep_frames

      void sleep_frames(long frames)
      Sleep for a number of frames. The frame monitor is notified at the beginning of each frame, before the update-render cycle. When frames is 1, this method returns just before the processing of the next frame starts.
      Parameters:
      frames - The number of frames to wait.

    • post_runnable

      void post_runnable(Runnable r)
      Post a Runnable to the main loop thread. This Runnable runs once after the update-scene stage, and before the render stage.
      Parameters:
      r - The runnable to run.

    • park_scene_runnable

      void park_scene_runnable(String id, Runnable r)

      Park an update Runnable to the main loop thread, and keeps it running every frame until it finishes, or it is removed by remove_runnable(String). This object runs after the update-scene stage and before the render stage, so it is intended for updating scene objects.

      Be careful with this function, as it probably needs a cleanup before the script is finished. Otherwise, all parked runnables will keep running until Gaia Sky is restarted, so make sure to remove them with remove_runnable(String) if needed.

      Parameters:
      id - The string id to identify the runnable.
      r - The scene update runnable to park.

    • park_camera_runnable

      void park_camera_runnable(String id, Runnable r)

      Park a camera update Runnable to the main loop thread, and keeps it running every frame until it finishes, or it is removed by remove_runnable(String). This object runs after the update-camera stage and before the update-scene, so it is intended for updating the camera only.

      Be careful with this function, as it probably needs a cleanup before the script is finished. Otherwise, all parked runnables will keep running until Gaia Sky is restarted, so make sure to remove them with remove_runnable(String) if needed.

      Parameters:
      id - The string id to identify the runnable.
      r - The camera update runnable to park.

    • remove_runnable

      void remove_runnable(String id)
      Remove the runnable with the given id, if any. Use this method to remove previously parked scene and camera runnables.
      Parameters:
      id - The id of the runnable to remove.

    • settings_backup

      void settings_backup()

      Create a backup of the current settings state that can be restored later on. The settings are backed up in a stack, so multiple calls to this method put different copies of the settings on the stack in a LIFO fashion.

      This method, together with settings_restore(), are useful to back up and restore the settings at the beginning and end of your scripts, respectively, and ensure that the user settings are left unmodified after your script ends.

    • settings_restore

      boolean settings_restore()

      Take the settings object at the top of the settings stack and makes it effective.

      This method, together with settings_backup(), are useful to back up and restore the settings at the beginning and end of your scripts, respectively, and ensure that the user settings are left unmodified after your script ends.

      WARN: This function applies all settings immediately, and the user interface may be re-initialized. Be aware that the UI may be set to its default state after this call.

      Returns:
      True if the stack was not empty and the settings were restored successfully. False otherwise.

    • settings_clear_stack

      void settings_clear_stack()
      Clear the stack of settings objects. This will invalidate all previous calls to settings_backup(), effectively making the settings stack empty. Calling settings_restore() after this method will return false.

    • m_to_internal

      double m_to_internal()
      Returns the meter to internal unit conversion factor. Use this factor to multiply your coordinates in meters to get them in internal units.
      Returns:
      The factor Constants.M_TO_U.

    • internal_to_m

      double internal_to_m()
      Returns the internal unit to meter conversion factor. Use this factor to multiply your coordinates in internal units to get them in meters.
      Returns:
      The factor Constants.U_TO_M.

    • internal_to_m

      double internal_to_m(double iu)
      Converts the value in internal units to metres.
      Parameters:
      iu - The value in internal units.
      Returns:
      The value in metres.

    • internal_to_km

      double internal_to_km(double iu)
      Converts the value in internal units to Kilometers.
      Parameters:
      iu - The value in internal units.
      Returns:
      The value in Kilometers.

    • internal_to_km

      double[] internal_to_km(double[] iu)
      Converts the array in internal units to Kilometers.
      Parameters:
      iu - The array in internal units.
      Returns:
      The array in Kilometers.

    • internal_to_pc

      double internal_to_pc(double iu)
      Converts the value in internal units to parsecs.
      Parameters:
      iu - The value in internal units.
      Returns:
      The value in parsecs.

    • internal_to_pc

      double[] internal_to_pc(double[] iu)
      Converts the array in internal units to parsecs.
      Parameters:
      iu - The array in internal units.
      Returns:
      The array in parsecs.

    • m_to_internal

      double m_to_internal(double m)
      Converts the metres to internal units.
      Parameters:
      m - The value in metres.
      Returns:
      The value in internal units.

    • km_to_internal

      double km_to_internal(double km)
      Converts the kilometres to internal units.
      Parameters:
      km - The value in kilometers.
      Returns:
      The value in internal units.

    • pc_to_internal

      double pc_to_internal(double pc)
      Converts the parsecs to internal units.
      Parameters:
      pc - The value in parsecs.
      Returns:
      The value in internal units.

    • print

      void print(String msg)
      Print text using the internal logging system.
      Parameters:
      msg - The message.

    • log

      void log(String msg)
      Print text using the internal logging system.
      Parameters:
      msg - The message.

    • error

      void error(String msg)
      Log an error using the internal logging system.
      Parameters:
      msg - The error message.

    • quit

      void quit()
      Initiate the quit action to terminate the program. This call causes Gaia Sky to exit.