Merge branch 'develop' for v1.1.9.0 release

CHANGELOG.md

@@ -1,6 +1,76 @@
 kOS Mod Changelog
 =================
 
+# v1.1.9.0 Breaking Bounds
+
+This update is a mix of new features, mostly
+
+### BREAKING CHANGES
+
+### NEW FEATURES
+
+- Bounding box information for parts and for the vessel as
+  a whole is now exposed for scripts to read.
+  [pull request 1](https://github.com/KSP-KOS/KOS/pull/2563).
+  [pull request 2](https://github.com/KSP-KOS/KOS/pull/2564).
+- The above bounding box feature also came with some new suffixes 
+  for Vecdraw so you can now draw plain lines (suppress the
+  arrowhead, suppress the opacity fade) with them.
+- Lexicons can now use the suffix syntax.  i.e. where you 
+  say ``mylex["key1"]`` you can now say ``mylex:key1``,
+  provided the key is something that works as a valid identifier
+  string (no spaces, etc).
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2553).
+- Can now set the default terminal Width and Height for all
+  newly spawned terminals.
+  [pull request 1](https://github.com/KSP-KOS/KOS/pull/2573).
+- A ternary conditional operator exists in kerboscript now,
+  using the syntax ``CHOOSE expr1 IF bool_expr ELSE expr2``.
+  If *bool_expr* is true, it returns expr1.  If it's false,
+  it returns expr2.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2549).
+- Added support to read more atmospheric values from KSP.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2557).
+
+### BUG FIXES
+
+- TimeSpan now peeks at the KSP game to learn its notion of
+  how long a day is, and how long a year is, rather than hardcoding
+  the values.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2582).
+- Fix cooked control triggers not working during a WHEN/ON trigger.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2534).
+- Fix mangled state if kOS is out of electricity when scenes switch
+  or the game is saved.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2521).
+- Obsolete list command documentation removed.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2520).
+- Allow part modules'd fields to work even when no GUI name is defined.
+  It seems that the main game allows the GUI name to be left out and if
+  so it inherits from the base name under tne hood.  Now kOS follows
+  this behaviour.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2519).
+- Prevent using UNSET on built-in variable names like SHIP, ALTITUDE,
+  and so on.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2510).
+- RP-1 used a different technique to lock out controls due to
+  insufficient avionics that kOS didn't know about.  kOS bypassed
+  this lockout and still controlled the vessel anyway.  This is no
+  longer the case.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2546).
+- PartModule:SETFIELD now works properly with the new type of slider
+  widget that robotic parts use in KSP 1.7.x.  KSP introduced a new
+  type of slider widget that presents false information when kOS tried
+  to obey its min, max, and detent values, those being only dummy
+  placeholders for these types of sliders, not actually populated with
+  the real values.  For these sliders, the real limit values come from
+  another field, requiring a more indirect method call to get the information.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2554).
+- GUI windows no longer use the KSP control lock system to emulate
+  keyboard focus, instead relying on the built-in Unity IMGUI
+  focus rules for widgets, thus they won't 'steal focus' as much.
+  [pull request](https://github.com/KSP-KOS/KOS/pull/2577).
+
 # v1.1.8.0 Engines and KSP 1.7 compatibility
 
 Mostly this was motivated by a need to get an officially

CONTRIBUTING.md

@@ -43,18 +43,27 @@ Pull Requests
 
 ####Nobody merges their own PR
 
+NOTE THIS RULE IS SUSPENDED.
+
+THIS RULE IS SUSPENDED BECAUSE THE DEV TEAM SHRUNK TO JUST ONE
+PERSON, MAKING IT IMPOSSIBLE TO GET ANY PR MERGED IF THIS RULE
+WAS STILL BEING FOLLOWED.  (If the dev team grows again to more
+people, this rule may be re-instated, as it is very good practice,
+WHEN there's actually more than one person on the team who has the
+time.)
+
 (Rules for priviledged members of the team who have permission to
 write directly to the main repository.)
 
-1. As a general policy, even experienced developers on the team should not
+1. (SUSPENDED - SEE ABOVE) As a general policy, even experienced developers on the team should not
    merge their own pull requests into the upstream `develop`.  Instead they
    should get another developer to merge it for them.
-2. As such, even if you have permission to do so, never directly push a
+2. (SUSPENDED - SEE ABOVE) As such, even if you have permission to do so, never directly push a
    change to `upstream develop` except in cases where you are doing so as
    part of the process of merging somebody *else's* pull request other than
    your own, or during some of the final steps of the release checklist
    that require it.
-3. When merging somebody else's pull request, do not "rubber stamp" it.  Actually
+3. (SUSPENDED - SEE ABOVE) When merging somebody else's pull request, do not "rubber stamp" it.  Actually
    try to read and understand what it does and how, and raise questions with
    the author using the github "line note" system.
 
@@ -146,12 +155,25 @@ Setting Up Your Environment
   pull request to KSP-KOS/KOS `develop` for review to be included.
 
 ####Setting Up The Solution Dependencies
+
 1. Copy the folder `$KOS/Resources/GameData/kOS` to `$KSP/GameData/`
 
-2. Copy `Assembly-CSharp.dll`, `Assembly-CSharp-firstpass.dll`,
-  `UnityEngine.dll` and `UnityEngine.UI.dll` from `$KSP/KSP_Data/Managed`
-  into `$KOS/Resources`.  If you do not have a copy of KSP locally, you may
-  download dummy assemblies at https://github.com/KSP-KOS/KSP_LIB
+2. Get the Unity assemblies into your project. There are two options:
+	1. Copy these DLLs from `$KSP/KSP_Data/Managed `into `$KOS/Resources`:
+		* `Assembly-CSharp`
+		* `Assembly-CSharp-firstpass`
+		* `UnityEngine`
+		* `UnityEngine.AnimationModule`
+		* `UnityEngine.AudioModule`
+		* `UnityEngine.CoreModule`
+		* `UnityEngine.ImageConversionModule`
+		* `UnityEngine.IMGUIModule`
+		* `UnityEngine.PhysicsModule`
+		* `UnityEngine.TextRenderingModule`
+		* `UnityEngine.UI`
+		* `UnityEngine.UnityWebRequestWWWModule`
+	2. If you do not have a copy of KSP locally, you may
+	  download dummy assemblies at https://github.com/KSP-KOS/KSP_LIB
 
 3. If you want building the solution to update the dlls in your KSP
    directory, create a symbolic link called `KSPdirlink` from the root

Resources/GameData/kOS/kOS.version

@@ -11,13 +11,13 @@
   "VERSION": {
     "MAJOR": 1,
     "MINOR": 1,
-    "PATCH": 8,
+    "PATCH": 9,
     "BUILD": 0
   },
   "KSP_VERSION": {
     "MAJOR": 1,
     "MINOR": 7,
-    "PATCH": 0
+    "PATCH": 3
   },
   "KSP_VERSION_MIN": {
     "MAJOR": 1,
@@ -27,6 +27,6 @@
   "KSP_VERSION_MAX": {
     "MAJOR": 1,
     "MINOR": 7,
-    "PATCH": 0
+    "PATCH": 99
   }
 }

doc/README.md

@@ -3,7 +3,7 @@ KOS_DOC
 The documents are generated using Sphinx restructured text, with the ReadTheDocs
 theme.
 
-#Getting started on Windows
+# Getting started on Windows
 
 (For this example, the KOS repository is assumed to be located at `C:\KOS`,
 you should adjust your path based on your actual repository location)
@@ -51,14 +51,14 @@ you should adjust your path based on your actual repository location)
 
   At which point you can point your browser to `http://localhost:8000`
 
