Merge branch 'mc-1.20.x' into mc-1.20.y

Historically (and according to the docs) getAudioTitle returned "false"
when the drive was empty (or had invalid media), and "null" when the
disk had no item. This was accidentally changed in a later refactor --
this change fixes that behaviour.

.github/workflows/make-doc.sh

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-
-set -eu
-
-DEST="${GITHUB_REF#refs/*/}"
-echo "Uploading docs to https://tweaked.cc/$DEST"
-
-# Setup ssh key
-mkdir -p "$HOME/.ssh/"
-echo "$SSH_KEY" > "$HOME/.ssh/key"
-chmod 600 "$HOME/.ssh/key"
-
-# And upload
-rsync -avc -e "ssh -i $HOME/.ssh/key -o StrictHostKeyChecking=no -p $SSH_PORT" \
-      "$GITHUB_WORKSPACE/projects/web/build/site/" \
-      "$SSH_USER@$SSH_HOST:/$DEST"
-rsync -avc -e "ssh -i $HOME/.ssh/key -o StrictHostKeyChecking=no -p $SSH_PORT" \
-      "$GITHUB_WORKSPACE/projects/common-api/build/docs/javadoc/" \
-      "$SSH_USER@$SSH_HOST:/$DEST/javadoc"

.github/workflows/make-doc.yml

@@ -11,30 +11,25 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Clone repository
+    - name: 📥 Clone repository
       uses: actions/checkout@v4
 
-    - name: Set up Java
+    - name: 📥 Set up Java
       uses: actions/setup-java@v4
       with:
         java-version: 21
         distribution: 'temurin'
 
-    - name: Setup Gradle
+    - name: 📥 Setup Gradle
       uses: gradle/actions/setup-gradle@v3
       with:
         cache-read-only: ${{ !startsWith(github.ref, 'refs/heads/mc-') }}
 
-    - name: Build with Gradle
-      run: ./gradlew compileJava --no-daemon || ./gradlew compileJava --no-daemon
+    - name: ⚒️ Generate documentation
+      run: ./gradlew docWebsite --no-daemon
 
-    - name: Generate documentation
-      run: ./gradlew docWebsite :common-api:javadoc  --no-daemon
-
-    - name: Upload documentation
-      run: .github/workflows/make-doc.sh 2> /dev/null
-      env:
-        SSH_KEY:  ${{ secrets.SSH_KEY  }}
-        SSH_USER: ${{ secrets.SSH_USER }}
-        SSH_HOST: ${{ secrets.SSH_HOST }}
-        SSH_PORT: ${{ secrets.SSH_PORT }}
+    - name: 📤 Upload Jar
+      uses: actions/upload-artifact@v4
+      with:
+        name: Documentation
+        path: ./projects/web/build/site/

doc/index.md

@@ -4,7 +4,14 @@ SPDX-FileCopyrightText: 2020 The CC: Tweaked Developers
 SPDX-License-Identifier: MPL-2.0
 -->
 
-# ![CC: Tweaked](logo.png)
+<h1>
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="logo-darkmode.png">
+        <source media="(prefers-color-scheme: light)" srcset="logo.png">
+        <img alt="CC: Tweaked" src="logo.png">
+    </picture>
+</h1>
+
 CC: Tweaked is a mod for Minecraft which adds programmable computers, turtles and more to the game. A fork of the
 much-beloved [ComputerCraft], it continues its legacy with improved performance and stability, along with a wealth of
 new features.
