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

CONTRIBUTING.md

@@ -51,18 +51,10 @@ illuaminate, which spits out our HTML.
 For various reasons, getting the environment set up to build documentation can be pretty complex. I'd quite like to
 automate this via Docker and/or nix in the future, but this needs to be done manually for now.
 
-First, you will need JDK 9+ (in addition to JDK 8 which is required to build Minecraft itself). Sadly our version of
-Gradle doesn't support multiple toolchains, and so you need to install this yourself.
-
-Gradle needs to be told about this JDK via the `JAVA_HOME_11_X64` environment variable or adding `java11Home` to 
-`~/.gradle/gradle.properties`. On my system this looks like:
-
-```properties
-java11Home=/usr/lib/jvm/java-11-openjdk/
-```
-
-If you just want to build the documentation stubs for linting, this is enough. However, if you want to build the full
-website, you will also need to install a few Node packages by running `npm ci`.
+This tooling is only needed if you need to build the whole website. If you just want to generate the Lua stubs, you can
+skp this section.
+ - Install Node/npm and install our Node packages with `npm ci`.
+ - Install [illuaminate][illuaminate-usage] as described above.
 
 #### Building documentation
 Gradle should be your entrypoint to building most documentation. There's two tasks which are of interest:

build.gradle

@@ -7,15 +7,15 @@ buildscript {
             url = "https://files.minecraftforge.net/maven"
         }
         maven {
-            name = "mixin"
-            url = "https://dist.creeper.host/Sponge/maven"
+            name = "Sponge (Mixin)"
+            url = "https://repo.spongepowered.org/repository/maven-public/"
+            content { includeGroup "org.spongepowered" }
         }
     }
     dependencies {
         classpath 'com.google.code.gson:gson:2.8.1'
-        classpath 'net.minecraftforge.gradle:ForgeGradle:3.0.190'
+        classpath 'net.minecraftforge.gradle:ForgeGradle:4.1.3'
         classpath 'net.sf.proguard:proguard-gradle:6.1.0beta2'
-        classpath 'org.ajoberstar.grgit:grgit-gradle:3.0.0'
         classpath 'org.spongepowered:mixingradle:0.7-SNAPSHOT'
     }
 }
@@ -24,14 +24,13 @@ plugins {
     id "checkstyle"
     id "jacoco"
     id "com.github.hierynomus.license" version "0.15.0"
-    id "com.matthewprenger.cursegradle" version "1.3.0"
-    id "com.github.breadmoirai.github-release" version "2.2.4"
+    id "com.matthewprenger.cursegradle" version "1.4.0"
+    id "com.github.breadmoirai.github-release" version "2.2.12"
     id "org.jetbrains.kotlin.jvm" version "1.3.72"
 }
 
 apply plugin: 'net.minecraftforge.gradle'
 apply plugin: 'org.spongepowered.mixin'
-apply plugin: 'org.ajoberstar.grgit'
 apply plugin: 'maven-publish'
 apply plugin: 'maven'
 
@@ -40,7 +39,11 @@ version = mod_version
 group = "org.squiddev"
 archivesBaseName = "cc-tweaked-${mc_version}"
 
