Merge branch 'mc-1.15.x' into mc-1.16.x

doc/stub/global.lua

@@ -0,0 +1,55 @@
+--[[-
+Global functions defined by `bios.lua`. This does not include standard Lua
+functions.
+
+@module _G
+]]
+
+--[[- Pauses execution for the specified number of seconds.
+
+As it waits for a fixed amount of world ticks, `time` will automatically be
+rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines
+or the @{parallel|parallel API}, it will only pause execution of the current
+thread, not the whole program.
+
+**Note** Because sleep internally uses timers, it is a function that yields.
+This means that you can use it to prevent "Too long without yielding" errors,
+however, as the minimum sleep time is 0.05 seconds, it will slow your program
+down.
+
+**Warning** Internally, this function queues and waits for a timer event (using
+@{os.startTimer}), however it does not listen for any other events. This means
+that any event that occurs while sleeping will be entirely discarded. If you
+need to receive events while sleeping, consider using @{os.startTimer|timers},
+or the @{parallel|parallel API}.
+
+@tparam number time The number of seconds to sleep for, rounded up to the
+nearest multiple of 0.05.
+
+@see os.startTimer
+]]
+function sleep(time) end
+
+function write(text) end
+function print(...) end
+function printError(...) end
+
+function read(replaceChar, history, completeFn, default) end
+
+--- The ComputerCraft and Minecraft version of the current computer environment.
+--
+-- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.
+_HOST = _HOST
+
+--[[- The default computer settings as defined in the ComputerCraft
+configuration.
+
+This is a comma-separated list of settings pairs defined by the mod
+configuration or server owner. By default, it is empty.
+
+An example value to disable autocompletion:
+
+    shell.autocomplete=false,lua.autocomplete=false,edit.autocomplete=false
+
+]]
+_CC_DEFAULT_SETTINGS = _CC_DEFAULT_SETTINGS

doc/stub/os.lua

@@ -1,6 +1,121 @@
 -- Defined in bios.lua
+
+--[[- Loads the given API into the global environment.
+
+**Warning** This function is deprecated. Use of this function will pollute the
+global table, use @{require} instead.
+
+This function loads and executes the file at the given path, and all global
+variables and functions exported by it will by available through the use of
+`myAPI.<function name>`, where `myAPI` is the base name of the API file.
+
+@tparam string path The path of the API to load.
+@treturn boolean Whether or not the API was successfully loaded.
+
+@deprecated Use @{require}.
+]]
 function loadAPI(path) end
+
+--- Unloads an API which was loaded by @{os.loadAPI}.
+--
+-- This effectively removes the specified table from `_G`.
+--
+-- @tparam string name The name of the API to unload.
+-- @deprecated Use @{require}.
+function unloadAPI(name) end
+
+--[[- Pause execution of the current thread and waits for any events matching
+`filter`.
+
+This function @{coroutine.yield|yields} the current process and waits for it
+to be resumed with a vararg list where the first element matches `filter`.
+If no `filter` is supplied, this will match all events.
+
+Unlike @{os.pullEventRaw}, it will stop the application upon a "terminate"
+event, printing the error "Terminated".
+
+@tparam[opt] string filter Event to filter for.
+@treturn string event The name of the event that fired.
+@treturn any param... Optional additional parameters of the event.
+@usage Listen for `mouse_click` events.
+
+    while true do
+        local event, button, x, y = os.pullEvent("mouse_click")
+        print("Button", button, "was clicked at", x, ",", y)
+    end
+
+@usage Listen for multiple events.
+
+    while true do
+        local eventData = {os.pullEvent()}
+        local event = eventData[1]
+
+        if event == "mouse_click" then
+            print("Button", eventData[2], "was clicked at", eventData[3], ",", eventData[4])
+        elseif event == "key" then
+            print("Key code", eventData[2], "was pressed")
+        end
+    end
+
+@see os.pullEventRaw To pull the terminate event.
+]]
 function pullEvent(filter) end