@@ -38,7 +45,7 @@ little daunting getting started. Thankfully, there's several fantastic tutorials
 
  - [Direwolf20's ComputerCraft tutorials](https://www.youtube.com/watch?v=wrUHUhfCY5A "ComputerCraft Tutorial Episode 1 - HELP! and Hello World")
  - [Sethbling's ComputerCraft series](https://www.youtube.com/watch?v=DSsx4VSe-Uk "Programming Tutorial with Minecraft Turtles -- Ep. 1: Intro to Turtles and If-Then-Else_End")
- - [Lyqyd's Computer Basics 1](http://www.computercraft.info/forums2/index.php?/topic/15033-computer-basics-i/ "Computer Basics I")
+ - [Lyqyd's Computer Basics 1](https://ccf.squiddev.cc/forums2/index.php?/topic/15033-computer-basics-i/ "Computer Basics I")
 
 Once you're a little more familiar with the mod, the sidebar and links below provide more detailed documentation on the
 various APIs and peripherals provided by the mod.

doc/mod-page.md

@@ -45,7 +45,7 @@ little daunting getting started. Thankfully, there's several fantastic tutorials
 
  - [Direwolf20's ComputerCraft tutorials](https://www.youtube.com/watch?v=wrUHUhfCY5A "ComputerCraft Tutorial Episode 1 - HELP! and Hello World")
  - [Sethbling's ComputerCraft series](https://www.youtube.com/watch?v=DSsx4VSe-Uk "Programming Tutorial with Minecraft Turtles -- Ep. 1: Intro to Turtles and If-Then-Else_End")
- - [Lyqyd's Computer Basics 1](http://www.computercraft.info/forums2/index.php?/topic/15033-computer-basics-i/ "Computer Basics I")
+ - [Lyqyd's Computer Basics 1](https://ccf.squiddev.cc/forums2/index.php?/topic/15033-computer-basics-i/ "Computer Basics I")
 
 Once you're a little more familiar with the mod, the [wiki](https://tweaked.cc/) provides more detailed documentation on the
 various APIs and peripherals provided by the mod.

doc/reference/breaking_changes.md

@@ -77,5 +77,5 @@ as documentation for breaking changes and "gotchas" one should look out for betw
    you can no longer type `turtle/excavate` to run `/rom/programs/turtle/excavate.lua`.
 
 [flattening]: https://minecraft.wiki/w/Java_Edition_1.13/Flattening
-[legal_data_pack]: https://minecraft.gamepedia.com/Tutorials/Creating_a_data_pack#Legal_characters
+[legal_data_pack]: https://minecraft.wiki/w/Tutorials/Creating_a_data_pack#Legal_characters
 [datapack-example]: https://github.com/cc-tweaked/datapack-example "An example datapack for CC: Tweaked"

gradle/libs.versions.toml

@@ -64,7 +64,7 @@ fabric-loom = "1.6.7"
 githubRelease = "2.5.2"
 gradleVersions = "0.50.0"
 ideaExt = "1.1.7"
-illuaminate = "0.1.0-71-g378d86e"
+illuaminate = "0.1.0-73-g43ee16c"
 lwjgl = "3.3.3"
 minotaur = "2.8.7"
 neoGradle = "7.0.116"

projects/common/src/main/java/dan200/computercraft/data/ItemModelProvider.java

@@ -36,13 +36,13 @@ public final class ItemModelProvider {
     }
 
     private static void registerPocketComputer(ItemModelGenerators generators, ResourceLocation id, boolean off) {
-        createFlatItem(generators, addSuffix(id, "_blinking"),
+        createFlatItem(generators, id.withSuffix("_blinking"),
             new ResourceLocation(ComputerCraftAPI.MOD_ID, "item/pocket_computer_blink"),
             id,
             new ResourceLocation(ComputerCraftAPI.MOD_ID, "item/pocket_computer_light")
         );
 
-        createFlatItem(generators, addSuffix(id, "_on"),
+        createFlatItem(generators, id.withSuffix("_on"),
             new ResourceLocation(ComputerCraftAPI.MOD_ID, "item/pocket_computer_on"),
             id,
             new ResourceLocation(ComputerCraftAPI.MOD_ID, "item/pocket_computer_light")
@@ -94,8 +94,4 @@ public final class ItemModelProvider {
         new ModelTemplate(Optional.of(new ResourceLocation("item/generated")), Optional.empty(), slots)
             .create(model, mapping, generators.output);
     }
-
-    private static ResourceLocation addSuffix(ResourceLocation location, String suffix) {
-        return new ResourceLocation(location.getNamespace(), location.getPath() + suffix);
-    }
 }

projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java

@@ -180,7 +180,7 @@ public class CommandAPI implements ILuaAPI {
      * blocks at once.
      * <p>
      * Blocks are traversed by ascending y level, followed by z and x - the returned
-     * table may be indexed using `x + z*width + y*depth*depth`.
+     * table may be indexed using `x + z*width + y*width*depth + 1`.
      *
      * @param minX      The start x coordinate of the range to query.
      * @param minY      The start y coordinate of the range to query.
@@ -194,6 +194,25 @@ public class CommandAPI implements ILuaAPI {
      * @throws LuaException If trying to get information about more than 4096 blocks.
      * @cc.since 1.76
      * @cc.changed 1.99 Added {@code dimension} argument.
+     *
+     * @cc.usage Print out all blocks in a cube around the computer.
+     *
+     * <pre>{@code
+     * -- Get a 3x3x3 cube around the computer
+     * local x, y, z = commands.getBlockPosition()
+     * local min_x, min_y, min_z, max_x, max_y, max_z = x - 1, y - 1, z - 1, x + 1, y + 1, z + 1
+     * local blocks = commands.getBlockInfos(min_x, min_y, min_z, max_x, max_y, max_z)
+     *
+     * -- Then loop over all blocks and print them out.
+     * local width, height, depth = max_x - min_x + 1, max_y - min_y + 1, max_z - min_z + 1
+     * for x = min_x, max_x do
+     *   for y = min_y, max_y do
+     *     for z = min_z, max_z do
+     *       print(("%d, %d %d => %s"):format(x, y, z, blocks[(x - min_x) + (z - min_z) * width + (y - min_y) * width * depth + 1].name))
+     *     end
+     *   end
+     * end
+     * }</pre>
      */
     @LuaFunction(mainThread = true)
     public final List<Map<?, ?>> getBlockInfos(int minX, int minY, int minZ, int maxX, int maxY, int maxZ, Optional<String> dimension) throws LuaException {

projects/common/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java

@@ -129,7 +129,8 @@ public class DiskDrivePeripheral implements IPeripheral {
     @LuaFunction
     @Nullable
     public final Object getAudioTitle() {
-        return diskDrive.getMedia().getAudioTitle();
+        var stack = diskDrive.getMedia();
+        return stack.media() != null ? stack.getAudioTitle() : false;
     }
 
     /**

projects/common/src/main/resources/assets/computercraft/lang/de_de.json

@@ -130,5 +130,18 @@
     "upgrade.minecraft.diamond_hoe.adjective": "Ackerbau",
     "upgrade.minecraft.diamond_pickaxe.adjective": "Bergbau",
     "upgrade.minecraft.diamond_shovel.adjective": "Graben",
-    "upgrade.minecraft.diamond_sword.adjective": "Nahkampf"
+    "upgrade.minecraft.diamond_sword.adjective": "Nahkampf",
+    "argument.computercraft.computer.id": "Computer ID",
+    "argument.computercraft.computer.instance": "einzigartige Instanz ID",
+    "argument.computercraft.computer.label": "Computer name",
+    "argument.computercraft.unknown_computer_family": "Unbekannte computer familie '%s'",
+    "gui.computercraft.config.floppy_space_limit.tooltip": "Die maximale Dateisystem Größe von Disketten (in bytes).",
+    "gui.computercraft.config.http.bandwidth": "Bandbreite",
+    "gui.computercraft.config.http.bandwidth.global_upload": "Globales upload limit",
+    "gui.computercraft.config.http.bandwidth.global_download.tooltip": "Die maximale Geschwindigkeit aller Computer in bytes/s mit der Heruntergeladen werden kann.\nBereich: > 1",
+    "gui.computercraft.config.http.bandwidth.global_download": "Globales download limit",
+    "gui.computercraft.config.http.bandwidth.tooltip": "Limitiert die Bandbreite der Computer.",
+    "argument.computercraft.computer.family": "Computer familie",
+    "gui.computercraft.config.execution.max_main_global_time.tooltip": "Die maximale Zeit in millisekunden, in der Aufgaben ausgeführt werden.\nAnmerkung: Diese Zeit wird höchstwarscheinlich überschritten und dient nur als ungefähre Grenze.\nLimit: > 1",
+    "gui.computercraft.config.http.bandwidth.global_upload.tooltip": "Die maximale Hochladungs Geschwindigkeit aller Computer in bytes/s.\nBereich: > 1"
 }

projects/common/src/main/resources/assets/computercraft/lang/zh_cn.json

@@ -102,7 +102,7 @@
     "item.computercraft.pocket_computer_normal.upgraded": "%s手提计算机",
     "item.computercraft.printed_book": "打印书",
     "item.computercraft.printed_page": "打印纸",
-    "item.computercraft.printed_pages": "打印纸",
+    "item.computercraft.printed_pages": "打印纸簇",
     "item.computercraft.treasure_disk": "软盘",
     "itemGroup.computercraft": "ComputerCraft",
     "tracking_field.computercraft.fs.name": "文件系统操作",
@@ -120,5 +120,41 @@
     "upgrade.minecraft.diamond_hoe.adjective": "耕种",
     "upgrade.minecraft.diamond_pickaxe.adjective": "采掘",
     "upgrade.minecraft.diamond_shovel.adjective": "挖掘",
-    "upgrade.minecraft.diamond_sword.adjective": "战斗"
+    "upgrade.minecraft.diamond_sword.adjective": "战斗",
+    "argument.computercraft.computer.instance": "唯一实例ID",
+    "commands.computercraft.dump.open_path": "查看该电脑的文件",
+    "gui.computercraft.config.command_require_creative": "命令电脑需要创造模式",
+    "gui.computercraft.config.command_require_creative.tooltip": "玩家需要处于创造模式并为管理员才能与命令计算机交互。\n这是原版命令方块的默认行为。",
+    "gui.computercraft.config.http.bandwidth": "带宽",
+    "gui.computercraft.config.http.bandwidth.global_download.tooltip": "每秒钟可以下载的字节数. 所有电脑共享该设置 (bytes/s).\n范围: > 1",
+    "gui.computercraft.config.http.proxy.type.tooltip": "代理使用的协议.\n允许: HTTP, HTTPS, SOCKS4, SOCKS5",
+    "argument.computercraft.computer.id": "电脑ID",
+    "argument.computercraft.computer.distance": "实体距离",
+    "argument.computercraft.computer.family": "电脑类别",
+    "argument.computercraft.computer.label": "电脑标签",
+    "argument.computercraft.unknown_computer_family": "未知电脑类别 '%s'",
+    "commands.computercraft.help.desc": "显示该帮助信息",
+    "gui.computercraft.config.computer_space_limit.tooltip": "计算机和海龟的磁盘空间限制，以字节为单位。",
+    "gui.computercraft.config.disabled_generic_methods": "禁用的通用方法",
+    "gui.computercraft.config.http.bandwidth.global_upload": "全局上传限速",
+    "gui.computercraft.config.http.bandwidth.global_download": "全局下载限速",
+    "gui.computercraft.config.http.bandwidth.global_upload.tooltip": "每秒钟可以上传的字节数. 所有电脑共享该设置 (bytes/s).\n范围: > 1",
+    "gui.computercraft.config.http.bandwidth.tooltip": "限制电脑可以使用的带宽.",
+    "gui.computercraft.config.http.proxy": "代理",
+    "gui.computercraft.config.http.proxy.host": "主机名",
+    "gui.computercraft.config.http.proxy.host.tooltip": "代理服务器的主机名或IP地址.",
+    "gui.computercraft.config.http.proxy.port": "端口",
+    "gui.computercraft.config.http.proxy.port.tooltip": "代理服务器的端口.\n范围: 1 ~ 65536",
+    "gui.computercraft.config.http.proxy.type": "代理类型",
+    "gui.computercraft.config.http.rules": "允许/阻止规则",
+    "gui.computercraft.config.http.tooltip": "控制HTTP API",
+    "tracking_field.computercraft.java_allocation.name": "Java分配",
+    "tracking_field.computercraft.max": "%s (最大)",
+    "tracking_field.computercraft.server_tasks.name": "服务器任务",
+    "tag.item.computercraft.turtle": "海龟",
+    "tag.item.computercraft.wired_modem": "有线调制解调器",
+    "tracking_field.computercraft.avg": "%s (平均)",
+    "tracking_field.computercraft.computer_tasks.name": "任务",
+    "tracking_field.computercraft.count": "%s (计数)",
+    "tracking_field.computercraft.http_requests.name": "HTTP请求"
 }

projects/common/src/testMod/kotlin/dan200/computercraft/gametest/Disk_Drive_Test.kt

@@ -8,6 +8,7 @@ import dan200.computercraft.core.apis.FSAPI
 import dan200.computercraft.gametest.api.*
 import dan200.computercraft.shared.ModRegistry
 import dan200.computercraft.shared.peripheral.diskdrive.DiskDriveBlock
+import dan200.computercraft.shared.peripheral.diskdrive.DiskDrivePeripheral
 import dan200.computercraft.shared.peripheral.diskdrive.DiskDriveState
 import dan200.computercraft.shared.util.DataComponentUtil
 import dan200.computercraft.test.core.assertArrayEquals
@@ -42,6 +43,17 @@ class Disk_Drive_Test {
         }
     }
 
+    /**
+     * [DiskDrivePeripheral] returns `false` when the item is not a disk (or is absent).
+     */
+    @GameTest
+    fun Audio_title_when_empty(helper: GameTestHelper) = helper.sequence {
+        thenOnComputer {
+            callPeripheral("right", "getAudioTitle")
+                .assertArrayEquals(false, message = "Correct audio title")
+        }
+    }
+
     @GameTest
     fun Ejects_disk(helper: GameTestHelper) = helper.sequence {
         val stackAt = BlockPos(2, 2, 2)

projects/common/src/testMod/resources/data/cctest/structures/disk_drive_test.audio_title_when_empty.snbt

@@ -0,0 +1,40 @@
+{
+    DataVersion: 2730,
+    size: [3, 3, 3],
+    data: [
+        {pos: [0, 0, 0], state: "minecraft:polished_andesite"},
+        {pos: [0, 0, 1], state: "minecraft:polished_andesite"},
+        {pos: [0, 0, 2], state: "minecraft:polished_andesite"},
+        {pos: [1, 0, 0], state: "minecraft:polished_andesite"},
+        {pos: [1, 0, 1], state: "minecraft:polished_andesite"},
+        {pos: [1, 0, 2], state: "minecraft:polished_andesite"},
+        {pos: [2, 0, 0], state: "minecraft:polished_andesite"},
+        {pos: [2, 0, 1], state: "minecraft:polished_andesite"},
+        {pos: [2, 0, 2], state: "minecraft:polished_andesite"},
+        {pos: [0, 1, 0], state: "minecraft:air"},
+        {pos: [0, 1, 1], state: "computercraft:disk_drive{facing:north,state:full}", nbt: {id: "computercraft:disk_drive"}},
+        {pos: [0, 1, 2], state: "minecraft:air"},
+        {pos: [1, 1, 0], state: "minecraft:air"},
+        {pos: [1, 1, 1], state: "computercraft:computer_advanced{facing:north,state:blinking}", nbt: {ComputerId: 1, Label: "disk_drive_test.audio_title_when_empty", On: 1b, id: "computercraft:computer_advanced"}},
+        {pos: [1, 1, 2], state: "minecraft:air"},
+        {pos: [2, 1, 0], state: "minecraft:air"},
+        {pos: [2, 1, 1], state: "minecraft:air"},
+        {pos: [2, 1, 2], state: "minecraft:air"},
+        {pos: [0, 2, 0], state: "minecraft:air"},
+        {pos: [0, 2, 1], state: "minecraft:air"},
+        {pos: [0, 2, 2], state: "minecraft:air"},
+        {pos: [1, 2, 0], state: "minecraft:air"},
+        {pos: [1, 2, 1], state: "minecraft:air"},
+        {pos: [1, 2, 2], state: "minecraft:air"},
+        {pos: [2, 2, 0], state: "minecraft:air"},
+        {pos: [2, 2, 1], state: "minecraft:air"},
+        {pos: [2, 2, 2], state: "minecraft:air"}
+    ],
+    entities: [],
+    palette: [
+        "minecraft:polished_andesite",
+        "minecraft:air",
+        "computercraft:disk_drive{facing:north,state:full}",
+        "computercraft:computer_advanced{facing:north,state:blinking}"
+    ]
+}

projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua

@@ -23,7 +23,7 @@ just the same. For example, you might build a GPS cluster according to [this
 tutorial][1], using z to account for height, or you might use y to account for
 height in the way that Minecraft's debug screen displays.
 
-[1]: http://www.computercraft.info/forums2/index.php?/topic/3088-how-to-guide-gps-global-position-system/
+[1]: https://ccf.squiddev.cc/forums2/index.php?/topic/3088-how-to-guide-gps-global-position-system/
 
 @module gps
 @since 1.31

projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua

@@ -284,6 +284,23 @@ function errors.wrong_ne(start_pos, end_pos)
     }
 end
 
+--[[- `!` was used instead of `not`.
+
+@tparam number start_pos The start position of the token.
+@tparam number end_pos The end position of the token.
+@return The resulting parse error.
+]]
+function errors.wrong_not(start_pos, end_pos)
+    expect(1, start_pos, "number")
+    expect(2, end_pos, "number")
+
+    return {
+        "Unexpected character.",
+        annotate(start_pos, end_pos),
+        "Tip: Replace this with " .. code("not") .. " to negate a boolean.",
+    }
+end
+
 --[[- An unexpected character was used.
 
 @tparam number pos The position of this character.

projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua

@@ -327,6 +327,9 @@ local function lex_token(context, str, pos)
             elseif contents == "!=" or contents == "<>" then
                 context.report(errors.wrong_ne, pos, end_pos)
                 return tokens.NE, end_pos
+            elseif contents == "!" then
+                context.report(errors.wrong_not, pos, end_pos)
+                return tokens.NOT, end_pos
             end
         end
 

projects/core/src/test/resources/test-rom/spec/modules/cc/internal/syntax/lexer_spec.md

@@ -265,6 +265,7 @@ if a != b then end
 if a ~= b then end
 if a && b then end
 if a || b then end
+if ! a then end
 ```
 
 ```txt
@@ -307,6 +308,16 @@ Tip: Replace this with or to check if either value is true.
 4:9-4:9 IDENT b
 4:11-4:14 THEN then
 4:16-4:18 END end
+5:1-5:2 IF if
+Unexpected character.
+   |
+ 5 | if ! a then end
+   |    ^
+Tip: Replace this with not to negate a boolean.
+5:4-5:4 NOT !
+5:6-5:6 IDENT a
+5:8-5:11 THEN then
+5:13-5:15 END end
 ```
 
 For entirely unknown glyphs we should just give up and return an `ERROR` token.

projects/web/build.gradle.kts

@@ -145,6 +145,8 @@ val docWebsite by tasks.registering(Copy::class) {
     from(illuaminateDocs) { exclude("**/*.html") }
     // And item/block images from the data export
     from(file("src/htmlTransform/export/items")) { into("images/items") }
+    // Add the common-api (and core-api) javadoc
+    from(project(":common-api").tasks.named("javadoc")) { into("javadoc") }
 
     into(layout.buildDirectory.dir("site"))
 }