-#Getting started on Linux
+# Getting started on Linux
 1. As with Windows above, install Python 2.7.  You may use your distribution's
   package manager system, or download from: https://www.python.org/downloads/
 
 2. All other instructions are the same as above for windows, replacing the `\`
   path character with `/` and adapting paths to reference your Linux file system.
 
-#Publishing
+# Publishing
 
 This section pertains only to what has to be done when a new release of
 the documentation is being made public (usually to correspond to a new
@@ -134,3 +134,23 @@ performed on every single documentation edit and every merged PR.
   ```
   C:\KOS-gh-pages>git push KOS_DOC gh-pages
   ```
+
+# Generating Dash Docset
+
+[Dash](https://kapeli.com/dash) is an offline API Documentation Browser and
+Code Snippet Manager for macOS.
+
+1. Install the [doc2dash][doc-2-dash] python package using `pipx` as
+   recommended in the linked instructions.
+2. Follow the instructions in "Getting started on Windows" adapting for macOS
+   as necessary. (Basically the Linux instructions, but no need to install
+   python).
+3. After compiling the RTD docs, use doc2dash to create a docset. From the
+   `doc/` folder run:
+   ```
+   pipx run doc2dash -n kOS -A gh-pages --icon=source/_images/kos_logo_konly.png
+   ```
+4. If this completes successfully and you have Dash installed, the docset will
+   automatically open and be added to your docset library.
+
+[doc-2-dash]: https://doc2dash.readthedocs.io/en/stable/installation.html

doc/source/changes.rst

@@ -24,6 +24,76 @@ release.
 
 ****
 
+Changes in 1.1.9.0
+------------------
+
+BOUNDING BOX
+::::::::::::
+
+Added the new :struct:`BOUNDS` structure for bounding box
+information, and made an :ref:`example using it <display_bounds>`
+on the tutorials page.
+
+TERNARY OPERATOR "CHOOSE"
+:::::::::::::::::::::::::
+
+A new expression ternary operator exists in kerboscript, called
+:ref:`CHOOSE <choose>`.  (Similar to C's "?" operator, but with
+different syntax.)
+
+New suffixes for Vecdraw
+::::::::::::::::::::::::
+
+New suffixes giving you more control over the appearance of
+vecdraws: :attr:`Vecdraw:POINTY` :attr:`Vecdraw:WIPING`
+
+Lexicon Suffixes
+::::::::::::::::
+
+:ref:`Describe using suffixes with lexicons. <lexicon_suffix>`
+
+Terminal default size
+:::::::::::::::::::::
+
+Two new config settings for a default terminal size for
+new terminals:
+
+:struct:`Config:DEFAULTWIDTH`, :struct:`Config:DEFAULTHEIGHT`
+
+Additional Atmospheric information
+:::::::::::::::::::::::::::::::::::
+
+Added some more information to the :struct:`atmosphere` structure,
+(mostly for people trying to perform drag calculations: 
+MOLARMASS, ADIABATICINDEX, ALTITUDETEMPERATURE).
+
+Also added the ability to read some more of the values the
+game uses for :ref:`mathematical constants <constants>`, to 
+work with this information: Avogadro, Boltzmann, and IdealGas.
+
+UNSET documentation
+:::::::::::::::::::
+
+Explicitly mention the :ref:`unset command <unset>`, which has existed
+for a long time but apparently wasn't in the documentation.
+
+LIST command
+::::::::::::
+
+Removed obsolete documentation about a no-longer-existing "FROM"
+variant of the LIST command that went like this:
+LIST *things* FROM *vessel* IN *variable*.
+
+DROPPRIORITY()
+::::::::::::::
+
+Described the new :func:`DROPPRIORITY()` built-in function that you
+can use when you want to write a long-lasting trigger body without
+it preventing other triggers from interrupting like it normally would.
+
+
+
+
 Changes in 1.1.8.0
 ------------------
 

doc/source/commands/flight/cooked.rst

@@ -184,17 +184,18 @@ Like all ``LOCK`` expressions, the steering and throttle continually update on t
     LOCK WHEELSTEERING.  See the note in the next section below.
 
 
-Don't 'WAIT' during cooked control calculation
-----------------------------------------------
+Don't 'WAIT' or run slow script code during cooked control calculation
+----------------------------------------------------------------------
 
 Be aware that because LOCK THROTTLE, LOCK STEERING, LOCK
-WHEELTHROTTLE, and LOCK WHEELSTEERING are actually
-:ref:`triggers <triggers>` that cause your expression
-to be calculated every single physics update tick behind
-the scenes, you should not execute a ``WAIT`` command
-in the code that performs the evaluation of the value
-used in them, as that will effectively cheat the entire
-script out of the full execution speed it deserves.
+WHEELTHROTTLE, and LOCK WHEELSTEERING are actually the
+highest priority types of :ref:`triggers <triggers>` that
+exist in kOS, they cause your expression to be calculated
+every single physics update tick behind the scenes.  So you
+should not execute a ``WAIT`` command in the code that
+performs the evaluation of the value used in them, as that
+will effectively cheat the entire script out of the full
+execution speed it deserves.
 
 For example, if you attempt this::
 
@@ -216,6 +217,13 @@ there, not resuming until the next update, effectively meaning
 it doesn't get around to running any of your main-line code
 until the next tick.)
 
+Again, note that the cooked steering LOCKS mentioned here are
+the *highest* priority triggers there are in kOS.  That means they
+can even interrupt other triggers like WHEN/THEN or GUI callbacks.
+Do not make them call complex functions that take a lot of instructions
+to return a value, or else you might find that there's not enough
+instructions per update left to run the rest of your program effectively.
+
 Normally when you use a LOCK command, the expression is only evaluated
 when it needs to be by some other part of the script that is trying
 to read the value.  But with these special cooked control locks,

doc/source/commands/flight/systems.rst

@@ -59,7 +59,7 @@ RCS and SAS
 
         SET SASMODE TO value.
 
-    It is the equivalent to clicking on the buttons next to the nav ball while manually piloting the craft, and will respect the current mode of the nav ball (orbital, surface, or target velocity - use NAVMODE to read or set it).  Valid strings for ``value`` are ``"PROGRADE"``, ``"RETROGRADE"``, ``"NORMAL"``, ``"ANTINORMAL"``, ``"RADIALOUT"``, ``"RADIALIN"``, ``"TARGET"``, ``"ANTITARGET"``, ``"MANEUVER"``, ``"STABILITYASSIST"``, and ``"STABILITY"``.  A null or empty string will default to stability assist mode, however any other invalid string will throw an exception.  This feature will respect career mode limitations, and will throw an exception if the current vessel is not able to use the mode passed to the command.  An exception is also thrown if ``"TARGET"`` or ``"ANTITARGET"`` are used, but no target is selected.
+    It is the equivalent to clicking on the buttons next to the nav ball while manually piloting the craft, and will respect the current mode of the nav ball (orbital, surface, or target velocity - use NAVMODE to read or set it).  Valid strings for ``value`` are ``"PROGRADE"``, ``"RETROGRADE"``, ``"NORMAL"``, ``"ANTINORMAL"``, ``"RADIALOUT"``, ``"RADIALIN"``, ``"TARGET"``, ``"ANTITARGET"``, ``"MANEUVER"``, ``"STABILITYASSIST"``, and ``"STABILITY"``.  A null or empty string will default to stability assist mode, however any other invalid string will throw an exception.  This feature will respect career mode limitations, and will throw an exception if the current vessel is not able to use the mode passed to the command.  An exception is also thrown if ``"TARGET"`` or ``"ANTITARGET"`` are used when no target is set.
 
     .. note::
         SAS mode is reset to stability assist when toggling SAS on, however it doesn't happen immediately.
@@ -388,4 +388,13 @@ TARGET
 
     For more information see :ref:`bindings`.
 
+    NOTE, the way to de-select the target is to set it to an empty
+    string like this::
+
+        SET TARGET TO "". // de-selects the target, setting it to nothing.
+
+    (Trying to use :ref:`UNSET TARGET.<unset>` will have no effect because
+    ``UNSET`` means "get rid of the variable itself" which you're not
+    allowed to do with built-in bound variables like ``TARGET``.)
+
 Note that the above options also can refer to a different vessel besides the current ship, for example, ``TARGET:THROTTLE`` to read the target's throttle. But not all "set" or "lock" options will work with a different vessel other than the current one, because there's no authority to control a craft the current program is not attached to.

doc/source/commands/list.rst

@@ -10,7 +10,7 @@ A :struct:`List` is a type of :ref:`Structure <features structures>` that stores
 ``FOR`` Loop
 ------------
 
-Lists need to be iterated over sometimes, to help with this we have the :ref:`FOR loop, explained on the flow control page <for>`. The ``LIST`` Command comes in 4 forms:
+Lists need to be iterated over sometimes, to help with this we have the :ref:`FOR loop, explained on the flow control page <for>`. The ``LIST`` Command comes in 3 forms:
 
 1. ``LIST.``
     When no parameters are given, the LIST command is exactly equivalent to the command::
@@ -23,9 +23,6 @@ Lists need to be iterated over sometimes, to help with this we have the :ref:`FO
 3. ``LIST ListKeyword IN YourVariable.``
     This variant takes the items that would otherwise have been printed to the terminal screen, and instead makes a :struct:`List` of them in ``YourVariable``, that you can then iterate over with a :ref:`FOR loop <for>` if you like.
 
-4. ``LIST ListKeyword FROM SomeVessel IN YourVariable.``
-    This variant is just like variant (3), except that it gives a list of the items that exist on some other vessel that might not necessarily be the current :ref:`CPU_vessel <cpu vessel>`.
-
 Available Listable Keywords
 ---------------------------
 
@@ -118,8 +115,8 @@ Here are some more examples::
     PRINT "The mass of the whole solar system is " + totMass.
 
     // Adds variable foo that contains a list of
-    // resources for my currently target vessel
-    LIST RESOURCES FROM TARGET IN foo.
+    // resources for my current vessel
+    LIST RESOURCES IN foo.
     FOR res IN foo {
         PRINT res:NAME. // Will print the name of every
                         // resource in the vessel

doc/source/conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.1.8.0'
+version = '1.1.9.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.1.8.0'
+release = '1.1.9.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.