+
+--[[- Pause execution of the current thread and waits for events, including the
+`terminate` event.
+
+This behaves almost the same as @{os.pullEvent}, except it allows you to handle
+the `terminate` event yourself - the program will not stop execution when
+<kbd>Ctrl+T</kbd> is pressed.
+
+@tparam[opt] string filter Event to filter for.
+@treturn string event The name of the event that fired.
+@treturn any param... Optional additional parameters of the event.
+@usage Listen for `terminate` events.
+
+    while true do
+        local event = os.pullEventRaw()
+        if event == "terminate" then
+            print("Caught terminate event!")
+        end
+    end
+
+@see os.pullEvent To pull events normally.
+]]
 function pullEventRaw(filter) end
+
+--- Pauses execution for the specified number of seconds, alias of @{_G.sleep}.
+function sleep(time) end
+
+--- Get the current CraftOS version (for example, `CraftOS 1.8`).
+--
+-- This is defined by `bios.lua`. For the current version of CC:Tweaked, this
+-- should return `CraftOS 1.8`.
+--
+-- @treturn string The current CraftOS version.
 function version() end
+
+--[[- Run the program at the given path with the specified environment and
+arguments.
+
+This function does not resolve program names like the shell does. This means
+that, for example, `os.run("edit")` will not work. As well as this, it does not
+provide access to the @{shell} API in the environment. For this behaviour, use
+@{shell.run} instead.
+
+If the program cannot be found, or failed to run, it will print the error and
+return `false`. If you want to handle this more gracefully, use an alternative
+such as @{loadfile}.
+
+@tparam table env The environment to run the program with.
+@tparam string path The exact path of the program to run.
+@param ... The arguments to pass to the program.
+@treturn boolean Whether or not the program ran successfully.
+@usage Run the default shell from within your program:
+
+    os.run({}, "/rom/programs/shell")
+
+@see shell.run
+@see loadfile
+]]
 function run(env, path, ...) end

doc/styles.css

@@ -23,7 +23,7 @@ body {
                  "Droid Sans", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
 }
 