-sourceCompatibility = targetCompatibility = compileJava.sourceCompatibility = compileJava.targetCompatibility = '1.8'
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(8)
+    }
+}
 
 minecraft {
     runs {
@@ -172,11 +175,10 @@ task luaJavadoc(type: Javadoc) {
 
     options.docletpath = configurations.cctJavadoc.files as List
     options.doclet = "cc.tweaked.javadoc.LuaDoclet"
+    options.noTimestamp = false
 
-    // Attempt to run under Java 11 (any Java >= 9 will work though).
-    if(System.getProperty("java.version").startsWith("1.")
-        && (System.getenv("JAVA_HOME_11_X64") != null || project.hasProperty("java11Home"))) {
-        executable = "${System.getenv("JAVA_HOME_11_X64") ?: project.property("java11Home")}/bin/javadoc"
+    javadocTool = javaToolchains.javadocToolFor {
+        languageVersion = JavaLanguageVersion.of(11)
     }
 }
 
@@ -214,7 +216,6 @@ import com.google.gson.GsonBuilder
 import com.google.gson.JsonElement
 import com.hierynomus.gradle.license.tasks.LicenseCheck
 import com.hierynomus.gradle.license.tasks.LicenseFormat
-import org.ajoberstar.grgit.Grgit
 import proguard.gradle.ProGuardTask
 
 task proguard(type: ProGuardTask, dependsOn: jar) {
@@ -267,16 +268,15 @@ processResources {
     def hash = 'none'
     Set<String> contributors = []
     try {
-        def grgit = Grgit.open(dir: '.')
-        hash = grgit.head().id
+        hash = ["git", "-C", projectDir, "rev-parse", "HEAD"].execute().text.trim()
 
         def blacklist = ['GitHub', 'dan200', 'Daniel Ratcliffe']
-        grgit.log().each {
-            if (!blacklist.contains(it.author.name)) contributors.add(it.author.name)
-            if (!blacklist.contains(it.committer.name)) contributors.add(it.committer.name)
+        ["git", "-C", projectDir, "log", "--format=tformat:%an%n%cn"].execute().text.split('\n').each {
+            if (!blacklist.contains(it)) contributors.add(it)
         }
-    } catch(Exception ignored) { }
-
+    } catch(Exception e) {
+        e.printStackTrace()
+    }
     inputs.property "commithash", hash
 
     from(sourceSets.main.resources.srcDirs) {
@@ -497,8 +497,8 @@ tasks.register('jacocoTestInGameReport', JacocoReport.class).configure {
     it.dependsOn('testInGame')
 
     it.executionData(new File(buildDir, 'jacoco/testInGame.exec'))
-    it.setSourceDirectories(project.files(sourceSets.main.allJava.srcDirs))
-    it.setClassDirectories(project.files(new File(buildDir, 'jacocoClassDump/testInGame')))
+    it.sourceDirectories.from(sourceSets.main.allJava.srcDirs)
+    it.classDirectories.from(new File(buildDir, 'jacocoClassDump/testInGame'))
 
     it.reports {
         xml.enabled true
@@ -623,18 +623,23 @@ githubRelease {
     token project.hasProperty('githubApiKey') ? project.githubApiKey : ''
     owner 'SquidDev-CC'
     repo 'CC-Tweaked'
-    try {
-        targetCommitish = Grgit.open(dir: '.').branch.current().name
-    } catch(Exception ignored) { }
+    targetCommitish.set(project.provider({
+        try {
+            return ["git", "-C", projectDir, "rev-parse", "--abbrev-ref", "HEAD"].execute().text.trim()
+        } catch (Exception e) {
+            e.printStackTrace()
+        }
+        return "master"
+    }))
 
     tagName "v${mc_version}-${mod_version}"
     releaseName "[${mc_version}] ${mod_version}"
-    body {
+    body.set(project.provider({
         "## " + new File(projectDir, "src/main/resources/data/computercraft/lua/rom/help/whatsnew.txt")
             .readLines()
             .takeWhile { it != 'Type "help changelog" to see the full version history.' }
             .join("\n").trim()
-    }
+    }))
     prerelease false
 }
 

doc/events/alarm.md

@@ -0,0 +1,21 @@
+---
+module: [kind=event] alarm
+see: os.setAlarm To start an alarm.
+---
+
+The @{timer} event is fired when an alarm started with @{os.setAlarm} completes.
+
+## Return Values
+1. @{string}: The event name.
+2. @{number}: The ID of the alarm that finished.
+
+## Example
+Starts a timer and then prints its ID:
+```lua
+local alarmID = os.setAlarm(os.time() + 0.05)
+local event, id
+repeat
+    event, id = os.pullEvent("alarm")
+until id == alarmID
+print("Alarm with ID " .. id .. " was fired")
+```

doc/events/computer_command.md

@@ -0,0 +1,18 @@
+---
+module: [kind=event] computer_command
+---
+
+The @{computer_command} event is fired when the `/computercraft queue` command is run for the current computer.
+
+## Return Values
+1. @{string}: The event name.
+... @{string}: The arguments passed to the command.
+
+## Example
+Prints the contents of messages sent:
+```lua
+while true do
+  local event = {os.pullEvent("computer_command")}
+  print("Received message:", table.unpack(event, 2))
+end
+```

doc/events/disk.md

@@ -0,0 +1,19 @@
+---
+module: [kind=event] disk
+see: disk_eject For the event sent when a disk is removed.
+---
+
+The @{disk} event is fired when a disk is inserted into an adjacent or networked disk drive.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The side of the disk drive that had a disk inserted.
+
+## Example
+Prints a message when a disk is inserted:
+```lua
+while true do
+  local event, side = os.pullEvent("disk")
+  print("Inserted a disk on side " .. side)
+end
+```

doc/events/disk_eject.md

@@ -0,0 +1,19 @@
+---
+module: [kind=event] disk_eject
+see: disk For the event sent when a disk is inserted.
+---
+
+The @{disk_eject} event is fired when a disk is removed from an adjacent or networked disk drive.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The side of the disk drive that had a disk removed.
+
+## Example
+Prints a message when a disk is removed:
+```lua
+while true do
+  local event, side = os.pullEvent("disk_eject")
+  print("Removed a disk on side " .. side)
+end
+```

doc/events/http_check.md

@@ -0,0 +1,14 @@
+---
+module: [kind=event] http_check
+see: http.checkURLAsync To check a URL asynchronously.
+---
+
+The @{http_check} event is fired when a URL check finishes.
+
+This event is normally handled inside @{http.checkURL}, but it can still be seen when using @{http.checkURLAsync}.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The URL requested to be checked.
+3. @{boolean}: Whether the check succeeded.
+4. @{string|nil}: If the check failed, a reason explaining why the check failed.

doc/events/http_failure.md

@@ -0,0 +1,39 @@
+---
+module: [kind=event] http_failure
+see: http.request To send an HTTP request.
+---
+
+The @{http_failure} event is fired when an HTTP request fails.
+
+This event is normally handled inside @{http.get} and @{http.post}, but it can still be seen when using @{http.request}.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The URL of the site requested.
+3. @{string}: An error describing the failure.
+4. @{http.Response|nil}: A response handle if the connection succeeded, but the server's response indicated failure.
+
+## Example
+Prints an error why the website cannot be contacted:
+```lua
+local myURL = "https://does.not.exist.tweaked.cc"
+http.request(myURL)
+local event, url, err
+repeat
+    event, url, err = os.pullEvent("http_failure")
+until url == myURL
+print("The URL " .. url .. " could not be reached: " .. err)
+```
+
+Prints the contents of a webpage that does not exist:
+```lua
+local myURL = "https://tweaked.cc/this/does/not/exist"
+http.request(myURL)
+local event, url, err, handle
+repeat
+    event, url, err, handle = os.pullEvent("http_failure")
+until url == myURL
+print("The URL " .. url .. " could not be reached: " .. err)
+print(handle.getResponseCode())
+handle.close()
+```

doc/events/http_success.md

@@ -0,0 +1,27 @@
+---
+module: [kind=event] http_success
+see: http.request To make an HTTP request.
+---
+
+The @{http_success} event is fired when an HTTP request returns successfully.
+
+This event is normally handled inside @{http.get} and @{http.post}, but it can still be seen when using @{http.request}.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The URL of the site requested.
+3. @{http.Response}: The handle for the response text.
+
+## Example
+Prints the content of a website (this may fail if the request fails):
+```lua
+local myURL = "https://tweaked.cc/"
+http.request(myURL)
+local event, url, handle
+repeat
+    event, url, handle = os.pullEvent("http_success")
+until url == myURL
+print("Contents of " .. url .. ":")
+print(handle.readAll())
+handle.close()
+```

doc/events/key.md

@@ -11,9 +11,9 @@ If the button pressed represented a printable character, then the @{key} event w
 event. If you are consuming text input, use a @{char} event instead!
 
 ## Return values
-1. [`string`]: The event name.
-2. [`number`]: The numerical key value of the key pressed.
-3. [`boolean`]: Whether the key event was generated while holding the key (@{true}), rather than pressing it the first time (@{false}).
+1. @{string}: The event name.
+2. @{number}: The numerical key value of the key pressed.
+3. @{boolean}: Whether the key event was generated while holding the key (@{true}), rather than pressing it the first time (@{false}).
 
 ## Example
 Prints each key when the user presses it, and if the key is being held.

doc/events/modem_message.md

@@ -0,0 +1,22 @@
+---
+module: [kind=event] modem_message
+---
+
+The @{modem_message} event is fired when a message is received on an open channel on any modem.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The side of the modem that received the message.
+3. @{number}: The channel that the message was sent on.
+4. @{number}: The reply channel set by the sender.
+5. @{any}: The message as sent by the sender.
+6. @{number}: The distance between the sender and the receiver, in blocks (decimal).
+
+## Example
+Prints a message when one is sent:
+```lua
+while true do
+  local event, side, channel, replyChannel, message, distance = os.pullEvent("modem_message")
+  print(("Message received on side %s on channel %d (reply to %d) from %f blocks away with message %s"):format(side, channel, replyChannel, distance, tostring(message)))
+end
+```

doc/events/monitor_resize.md

@@ -0,0 +1,18 @@
+---
+module: [kind=event] monitor_resize
+---
+
+The @{monitor_resize} event is fired when an adjacent or networked monitor's size is changed.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The side or network ID of the monitor that resized.
+
+## Example
+Prints a message when a monitor is resized:
+```lua
+while true do
+  local event, side = os.pullEvent("monitor_resize")
+  print("The monitor on side " .. side .. " was resized.")
+end
+```

doc/events/monitor_touch.md

@@ -0,0 +1,20 @@
+---
+module: [kind=event] monitor_touch
+---
+
+The @{monitor_touch} event is fired when an adjacent or networked Advanced Monitor is right-clicked.
+
+## Return Values
+1. @{string}: The event name.
+2. @{string}: The side or network ID of the monitor that was touched.
+3. @{number}: The X coordinate of the touch, in characters.
+4. @{number}: The Y coordinate of the touch, in characters.
+
+## Example
+Prints a message when a monitor is touched:
+```lua
+while true do
+  local event, side, x, y = os.pullEvent("monitor_touch")
+  print("The monitor on side " .. side .. " was touched at (" .. x .. ", " .. y .. ")")
+end
+```