-code, pre, .parameter, .type, .definition-name, .reference-code {
+code, pre, kbd, .parameter, .type, .definition-name, .reference-code {
     font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
 }
 
@@ -111,7 +111,7 @@ footer {
 }
 
 /* The definition lists at the top of each page */
-table.definition-list {
+table.definition-list, table.pretty-table {
     border-collapse: collapse;
     width: 100%;
 }
@@ -128,8 +128,23 @@ table.definition-list th {
     text-align: right;
 }
 
+/* Deprecated definitions */
+table.definition-list tr.definition-deprecated th {
+    text-decoration: line-through;
+}
+
 table.definition-list td { width: 100%; }
 
+/* Pretty tables, mostly inherited from table.definition-list */
+table.pretty-table td, table.pretty-table th {
+    border: 1px solid #cccccc;
+    padding: 2px 4px;
+}
+
+table.pretty-table th {
+    background-color: #f0f0f0;
+}
+
 dl.definition dt {
     border-top: 1px solid #ccc;
     padding-top: 1em;
@@ -142,6 +157,10 @@ dl.definition dt .definition-name {
     flex-grow: 1;
 }
 
+/* Deprecated definitions */
+dl.definition dt .definition-name.definition-deprecated {
+    text-decoration: line-through;
+}
 
 dl.definition dd {
     padding-bottom: 1em;
@@ -173,6 +192,20 @@ span.parameter:after { content:":"; padding-left: 0.3em; }
     vertical-align: middle;
 }
 
+/** Fancy keyboard shortcut styling, inspired by GitHub markdown. */
+kbd {
+    display: inline-block;
+    padding: 4px 5px;
+    font-size: 0.8em;
+    line-height: 10px;
+    color: #444d56;
+    vertical-align: middle;
+    background-color: #fafbfc;
+    border: 1px solid #d1d5da;
+    border-radius: 3px;
+    box-shadow: inset 0 -1px 0 #d1d5da;
+}
+
 /* styles for prettification of source */
 .highlight .comment { color: #558817; }
 .highlight .constant { color: #a8660d; }

gradle.properties

@@ -1,5 +1,5 @@
 # Mod properties
-mod_version=1.93.0
+mod_version=1.93.1
 
 # Minecraft properties (update mods.toml when changing)
 mc_version=1.16.3

illuaminate.sexp

@@ -50,7 +50,7 @@
 
     ;; colours imports from colors, and we don't handle that right now.
     ;; keys is entirely dynamic, so we skip it.
-    (dynamic-modules colours keys)
+    (dynamic-modules colours keys _G)
 
     (globals
       :max
@@ -79,6 +79,7 @@
    /doc/stub/http.lua
    /doc/stub/os.lua
    /doc/stub/turtle.lua
+   /doc/stub/global.lua
    ; Java generated APIs
    /doc/javadoc/turtle.lua
    ; Peripherals
@@ -100,6 +101,10 @@
    /doc/stub/fs.lua)
   (linters -doc:unresolved-reference))
 
+;; Suppress warnings for the BIOS using its own deprecated members for now.
+(at /src/main/resources/*/computercraft/lua/bios.lua
+  (linters -var:deprecated))
+
 (at /src/test/resources/test-rom
   ; We should still be able to test deprecated members.
   (linters -var:deprecated)

src/main/java/dan200/computercraft/core/apis/OSAPI.java

@@ -171,12 +171,18 @@ public class OSAPI implements ILuaAPI
 
     /**
      * Starts a timer that will run for the specified number of seconds. Once
-     * the timer fires, a timer event will be added to the queue with the ID
-     * returned from this function as the first parameter.
+     * the timer fires, a {@code timer} event will be added to the queue with
+     * the ID returned from this function as the first parameter.
+     *
+     * As with @{os.sleep|sleep}, {@code timer} will automatically be rounded up
+     * to the nearest multiple of 0.05 seconds, as it waits for a fixed amount
+     * of world ticks.
      *
      * @param timer The number of seconds until the timer fires.
-     * @return The ID of the new timer.
+     * @return The ID of the new timer. This can be used to filter the
+     *   {@code timer} event, or {@link #cancelTimer cancel the timer}.
      * @throws LuaException If the time is below zero.
+     * @see #cancelTimer To cancel a timer.
      */
     @LuaFunction
     public final int startTimer( double timer ) throws LuaException
@@ -199,11 +205,14 @@ public class OSAPI implements ILuaAPI
 
     /**
      * Sets an alarm that will fire at the specified world time. When it fires,
-     * an alarm event will be added to the event queue.
+     * an {@code alarm} event will be added to the event queue with the ID
+     * returned from this function as the first parameter.
      *
      * @param time The time at which to fire the alarm, in the range [0.0, 24.0).
-     * @return The ID of the alarm that was set.
+     * @return The ID of the new alarm. This can be used to filter the
+     *   {@code alarm} event, or {@link #cancelAlarm cancel the alarm}.
      * @throws LuaException If the time is out of range.
+     * @see #cancelAlarm To cancel an alarm.
      */
     @LuaFunction
     public final int setAlarm( double time ) throws LuaException

src/main/java/dan200/computercraft/shared/peripheral/monitor/ClientMonitor.java

@@ -69,7 +69,7 @@ public final class ClientMonitor extends ClientTerminal
                 GL15.glBufferData( GL31.GL_TEXTURE_BUFFER, 0, GL15.GL_STATIC_DRAW );
                 tboTexture = GlStateManager.genTexture();
                 GL11.glBindTexture( GL31.GL_TEXTURE_BUFFER, tboTexture );
-                GL31.glTexBuffer( GL31.GL_TEXTURE_BUFFER, GL30.GL_R8, tboBuffer );
+                GL31.glTexBuffer( GL31.GL_TEXTURE_BUFFER, GL30.GL_R8UI, tboBuffer );
                 GL11.glBindTexture( GL31.GL_TEXTURE_BUFFER, 0 );
 
                 GlStateManager.bindBuffer( GL31.GL_TEXTURE_BUFFER, 0 );

src/main/resources/assets/computercraft/shaders/monitor.frag

@@ -6,7 +6,7 @@
 uniform sampler2D u_font;
 uniform int u_width;
 uniform int u_height;
-uniform samplerBuffer u_tbo;
+uniform usamplerBuffer u_tbo;
 uniform vec3 u_palette[16];
 
 in vec2 f_pos;
@@ -30,9 +30,9 @@ void main() {
     vec2 outside = step(vec2(0.0, 0.0), vec2(cell)) * step(vec2(cell), vec2(float(u_width) - 1.0, float(u_height) - 1.0));
     float mult = outside.x * outside.y;
 
-    int character = int(texelFetch(u_tbo, index).r * 255.0);
-    int fg = int(texelFetch(u_tbo, index + 1).r * 255.0);
-    int bg = int(texelFetch(u_tbo, index + 2).r * 255.0);
+    int character = int(texelFetch(u_tbo, index).r);
+    int fg = int(texelFetch(u_tbo, index + 1).r);
+    int bg = int(texelFetch(u_tbo, index + 2).r);
 
     vec2 pos = (term_pos - corner) * vec2(FONT_WIDTH, FONT_HEIGHT);
     vec4 img = texture(u_font, (texture_corner(character) + pos) / 256.0);

src/main/resources/data/computercraft/lua/rom/apis/colors.lua

@@ -1,15 +1,137 @@
---- The Colors API allows you to manipulate sets of colors.
---
--- This is useful in conjunction with Bundled Cables from the RedPower mod,
--- RedNet Cables from the MineFactory Reloaded mod, and colors on Advanced
--- Computers and Advanced Monitors.
---
--- For the non-American English version just replace @{colors} with @{colours}
--- and it will use the other API, colours which is exactly the same, except in
--- British English (e.g. @{colors.gray} is spelt @{colours.grey}).
---
--- @see colours
--- @module colors
+--[[- The Colors API allows you to manipulate sets of colors.
+
+This is useful in conjunction with Bundled Cables from the RedPower mod, RedNet
+Cables from the MineFactory Reloaded mod, and colors on Advanced Computers and
+Advanced Monitors.
+
+For the non-American English version just replace @{colors} with @{colours} and
+it will use the other API, colours which is exactly the same, except in British
+English (e.g. @{colors.gray} is spelt @{colours.grey}).
+
+On basic terminals (such as the Computer and Monitor), all the colors are
+converted to grayscale. This means you can still use all 16 colors on the
+screen, but they will appear as the nearest tint of gray. You can check if a
+terminal supports color by using the function @{term.isColor}.
+
+Grayscale colors are calculated by taking the average of the three components,
+i.e. `(red + green + blue) / 3`.
+
+<table class="pretty-table">
+<thead>
+    <tr><th colspan="8" align="center">Default Colors</th></tr>
+    <tr>
+    <th rowspan="2" align="center">Color</th>
+    <th colspan="3" align="center">Value</th>
+    <th colspan="4" align="center">Default Palette Color</th>
+    </tr>
+    <tr>
+    <th>Dec</th><th>Hex</th><th>Paint/Blit</th>
+    <th>Preview</th><th>Hex</th><th>RGB</th><th>Grayscale</th>
+    </tr>
+</thead>
+<tbody>
+    <tr>
+    <td><code>colors.white</code></td>
+    <td align="right">1</td><td align="right">0x1</td><td align="right">0</td>
+    <td style="background:#F0F0F0"></td><td>#F0F0F0</td><td>240, 240, 240</td>
+    <td style="background:#F0F0F0"></td>
+    </tr>
+    <tr>
+    <td><code>colors.orange</code></td>
+    <td align="right">2</td><td align="right">0x2</td><td align="right">1</td>
+    <td style="background:#F2B233"></td><td>#F2B233</td><td>242, 178, 51</td>
+    <td style="background:#9D9D9D"></td>
+    </tr>
+    <tr>
+    <td><code>colors.magenta</code></td>
+    <td align="right">4</td><td align="right">0x4</td><td align="right">2</td>
+    <td style="background:#E57FD8"></td><td>#E57FD8</td><td>229, 127, 216</td>
+    <td style="background:#BEBEBE"></td>
+    </tr>
+    <tr>
+    <td><code>colors.lightBlue</code></td>
+    <td align="right">8</td><td align="right">0x8</td><td align="right">3</td>
+    <td style="background:#99B2F2"></td><td>#99B2F2</td><td>153, 178, 242</td>
+    <td style="background:#BFBFBF"></td>
+    </tr>
+    <tr>
+    <td><code>colors.yellow</code></td>
+    <td align="right">16</td><td align="right">0x10</td><td align="right">4</td>
+    <td style="background:#DEDE6C"></td><td>#DEDE6C</td><td>222, 222, 108</td>
+    <td style="background:#B8B8B8"></td>
+    </tr>
+    <tr>
+    <td><code>colors.lime</code></td>
+    <td align="right">32</td><td align="right">0x20</td><td align="right">5</td>
+    <td style="background:#7FCC19"></td><td>#7FCC19</td><td>127, 204, 25</td>
+    <td style="background:#767676"></td>
+    </tr>
+    <tr>
+    <td><code>colors.pink</code></td>
+    <td align="right">64</td><td align="right">0x40</td><td align="right">6</td>
+    <td style="background:#F2B2CC"></td><td>#F2B2CC</td><td>242, 178, 204</td>
+    <td style="background:#D0D0D0"></td>
+    </tr>
+    <tr>
+    <td><code>colors.gray</code></td>
+    <td align="right">128</td><td align="right">0x80</td><td align="right">7</td>
+    <td style="background:#4C4C4C"></td><td>#4C4C4C</td><td>76, 76, 76</td>
+    <td style="background:#4C4C4C"></td>
+    </tr>
+    <tr>
+    <td><code>colors.lightGray</code></td>
+    <td align="right">256</td><td align="right">0x100</td><td align="right">8</td>
+    <td style="background:#999999"></td><td>#999999</td><td>153, 153, 153</td>
+    <td style="background:#999999"></td>
+    </tr>
+    <tr>
+    <td><code>colors.cyan</code></td>
+    <td align="right">512</td><td align="right">0x200</td><td align="right">9</td>
+    <td style="background:#4C99B2"></td><td>#4C99B2</td><td>76, 153, 178</td>
+    <td style="background:#878787"></td>
+    </tr>
+    <tr>
+    <td><code>colors.purple</code></td>
+    <td align="right">1024</td><td align="right">0x400</td><td align="right">a</td>
+    <td style="background:#B266E5"></td><td>#B266E5</td><td>178, 102, 229</td>
+    <td style="background:#A9A9A9"></td>
+    </tr>
+    <tr>
+    <td><code>colors.blue</code></td>
+    <td align="right">2048</td><td align="right">0x800</td><td align="right">b</td>
+    <td style="background:#3366CC"></td><td>#3366CC</td><td>51, 102, 204</td>
+    <td style="background:#777777"></td>
+    </tr>
+    <tr>
+    <td><code>colors.brown</code></td>
+    <td align="right">4096</td><td align="right">0x1000</td><td align="right">c</td>
+    <td style="background:#7F664C"></td><td>#7F664C</td><td>127, 102, 76</td>
+    <td style="background:#656565"></td>
+    </tr>
+    <tr>
+    <td><code>colors.green</code></td>
+    <td align="right">8192</td><td align="right">0x2000</td><td align="right">d</td>
+    <td style="background:#57A64E"></td><td>#57A64E</td><td>87, 166, 78</td>
+    <td style="background:#6E6E6E"></td>
+    </tr>
+    <tr>
+    <td><code>colors.red</code></td>
+    <td align="right">16384</td><td align="right">0x4000</td><td align="right">e</td>
+    <td style="background:#CC4C4C"></td><td>#CC4C4C</td><td>204, 76, 76</td>
+    <td style="background:#767676"></td>
+    </tr>
+    <tr>
+    <td><code>colors.black</code></td>
+    <td align="right">32768</td><td align="right">0x8000</td><td align="right">f</td>
+    <td style="background:#111111"></td><td>#111111</td><td>17, 17, 17</td>
+    <td style="background:#111111"></td>
+    </tr>
+</tbody>
+</table>
+
+@see colours
+@module colors
+]]
 
 local expect = dofile("rom/modules/main/cc/expect.lua").expect
 
@@ -37,7 +159,7 @@ yellow = 0x10
 -- terminal colour of #7FCC19.
 lime = 0x20
 
---- Pink. Written as `6` in paint files and @{term.blit}, has a default
+--- Pink: Written as `6` in paint files and @{term.blit}, has a default
 -- terminal colour of #F2B2CC.
 pink = 0x40
 
@@ -74,10 +196,11 @@ green = 0x2000
 red = 0x4000
 
 --- Black: Written as `f` in paint files and @{term.blit}, has a default
--- terminal colour of #191919.
+-- terminal colour of #111111.
 black = 0x8000
 
---- Combines a set of colors (or sets of colors) into a larger set.
+--- Combines a set of colors (or sets of colors) into a larger set. Useful for
+-- Bundled Cables.
 --
 -- @tparam number ... The colors to combine.
 -- @treturn number The union of the color sets given in `...`
@@ -96,7 +219,8 @@ function combine(...)
     return r
 end
 
---- Removes one or more colors (or sets of colors) from an initial set.
+--- Removes one or more colors (or sets of colors) from an initial set. Useful
+-- for Bundled Cables.
 --
 -- Each parameter beyond the first may be a single color or may be a set of
 -- colors (in the latter case, all colors in the set are removed from the
@@ -121,7 +245,8 @@ function subtract(colors, ...)
     return r
 end
 
---- Tests whether `color` is contained within `colors`.
+--- Tests whether `color` is contained within `colors`. Useful for Bundled
+-- Cables.
 --
 -- @tparam number colors A color, or color set
 -- @tparam number color A color or set of colors that `colors` should contain.

src/main/resources/data/computercraft/lua/rom/help/changelog.txt

@@ -1,3 +1,8 @@
+# New features in CC: Tweaked 1.93.1
+
+* Various documentation improvements (Lemmmy).
+* Fix TBO monitor renderer on some older graphics cards (Lemmmy).
+
 # New features in CC: Tweaked 1.93.0
 
 * Update Swedish translations (Granddave).

src/main/resources/data/computercraft/lua/rom/help/whatsnew.txt

@@ -1,11 +1,6 @@
-New features in CC: Tweaked 1.93.0
+New features in CC: Tweaked 1.93.1
 
-* Update Swedish translations (Granddave).
-* Printers use item tags to check dyes.
-* HTTP rules may now be targetted for a specific port.
-* Don't propagate adjacent redstone signals through computers.
-
-And several bug fixes:
-* Fix NPEs when turtles interact with containers.
+* Various documentation improvements (Lemmmy).
+* Fix TBO monitor renderer on some older graphics cards (Lemmmy).
 
 Type "help changelog" to see the full version history.

src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua

@@ -13,7 +13,7 @@
 -- @module cc.pretty
 -- @usage Print a table to the terminal
 --     local pretty = require "cc.pretty"
---     pretty.write(pretty.dump({ 1, 2, 3 }))
+--     pretty.write(pretty.pretty({ 1, 2, 3 }))
 --
 -- @usage Build a custom document and display it
 --     local pretty = require "cc.pretty"