We are going to build our GPS constellation as shown in the image above. You will need 4 computers and either 4 wireless
modems or 4 ender modems. Try not to mix ender and wireless modems together as you might get some odd behavior when your
requesting computers are out of range.
-:::tip Ender modems vs wireless modems
-Ender modems have a very large range, which makes them very useful for setting up GPS hosts. If you do this then you
-will likely only need one GPS constellation for the whole dimension (such as the Overworld or Nether).
-
-If you do use wireless modems then you may find that you need multiple GPS constellations to cover your needs.
-
-A computer needs a wireless or ender modem and to be in range of a GPS constellation that is in the same dimension as it
-to use the GPS API. The reason for this is that ComputerCraft mimics real-life GPS by making use of the distance
-parameter of @{modem_message|modem messages} and some maths.
-:::
+> [Ender modems vs wireless modems][!TIP]
+> Ender modems have a very large range, which makes them very useful for setting up GPS hosts. If you do this then you
+> will likely only need one GPS constellation for the whole dimension (such as the Overworld or Nether).
+>
+> If you do use wireless modems then you may find that you need multiple GPS constellations to cover your needs.
+>
+> A computer needs a wireless or ender modem and to be in range of a GPS constellation that is in the same dimension as
+> it to use the GPS API. The reason for this is that ComputerCraft mimics real-life GPS by making use of the distance
+> parameter of [modem messages][`modem_message`] and some maths.
Locate where you want to place your GPS constellation. You will need an area at least 6 blocks high, 6 blocks wide, and
6 blocks deep (6x6x6). If you are using wireless modems then you may want to build your constellation as high as you can
@@ -79,18 +78,16 @@ To hide Minecraft's debug screen, press F3 again.
Create similar startup files for the other computers in your constellation, making sure to input the each computer's own
coordinates.
-:::caution Modem messages come from the computer's position, not the modem's
-Wireless modems transmit from the block that they are attached to *not* the block space that they occupy, the
-coordinates that you input into your GPS host should be the position of the computer and not the position of the modem.
-:::
+> [Modem messages come from the computer's position, not the modem's][!WARNING]
+> Wireless modems transmit from the block that they are attached to *not* the block space that they occupy, the
+> coordinates that you input into your GPS host should be the position of the computer and not the position of the modem.
Congratulations, your constellation is now fully set up! You can test it by placing another computer close by, placing a
-wireless modem on it, and running the `gps locate` program (or calling the @{gps.locate} function).
+wireless modem on it, and running the `gps locate` program (or calling the [`gps.locate`] function).
-:::info Why use Minecraft's coordinates?
-CC doesn't care if you use Minecraft's coordinate system, so long as all of the GPS hosts with overlapping ranges use
-the same reference point (requesting computers will get confused if hosts have different reference points). However,
-using MC's coordinate system does provide a nice standard to adopt server-wide. It also is consistent with how command
-computers get their location, they use MC's command system to get their block which returns that in MC's coordinate
-system.
-:::
+> [Why use Minecraft's coordinates?][!INFO]
+> CC doesn't care if you use Minecraft's coordinate system, so long as all of the GPS hosts with overlapping ranges use
+> the same reference point (requesting computers will get confused if hosts have different reference points). However,
+> using MC's coordinate system does provide a nice standard to adopt server-wide. It also is consistent with how command
+> computers get their location, they use MC's command system to get their block which returns that in MC's coordinate
+> system.
diff --git a/doc/guides/speaker_audio.md b/doc/guides/speaker_audio.md
index 1ced4fff1..9ff4779b8 100644
--- a/doc/guides/speaker_audio.md
+++ b/doc/guides/speaker_audio.md
@@ -11,7 +11,7 @@ SPDX-License-Identifier: MPL-2.0
-->
# Playing audio with speakers
-CC: Tweaked's speaker peripheral provides a powerful way to play any audio you like with the @{speaker.playAudio}
+CC: Tweaked's speaker peripheral provides a powerful way to play any audio you like with the [`speaker.playAudio`]
method. However, for people unfamiliar with digital audio, it's not the most intuitive thing to use. This guide provides
an introduction to digital audio, demonstrates how to play music with CC: Tweaked's speakers, and then briefly discusses
the more complex topic of audio processing.
@@ -60,7 +60,7 @@ sine waves (and why wouldn't you?), you'd need a table with almost 3 _million_.
up very quickly, and these tables take up more and more memory.
Instead of building our entire song (well, sine wave) in one go, we can produce it in small batches, each of which get
-passed off to @{speaker.playAudio} when the time is right. This allows us to build a _stream_ of audio, where we read
+passed off to [`speaker.playAudio`] when the time is right. This allows us to build a _stream_ of audio, where we read
chunks of audio one at a time (either from a file or a tone generator like above), do some optional processing to each
one, and then play them.
@@ -84,15 +84,15 @@ end
```
It looks pretty similar to before, aside from we've wrapped the generation and playing code in a while loop, and added a
-rather odd loop with @{speaker.playAudio} and @{os.pullEvent}.
+rather odd loop with [`speaker.playAudio`] and [`os.pullEvent`].
-Let's talk about this loop, why do we need to keep calling @{speaker.playAudio}? Remember that what we're trying to do
+Let's talk about this loop, why do we need to keep calling [`speaker.playAudio`]? Remember that what we're trying to do
here is avoid keeping too much audio in memory at once. However, if we're generating audio quicker than the speakers can
play it, we're not helping at all - all this audio is still hanging around waiting to be played!
In order to avoid this, the speaker rejects any new chunks of audio if its backlog is too large. When this happens,
-@{speaker.playAudio} returns false. Once enough audio has played, and the backlog has been reduced, a
-@{speaker_audio_empty} event is queued, and we can try to play our chunk once more.
+[`speaker.playAudio`] returns false. Once enough audio has played, and the backlog has been reduced, a
+[`speaker_audio_empty`] event is queued, and we can try to play our chunk once more.
## Storing audio
PCM is a fantastic way of representing audio when we want to manipulate it, but it's not very efficient when we want to
@@ -106,7 +106,7 @@ computer. Instead, we need something much simpler.
DFPWM (Dynamic Filter Pulse Width Modulation) is the de facto standard audio format of the ComputerCraft (and
OpenComputers) world. Originally popularised by the addon mod [Computronics], CC:T now has built-in support for it with
-the @{cc.audio.dfpwm} module. This allows you to read DFPWM files from disk, decode them to PCM, and then play them
+the [`cc.audio.dfpwm`] module. This allows you to read DFPWM files from disk, decode them to PCM, and then play them
using the speaker.
Let's dive in with an example, and we'll explain things afterwards:
@@ -125,16 +125,16 @@ for chunk in io.lines("data/example.dfpwm", 16 * 1024) do
end
```
-Once again, we see the @{speaker.playAudio}/@{speaker_audio_empty} loop. However, the rest of the program is a little
+Once again, we see the [`speaker.playAudio`]/[`speaker_audio_empty`] loop. However, the rest of the program is a little
different.
-First, we require the dfpwm module and call @{cc.audio.dfpwm.make_decoder} to construct a new decoder. This decoder
+First, we require the dfpwm module and call [`cc.audio.dfpwm.make_decoder`] to construct a new decoder. This decoder
accepts blocks of DFPWM data and converts it to a list of 8-bit amplitudes, which we can then play with our speaker.
-As mentioned above, @{speaker.playAudio} accepts at most 128×1024 samples in one go. DFPMW uses a single bit for each
+As mentioned above, [`speaker.playAudio`] accepts at most 128×1024 samples in one go. DFPMW uses a single bit for each
sample, which means we want to process our audio in chunks of 16×1024 bytes (16KiB). In order to do this, we use
-@{io.lines}, which provides a nice way to loop over chunks of a file. You can of course just use @{fs.open} and
-@{fs.BinaryReadHandle.read} if you prefer.
+[`io.lines`], which provides a nice way to loop over chunks of a file. You can of course just use [`fs.open`] and
+[`fs.BinaryReadHandle.read`] if you prefer.
## Processing audio
As mentioned near the beginning of this guide, PCM audio is pretty easy to work with as it's just a list of amplitudes.
@@ -189,10 +189,9 @@ for chunk in io.lines("data/example.dfpwm", 16 * 1024) do
end
```
-:::note Confused?
-Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't
-cover. That said, don't be afraid to ask on [GitHub Discussions] or [IRC] either!
-:::
+> [Confused?][!NOTE]
+> Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't
+> cover. That said, don't be afraid to ask on [GitHub Discussions] or [IRC] either!
It's worth noting that the examples of audio processing we've mentioned here are about manipulating the _amplitude_ of
the wave. If you wanted to modify the _frequency_ (for instance, shifting the pitch), things get rather more complex.
diff --git a/doc/guides/using_require.md b/doc/guides/using_require.md
index 9e69cba65..ec50ab408 100644
--- a/doc/guides/using_require.md
+++ b/doc/guides/using_require.md
@@ -13,7 +13,7 @@ A library is a collection of useful functions and other definitions which is sto
might want to create a library because you have some functions which are used in multiple programs, or just to split
your program into multiple more modular files.
-Let's say we want to create a small library to make working with the @{term|terminal} a little easier. We'll provide two
+Let's say we want to create a small library to make working with the [terminal][`term`] a little easier. We'll provide two
functions: `reset`, which clears the terminal and sets the cursor to (1, 1), and `write_center`, which prints some text
in the middle of the screen.
@@ -48,32 +48,32 @@ more_term.write_center("Hello, world!")
When run, this'll clear the screen and print some text in the middle of the first line.
## require in depth
-While the previous section is a good introduction to how @{require} operates, there are a couple of remaining points
+While the previous section is a good introduction to how [`require`] operates, there are a couple of remaining points
which are worth mentioning for more advanced usage.
### Libraries can return anything
In our above example, we return a table containing the functions we want to expose. However, it's worth pointing out
-that you can return ''anything'' from your library - a table, a function or even just a string! @{require} treats them
+that you can return ''anything'' from your library - a table, a function or even just a string! [`require`] treats them
all the same, and just returns whatever your library provides.
### Module resolution and the package path
-In the above examples, we defined our library in a file, and @{require} read from it. While this is what you'll do most
-of the time, it is possible to make @{require} look elsewhere for your library, such as downloading from a website or
+In the above examples, we defined our library in a file, and [`require`] read from it. While this is what you'll do most
+of the time, it is possible to make [`require`] look elsewhere for your library, such as downloading from a website or
loading from an in-memory library store.
-As a result, the *module name* you pass to @{require} doesn't correspond to a file path. One common mistake is to load
+As a result, the *module name* you pass to [`require`] doesn't correspond to a file path. One common mistake is to load
code from a sub-directory using `require("folder/library")` or even `require("folder/library.lua")`, neither of which
will do quite what you expect.
-When loading libraries (also referred to as *modules*) from files, @{require} searches along the *@{package.path|module
-path}*. By default, this looks something like:
+When loading libraries (also referred to as *modules*) from files, [`require`] searches along the [*module
+path*][`package.path`]. By default, this looks something like:
* `?.lua`
* `?/init.lua`
* `/rom/modules/main/?.lua`
* etc...
-When you call `require("my_library")`, @{require} replaces the `?` in each element of the path with your module name, and
+When you call `require("my_library")`, [`require`] replaces the `?` in each element of the path with your module name, and
checks if the file exists. In this case, we'd look for `my_library.lua`, `my_library/init.lua`,
`/rom/modules/main/my_library.lua` and so on. Note that this works *relative to the current program*, so if your
program is actually called `folder/program`, then we'll look for `folder/my_library.lua`, etc...
@@ -86,4 +86,4 @@ before we start looking for the library.
There are several external resources which go into require in a little more detail:
- The [Lua Module tutorial](http://lua-users.org/wiki/ModulesTutorial) on the Lua wiki.
- - [Lua's manual section on @{require}](https://www.lua.org/manual/5.1/manual.html#pdf-require).
+ - [Lua's manual section on `require`](https://www.lua.org/manual/5.1/manual.html#pdf-require).
diff --git a/doc/index.md b/doc/index.md
index 1d807151d..efa1a28d4 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -15,13 +15,13 @@ CC: Tweaked can be installed from [CurseForge] or [Modrinth]. It runs on both [M
Controlled using the [Lua programming language][lua], CC: Tweaked's computers provides all the tools you need to start
writing code and automating your Minecraft world.
-{.big-image}
+
While computers are incredibly powerful, they're rather limited by their inability to move about. *Turtles* are the
solution here. They can move about the world, placing and breaking blocks, swinging a sword to protect you from zombies,
or whatever else you program them to!
-{.big-image}
+
Not all problems can be solved with a pickaxe though, and so CC: Tweaked also provides a bunch of additional peripherals
for your computers. You can play a tune with speakers, display text or images on a monitor, connect all your
@@ -30,7 +30,7 @@ computers together with modems, and much more.
Computers can now also interact with inventories such as chests, allowing you to build complex inventory and item
management systems.
-{.big-image}
+
## Getting Started
While ComputerCraft is lovely for both experienced programmers and for people who have never coded before, it can be a
diff --git a/doc/stub/global.lua b/doc/stub/global.lua
index 1065c1497..2d237f96f 100644
--- a/doc/stub/global.lua
+++ b/doc/stub/global.lua
@@ -13,22 +13,20 @@ include standard Lua functions.
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
+or the [parallel API][`parallel`], it will only pause execution of the current
thread, not the whole program.
-:::tip
-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.
-:::
+> [!TIP]
+> 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.
-:::caution
-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}.
-:::
+> [!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 [timers][`os.startTimer`],
+> or the [parallel API][`parallel`].
@tparam number time The number of seconds to sleep for, rounded up to the
nearest multiple of 0.05.
@@ -116,7 +114,7 @@ function read(replaceChar, history, completeFn, default) end
--- Stores the current ComputerCraft and Minecraft versions.
--
--- Outside of Minecraft (for instance, in an emulator) @{_HOST} will contain the
+-- Outside of Minecraft (for instance, in an emulator) [`_HOST`] will contain the
-- emulator's version instead.
--
-- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.
diff --git a/doc/stub/os.lua b/doc/stub/os.lua
index 48043cb67..a2b5f5e08 100644
--- a/doc/stub/os.lua
+++ b/doc/stub/os.lua
@@ -15,27 +15,27 @@ variables and functions exported by it will by available through the use of
@deprecated When possible it's best to avoid using this function. It pollutes
the global table and can mask errors.
-@{require} should be used to load libraries instead.
+[`require`] should be used to load libraries instead.
]]
function loadAPI(path) end
---- Unloads an API which was loaded by @{os.loadAPI}.
+--- 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.
-- @since 1.2
--- @deprecated See @{os.loadAPI} for why.
+-- @deprecated See [`os.loadAPI`] for why.
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
+This function [yields][`coroutine.yield`] 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"
+Unlike [`os.pullEventRaw`], it will stop the application upon a "terminate"
event, printing the error "Terminated".
@tparam[opt] string filter Event to filter for.
@@ -69,7 +69,7 @@ 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
+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
Ctrl+T is pressed.
@@ -89,7 +89,7 @@ the `terminate` event yourself - the program will not stop execution when
]]
function pullEventRaw(filter) end
---- Pauses execution for the specified number of seconds, alias of @{_G.sleep}.
+--- Pauses execution for the specified number of seconds, alias of [`_G.sleep`].
--
-- @tparam number time The number of seconds to sleep for, rounded up to the
-- nearest multiple of 0.05.
@@ -109,12 +109,12 @@ 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.
+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}.
+such as [`loadfile`].
@tparam table env The environment to run the program with.
@tparam string path The exact path of the program to run.
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index f41a50120..3e79aefc0 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -19,8 +19,8 @@ parchmentMc = "1.19.4"
asm = "9.3"
autoService = "1.0.1"
checkerFramework = "3.32.0"
-cobalt = "0.7.1"
-cobalt-next = "0.7.2" # Not a real version, used to constrain the version we accept.
+cobalt = "0.7.3"
+cobalt-next = "0.7.4" # Not a real version, used to constrain the version we accept.
fastutil = "8.5.9"
guava = "31.1-jre"
jetbrainsAnnotations = "24.0.1"
@@ -34,6 +34,7 @@ slf4j = "1.7.36"
# Minecraft mods
emi = "1.0.8+1.20.1"
+fabricPermissions = "0.3.20230723"
iris = "1.6.4+1.20"
jei = "15.2.0.22"
modmenu = "7.1.0"
@@ -49,7 +50,7 @@ jqwik = "1.7.2"
junit = "5.9.2"
# Build tools
-cctJavadoc = "1.7.0"
+cctJavadoc = "1.8.0"
checkstyle = "10.3.4"
curseForgeGradle = "1.0.14"
errorProne-core = "2.18.0"
@@ -58,7 +59,7 @@ fabric-loom = "1.3.7"
forgeGradle = "6.0.8"
githubRelease = "2.2.12"
ideaExt = "1.1.6"
-illuaminate = "0.1.0-28-ga7efd71"
+illuaminate = "0.1.0-40-g975cbc3"
librarian = "1.+"
minotaur = "2.+"
mixinGradle = "0.7.+"
@@ -93,6 +94,7 @@ slf4j = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
# Minecraft mods
fabric-api = { module = "net.fabricmc.fabric-api:fabric-api", version.ref = "fabric-api" }
fabric-loader = { module = "net.fabricmc:fabric-loader", version.ref = "fabric-loader" }
+fabricPermissions = { module = "me.lucko:fabric-permissions-api", version.ref = "fabricPermissions" }
emi = { module = "dev.emi:emi-xplat-mojmap", version.ref = "emi" }
iris = { module = "maven.modrinth:iris", version.ref = "iris" }
jei-api = { module = "mezz.jei:jei-1.20.1-common-api", version.ref = "jei" }
@@ -154,7 +156,7 @@ externalMods-common = ["jei-api", "nightConfig-core", "nightConfig-toml"]
externalMods-forge-compile = ["oculus", "jei-api"]
externalMods-forge-runtime = ["jei-forge"]
externalMods-fabric = ["nightConfig-core", "nightConfig-toml"]
-externalMods-fabric-compile = ["iris", "jei-api", "rei-api", "rei-builtin"]
+externalMods-fabric-compile = ["fabricPermissions", "iris", "jei-api", "rei-api", "rei-builtin"]
externalMods-fabric-runtime = ["jei-fabric", "modmenu"]
# Testing
diff --git a/illuaminate.sexp b/illuaminate.sexp
index 74b37f146..d033e3712 100644
--- a/illuaminate.sexp
+++ b/illuaminate.sexp
@@ -12,7 +12,6 @@
/projects/core/src/test/resources/test-rom
/projects/web/src/mount)
-
(doc
; Also defined in projects/web/build.gradle.kts
(destination /projects/web/build/illuaminate)
@@ -50,6 +49,8 @@
(at /
(linters
syntax:string-index
+ doc:docusaurus-admonition
+ doc:ldoc-reference
;; It'd be nice to avoid this, but right now there's a lot of instances of
;; it.
@@ -82,23 +83,19 @@
;; isn't smart enough.
sleep write printError read rs)))
-;; We disable the unused global linter in bios.lua and the APIs. In the future
-;; hopefully we'll get illuaminate to handle this.
+;; We disable the unused global linter in bios.lua, APIs and our documentation
+;; stubs docs. In the future hopefully we'll get illuaminate to handle this.
(at
- (/projects/core/src/main/resources/data/computercraft/lua/bios.lua
- /projects/core/src/main/resources/data/computercraft/lua/rom/apis/)
- (linters -var:unused-global)
- (lint (allow-toplevel-global true)))
-
-;; Silence some variable warnings in documentation stubs.
-(at (/doc/stub/ /projects/forge/build/docs/luaJavadoc/)
+ (/doc/stub/
+ /projects/core/src/main/resources/data/computercraft/lua/bios.lua
+ /projects/core/src/main/resources/data/computercraft/lua/rom/apis/
+ /projects/forge/build/docs/luaJavadoc/)
(linters -var:unused-global)
(lint (allow-toplevel-global true)))
;; Suppress warnings for currently undocumented modules.
(at
(; Lua APIs
- /projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua
/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua)
(linters -doc:undocumented -doc:undocumented-arg -doc:undocumented-return))
diff --git a/projects/common/src/client/java/dan200/computercraft/client/ClientRegistry.java b/projects/common/src/client/java/dan200/computercraft/client/ClientRegistry.java
index 5a5da7852..490c12d6a 100644
--- a/projects/common/src/client/java/dan200/computercraft/client/ClientRegistry.java
+++ b/projects/common/src/client/java/dan200/computercraft/client/ClientRegistry.java
@@ -21,6 +21,7 @@ import dan200.computercraft.shared.computer.inventory.AbstractComputerMenu;
import dan200.computercraft.shared.computer.inventory.ViewComputerMenu;
import dan200.computercraft.shared.media.items.DiskItem;
import dan200.computercraft.shared.media.items.TreasureDiskItem;
+import net.minecraft.client.Minecraft;
import net.minecraft.client.color.item.ItemColor;
import net.minecraft.client.gui.screens.MenuScreens;
import net.minecraft.client.multiplayer.ClientLevel;
@@ -30,6 +31,7 @@ import net.minecraft.client.renderer.blockentity.BlockEntityRenderers;
import net.minecraft.client.renderer.item.ClampedItemPropertyFunction;
import net.minecraft.client.renderer.item.ItemProperties;
import net.minecraft.resources.ResourceLocation;
+import net.minecraft.server.packs.resources.PreparableReloadListener;
import net.minecraft.server.packs.resources.ResourceProvider;
import net.minecraft.world.entity.LivingEntity;
import net.minecraft.world.item.Item;
@@ -107,6 +109,10 @@ public final class ClientRegistry {
for (var item : items) ItemProperties.register(item.get(), id, getter);
}
+ public static void registerReloadListeners(Consumer
+ * This batches all render calls together, though requires that all {@link TextureAtlasSprite}s are on the same sprite
+ * sheet.
+ */
+public class SpriteRenderer {
+ private final Matrix4f transform;
+ private final VertexConsumer builder;
+ private final int light;
+ private final int z;
+ private final int r, g, b;
+
+ public SpriteRenderer(Matrix4f transform, VertexConsumer builder, int z, int light, int r, int g, int b) {
+ this.transform = transform;
+ this.builder = builder;
+ this.z = z;
+ this.light = light;
+ this.r = r;
+ this.g = g;
+ this.b = b;
+ }
+
+ public static SpriteRenderer createForGui(GuiGraphics graphics, RenderType renderType) {
+ return new SpriteRenderer(
+ graphics.pose().last().pose(), graphics.bufferSource().getBuffer(renderType),
+ 0, RenderTypes.FULL_BRIGHT_LIGHTMAP, 255, 255, 255
+ );
+ }
+
+ /**
+ * Render a single sprite.
+ *
+ * @param sprite The texture to draw.
+ * @param x The x position of the rectangle we'll draw.
+ * @param y The x position of the rectangle we'll draw.
+ * @param width The width of the rectangle we'll draw.
+ * @param height The height of the rectangle we'll draw.
+ */
+ public void blit(TextureAtlasSprite sprite, int x, int y, int width, int height) {
+ blit(x, y, width, height, sprite.getU0(), sprite.getV0(), sprite.getU1(), sprite.getV1());
+ }
+
+ /**
+ * Render a horizontal 3-sliced texture (i.e. split into left, middle and right). Unlike {@link GuiGraphics#blitNineSliced},
+ * the middle texture is stretched rather than repeated.
+ *
+ * @param sprite The texture to draw.
+ * @param x The x position of the rectangle we'll draw.
+ * @param y The x position of the rectangle we'll draw.
+ * @param width The width of the rectangle we'll draw.
+ * @param height The height of the rectangle we'll draw.
+ * @param leftBorder The width of the left border.
+ * @param rightBorder The width of the right border.
+ * @param textureWidth The width of the whole texture.
+ */
+ public void blitHorizontalSliced(TextureAtlasSprite sprite, int x, int y, int width, int height, int leftBorder, int rightBorder, int textureWidth) {
+ // TODO(1.20.2)/TODO(1.21.0): Drive this from mcmeta files, like vanilla does.
+ if (width < leftBorder + rightBorder) throw new IllegalArgumentException("width is less than two borders");
+
+ var centerStart = SpriteRenderer.u(sprite, leftBorder, textureWidth);
+ var centerEnd = SpriteRenderer.u(sprite, textureWidth - rightBorder, textureWidth);
+
+ blit(x, y, leftBorder, height, sprite.getU0(), sprite.getV0(), centerStart, sprite.getV1());
+ blit(x + leftBorder, y, width - leftBorder - rightBorder, height, centerStart, sprite.getV0(), centerEnd, sprite.getV1());
+ blit(x + width - rightBorder, y, rightBorder, height, centerEnd, sprite.getV0(), sprite.getU1(), sprite.getV1());
+ }
+
+ /**
+ * Render a vertical 3-sliced texture (i.e. split into top, middle and bottom). Unlike {@link GuiGraphics#blitNineSliced},
+ * the middle texture is stretched rather than repeated.
+ *
+ * @param sprite The texture to draw.
+ * @param x The x position of the rectangle we'll draw.
+ * @param y The x position of the rectangle we'll draw.
+ * @param width The width of the rectangle we'll draw.
+ * @param height The height of the rectangle we'll draw.
+ * @param topBorder The height of the top border.
+ * @param bottomBorder The height of the bottom border.
+ * @param textureHeight The height of the whole texture.
+ */
+ public void blitVerticalSliced(TextureAtlasSprite sprite, int x, int y, int width, int height, int topBorder, int bottomBorder, int textureHeight) {
+ // TODO(1.20.2)/TODO(1.21.0): Drive this from mcmeta files, like vanilla does.
+ if (width < topBorder + bottomBorder) throw new IllegalArgumentException("height is less than two borders");
+
+ var centerStart = SpriteRenderer.v(sprite, topBorder, textureHeight);
+ var centerEnd = SpriteRenderer.v(sprite, textureHeight - bottomBorder, textureHeight);
+
+ blit(x, y, width, topBorder, sprite.getU0(), sprite.getV0(), sprite.getU1(), centerStart);
+ blit(x, y + topBorder, width, height - topBorder - bottomBorder, sprite.getU0(), centerStart, sprite.getU1(), centerEnd);
+ blit(x, y + height - bottomBorder, width, bottomBorder, sprite.getU0(), centerEnd, sprite.getU1(), sprite.getV1());
+ }
+
+ /**
+ * The low-level blit function, used to render a portion of the sprite sheet. Unlike other functions, this takes uvs rather than a single sprite.
+ *
+ * @param x The x position of the rectangle we'll draw.
+ * @param y The x position of the rectangle we'll draw.
+ * @param width The width of the rectangle we'll draw.
+ * @param height The height of the rectangle we'll draw.
+ * @param u0 The first U coordinate.
+ * @param v0 The first V coordinate.
+ * @param u1 The second U coordinate.
+ * @param v1 The second V coordinate.
+ */
+ public void blit(
+ int x, int y, int width, int height, float u0, float v0, float u1, float v1) {
+ builder.vertex(transform, x, y + height, z).color(r, g, b, 255).uv(u0, v1).uv2(light).endVertex();
+ builder.vertex(transform, x + width, y + height, z).color(r, g, b, 255).uv(u1, v1).uv2(light).endVertex();
+ builder.vertex(transform, x + width, y, z).color(r, g, b, 255).uv(u1, v0).uv2(light).endVertex();
+ builder.vertex(transform, x, y, z).color(r, g, b, 255).uv(u0, v0).uv2(light).endVertex();
+ }
+
+ public static float u(TextureAtlasSprite sprite, int x, int width) {
+ return sprite.getU((double) x / width * 16);
+ }
+
+ public static float v(TextureAtlasSprite sprite, int y, int height) {
+ return sprite.getV((double) y / height * 16);
+ }
+}
diff --git a/projects/common/src/client/java/dan200/computercraft/data/client/ClientDataProviders.java b/projects/common/src/client/java/dan200/computercraft/data/client/ClientDataProviders.java
index 61d4dd6cf..76891e250 100644
--- a/projects/common/src/client/java/dan200/computercraft/data/client/ClientDataProviders.java
+++ b/projects/common/src/client/java/dan200/computercraft/data/client/ClientDataProviders.java
@@ -4,8 +4,10 @@
package dan200.computercraft.data.client;
+import dan200.computercraft.client.gui.GuiSprites;
import dan200.computercraft.data.DataProviders;
import dan200.computercraft.shared.turtle.inventory.UpgradeSlot;
+import net.minecraft.client.renderer.texture.atlas.SpriteSource;
import net.minecraft.client.renderer.texture.atlas.SpriteSources;
import net.minecraft.client.renderer.texture.atlas.sources.SingleFile;
import net.minecraft.resources.ResourceLocation;
@@ -13,6 +15,7 @@ import net.minecraft.server.packs.PackType;
import java.util.List;
import java.util.Optional;
+import java.util.stream.Stream;
/**
* A version of {@link DataProviders} which relies on client-side classes.
@@ -29,6 +32,17 @@ public final class ClientDataProviders {
new SingleFile(UpgradeSlot.LEFT_UPGRADE, Optional.empty()),
new SingleFile(UpgradeSlot.RIGHT_UPGRADE, Optional.empty())
));
+ out.accept(GuiSprites.SPRITE_SHEET, Stream.of(
+ // Buttons
+ GuiSprites.TURNED_OFF.textures(),
+ GuiSprites.TURNED_ON.textures(),
+ GuiSprites.TERMINATE.textures(),
+ // Computers
+ GuiSprites.COMPUTER_NORMAL.textures(),
+ GuiSprites.COMPUTER_ADVANCED.textures(),
+ GuiSprites.COMPUTER_COMMAND.textures(),
+ GuiSprites.COMPUTER_COLOUR.textures()
+ ).flatMap(x -> x).
- * This satisfies the property that for all sources {@code s}, {@code a.test(s) || b.test(s) == (a ∪ b).test(s)}.
- *
- * @param left The first user level to take the union of.
- * @param right The second user level to take the union of.
- * @return The union of two levels.
- */
- public static UserLevel union(UserLevel left, UserLevel right) {
- if (left == right) return left;
-
- // x ∪ ANYONE = ANYONE
- if (left == ANYONE || right == ANYONE) return ANYONE;
-
- // x ∪ OWNER = OWNER
- if (left == OWNER) return right;
- if (right == OWNER) return left;
-
- // At this point, we have x != y and x, y ∈ { OP, OWNER_OP }.
- return OWNER_OP;
+ public boolean test(ServerPlayer source) {
+ if (this == ANYONE) return true;
+ if (this == OWNER_OP && isOwner(source)) return true;
+ return source.hasPermissions(toLevel());
}
- private static boolean isOwner(CommandSourceStack source) {
+ public static boolean isOwner(CommandSourceStack source) {
var server = source.getServer();
- var sender = source.getEntity();
+ var player = source.getPlayer();
return server.isDedicatedServer()
? source.getEntity() == null && source.hasPermission(4) && source.getTextName().equals("Server")
- : sender instanceof Player player && server.isSingleplayerOwner(player.getGameProfile());
+ : player != null && server.isSingleplayerOwner(player.getGameProfile());
+ }
+
+ public static boolean isOwner(ServerPlayer player) {
+ var server = player.getServer();
+ return server != null && server.isSingleplayerOwner(player.getGameProfile());
}
}
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/command/builder/CommandBuilder.java b/projects/common/src/main/java/dan200/computercraft/shared/command/builder/CommandBuilder.java
index 2a395ff7b..a150b8c88 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/command/builder/CommandBuilder.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/command/builder/CommandBuilder.java
@@ -44,7 +44,8 @@ public class CommandBuilder
* Blocks are traversed by ascending y level, followed by z and x - the returned
@@ -225,7 +225,7 @@ public class CommandAPI implements ILuaAPI {
* Get some basic information about a block.
*
* The returned table contains the current name, metadata and block state (as
- * with @{turtle.inspect}). If there is a tile entity for that block, its NBT
+ * with [`turtle.inspect`]). If there is a tile entity for that block, its NBT
* will also be returned.
*
* @param x The x position of the block to query.
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/computer/terminal/TerminalState.java b/projects/common/src/main/java/dan200/computercraft/shared/computer/terminal/TerminalState.java
index ae9b3237c..19a554850 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/computer/terminal/TerminalState.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/computer/terminal/TerminalState.java
@@ -5,18 +5,10 @@
package dan200.computercraft.shared.computer.terminal;
import io.netty.buffer.ByteBuf;
-import io.netty.buffer.ByteBufInputStream;
-import io.netty.buffer.ByteBufOutputStream;
import io.netty.buffer.Unpooled;
import net.minecraft.network.FriendlyByteBuf;
import javax.annotation.Nullable;
-import java.io.IOException;
-import java.io.InputStream;
-import java.io.OutputStream;
-import java.io.UncheckedIOException;
-import java.util.zip.GZIPInputStream;
-import java.util.zip.GZIPOutputStream;
/**
* A snapshot of a terminal's state.
@@ -31,20 +23,10 @@ public class TerminalState {
public final int width;
public final int height;
- private final boolean compress;
-
@Nullable
private final ByteBuf buffer;
- private @Nullable ByteBuf compressed;
-
public TerminalState(@Nullable NetworkedTerminal terminal) {
- this(terminal, true);
- }
-
- public TerminalState(@Nullable NetworkedTerminal terminal, boolean compress) {
- this.compress = compress;
-
if (terminal == null) {
colour = false;
width = height = 0;
@@ -61,14 +43,13 @@ public class TerminalState {
public TerminalState(FriendlyByteBuf buf) {
colour = buf.readBoolean();
- compress = buf.readBoolean();
if (buf.readBoolean()) {
width = buf.readVarInt();
height = buf.readVarInt();
var length = buf.readVarInt();
- buffer = readCompressed(buf, length, compress);
+ buffer = buf.readBytes(length);
} else {
width = height = 0;
buffer = null;
@@ -77,16 +58,13 @@ public class TerminalState {
public void write(FriendlyByteBuf buf) {
buf.writeBoolean(colour);
- buf.writeBoolean(compress);
buf.writeBoolean(buffer != null);
if (buffer != null) {
buf.writeVarInt(width);
buf.writeVarInt(height);
-
- var sendBuffer = getCompressed();
- buf.writeVarInt(sendBuffer.readableBytes());
- buf.writeBytes(sendBuffer, sendBuffer.readerIndex(), sendBuffer.readableBytes());
+ buf.writeVarInt(buffer.readableBytes());
+ buf.writeBytes(buffer, buffer.readerIndex(), buffer.readableBytes());
}
}
@@ -110,40 +88,4 @@ public class TerminalState {
terminal.read(new FriendlyByteBuf(buffer));
return terminal;
}
-
- private ByteBuf getCompressed() {
- if (buffer == null) throw new NullPointerException("buffer");
- if (!compress) return buffer;
- if (compressed != null) return compressed;
-
- var compressed = Unpooled.buffer();
- try (OutputStream stream = new GZIPOutputStream(new ByteBufOutputStream(compressed))) {
- stream.write(buffer.array(), buffer.arrayOffset(), buffer.readableBytes());
- } catch (IOException e) {
- throw new UncheckedIOException(e);
- }
-
- return this.compressed = compressed;
- }
-
- private static ByteBuf readCompressed(ByteBuf buf, int length, boolean compress) {
- if (compress) {
- var buffer = Unpooled.buffer();
- try (InputStream stream = new GZIPInputStream(new ByteBufInputStream(buf, length))) {
- var swap = new byte[8192];
- while (true) {
- var bytes = stream.read(swap);
- if (bytes == -1) break;
- buffer.writeBytes(swap, 0, bytes);
- }
- } catch (IOException e) {
- throw new UncheckedIOException(e);
- }
- return buffer;
- } else {
- var buffer = Unpooled.buffer(length);
- buf.readBytes(buffer, length);
- return buffer;
- }
- }
}
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/config/AddressRuleConfig.java b/projects/common/src/main/java/dan200/computercraft/shared/config/AddressRuleConfig.java
index c063569a7..5ee6ce442 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/config/AddressRuleConfig.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/config/AddressRuleConfig.java
@@ -26,6 +26,10 @@ class AddressRuleConfig {
private static final AddressRule REJECT_ALL = AddressRule.parse("*", OptionalInt.empty(), Action.DENY.toPartial());
+ private static final Set
+ * This acts as an abstraction layer over permission systems such Forge's built-in permissions API, or Fabric's
+ * unofficial fabric-permissions-api-v0.
+ *
+ * This behaves similarly to {@link RegistrationHelper} (aka Forge's deferred registry), in that you {@linkplain #create()
+ * create a registry}, {@linkplain #registerCommand(String, UserLevel) add nodes to it} and then finally {@linkplain
+ * #register()} all created nodes.
+ *
+ * @see dan200.computercraft.shared.ModRegistry.Permissions
+ */
+public abstract class PermissionRegistry {
+ private boolean frozen = false;
+
+ /**
+ * Register a permission node for a command. The registered node should be of the form {@code "command." + command}.
+ *
+ * @param command The name of the command. This should be one of the subcommands under the {@code /computercraft}
+ * subcommand, and not something general.
+ * @param fallback The default/fallback permission check.
+ * @return The resulting predicate which should be passed to {@link ArgumentBuilder#requires(Predicate)}.
+ * @see CommandComputerCraft
+ */
+ public abstract Predicate
- * :::tip
- * Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The
- * {@literal @}{rednet} API is built on top of modems, and provides a more user-friendly interface.
- * :::
+ * > [!TIP]
+ * > Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The
+ * > [`rednet`] API is built on top of modems, and provides a more user-friendly interface.
*
* ## Sending and receiving messages
* Modems operate on a series of channels, a bit like frequencies on a radio. Any modem can send a message on a
@@ -31,11 +31,11 @@ import java.util.Set;
* messages.
*
* Channels are represented as an integer between 0 and 65535 inclusive. These channels don't have any defined meaning,
- * though some APIs or programs will assign a meaning to them. For instance, the @{gps} module sends all its messages on
- * channel 65534 (@{gps.CHANNEL_GPS}), while @{rednet} uses channels equal to the computer's ID.
+ * though some APIs or programs will assign a meaning to them. For instance, the [`gps`] module sends all its messages on
+ * channel 65534 ([`gps.CHANNEL_GPS`]), while [`rednet`] uses channels equal to the computer's ID.
*
* - Sending messages is done with the {@link #transmit(int, int, Object)} message.
- * - Receiving messages is done by listening to the @{modem_message} event.
+ * - Receiving messages is done by listening to the [`modem_message`] event.
*
* ## Types of modem
* CC: Tweaked comes with three kinds of modem, with different capabilities.
@@ -85,7 +85,7 @@ import java.util.Set;
*/
public abstract class ModemPeripheral implements IPeripheral, PacketSender, PacketReceiver {
private @Nullable PacketNetwork network;
- private final Set
- * :::note
- * The channel does not need be open to send a message.
- * :::
+ * > [!NOTE]
+ * > The channel does not need be open to send a message.
*
* @param channel The channel to send messages on.
* @param replyChannel The channel that responses to this message should be sent on. This can be the same as
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
index a4956ac69..8e0a6f8bb 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
@@ -80,9 +80,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
* If this computer is attached to the network, it _will not_ be included in
* this list.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @return Remote peripheral names on the network.
@@ -96,9 +95,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
/**
* Determine if a peripheral is available on this wired network.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -113,9 +111,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
/**
* Get the type of a peripheral is available on this wired network.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -133,9 +130,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
/**
* Check a peripheral is of a particular type.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -154,9 +150,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
/**
* Get all available methods for the remote peripheral with the given name.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -175,9 +170,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
/**
* Call a method on a peripheral on this wired network.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param context The Lua context we're executing in.
@@ -205,9 +199,8 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements Wi
* may be used by other computers on the network to wrap this computer as a
* peripheral.
*
- * :::note
- * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
- * :::
+ * > [!NOTE]
+ * > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @return The current computer's name.
* @cc.treturn string|nil The current computer's name on the wired network.
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorBlockEntity.java b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorBlockEntity.java
index be2feee1e..3f89c17cd 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorBlockEntity.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorBlockEntity.java
@@ -25,8 +25,9 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.Nullable;
-import java.util.HashSet;
+import java.util.Collections;
import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Consumer;
public class MonitorBlockEntity extends BlockEntity {
@@ -46,7 +47,7 @@ public class MonitorBlockEntity extends BlockEntity {
private @Nullable ServerMonitor serverMonitor;
private @Nullable ClientMonitor clientMonitor;
private @Nullable MonitorPeripheral peripheral;
- private final Set
- * Monitors act as @{term.Redirect|terminal redirects} and so expose the same methods, as well as several additional
+ * Monitors act as [terminal redirects][`term.Redirect`] and so expose the same methods, as well as several additional
* ones, which are documented below.
*
* Like computers, monitors come in both normal (no colour) and advanced (colour) varieties.
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
index c68e4ad71..bf1075f2d 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
@@ -4,6 +4,7 @@
package dan200.computercraft.shared.peripheral.speaker;
+import com.google.errorprone.annotations.concurrent.GuardedBy;
import dan200.computercraft.api.lua.ILuaContext;
import dan200.computercraft.api.lua.LuaException;
import dan200.computercraft.api.lua.LuaFunction;
@@ -57,7 +58,7 @@ public abstract class SpeakerPeripheral implements IPeripheral {
public static final int SAMPLE_RATE = 48000;
private final UUID source = UUID.randomUUID();
- private final Set
* This accepts a list of audio samples as amplitudes between -128 and 127. These are stored in an internal buffer
* and played back at 48kHz. If this buffer is full, this function will return {@literal false}. You should wait for
- * a @{speaker_audio_empty} event before trying again.
+ * a [`speaker_audio_empty`] event before trying again.
*
- * :::note
- * The speaker only buffers a single call to {@link #playAudio} at once. This means if you try to play a small
- * number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible
- * (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or
- * computer is lagging.
- * :::
+ * > [!NOTE]
+ * > The speaker only buffers a single call to {@link #playAudio} at once. This means if you try to play a small
+ * > number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible
+ * > (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or
+ * > computer is lagging.
*
- * {@literal @}{speaker_audio} provides a more complete guide to using speakers
+ * [`speaker_audio`] provides a more complete guide to using speakers
*
* @param context The Lua context.
* @param audio The audio data to play.
@@ -291,7 +291,7 @@ public abstract class SpeakerPeripheral implements IPeripheral {
* @cc.tparam [opt] number volume The volume to play this audio at. If not given, defaults to the previous volume
* given to {@link #playAudio}.
* @cc.since 1.100
- * @cc.usage Read an audio file, decode it using @{cc.audio.dfpwm}, and play it using the speaker.
+ * @cc.usage Read an audio file, decode it using [`cc.audio.dfpwm`], and play it using the speaker.
*
*
- * {@literal @}{turtle.forward} and @{turtle.back} move the turtle in the direction it is facing, while @{turtle.up} and
- * {@literal @}{turtle.down} move it up and down (as one might expect!). In order to move left or right, you first need
- * to turn the turtle using @{turtle.turnLeft}/@{turtle.turnRight} and then move forward or backwards.
+ * [`turtle.forward`] and [`turtle.back`] move the turtle in the direction it is facing, while [`turtle.up`] and
+ * [`turtle.down`] move it up and down (as one might expect!). In order to move left or right, you first need
+ * to turn the turtle using [`turtle.turnLeft`]/[`turtle.turnRight`] and then move forward or backwards.
*
- * :::info
- * The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd move
- * a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
- * :::
+ * > [!INFO]
+ * > The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd
+ * > move a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
*
- * Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any @{turtle.refuel|fuel}, it
- * won't move, and the movement functions will return @{false}. If your turtle isn't going anywhere, the first thing to
+ * Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any [fuel][`turtle.refuel`], it
+ * won't move, and the movement functions will return [`false`]. If your turtle isn't going anywhere, the first thing to
* check is if you've fuelled your turtle.
*
- * :::tip Handling errors
- * Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a block
- * there. Instead of erroring, functions which can fail either return @{true} if they succeed, or @{false} and some
- * error message if they fail.
- *
- * Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
- * functions, or wrap them in @{assert} (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
- * so the program doesn't misbehave.
- * :::
+ * > [Handling errors][!TIP]
+ * > Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a
+ * > block there. Instead of erroring, functions which can fail either return [`true`] if they succeed, or [`false`] and
+ * > some error message if they fail.
+ * >
+ * > Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
+ * > functions, or wrap them in [`assert`] (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
+ * > so the program doesn't misbehave.
*
* ## Turtle upgrades
* While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles
- * can be upgraded with *tools* and @{peripheral|peripherals}. Turtles have two upgrade slots, one on the left and right
- * sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the @{turtle.equipLeft}/@{turtle.equipRight}
+ * can be upgraded with *tools* and [peripherals][`peripheral`]. Turtles have two upgrade slots, one on the left and right
+ * sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the [`turtle.equipLeft`]/[`turtle.equipRight`]
* functions.
*
- * Turtle tools allow you to break blocks (@{turtle.dig}) and attack entities (@{turtle.attack}). Some tools are more
+ * Turtle tools allow you to break blocks ([`turtle.dig`]) and attack entities ([`turtle.attack`]). Some tools are more
* suitable to a task than others. For instance, a diamond pickaxe can break every block, while a sword does more
* damage. Other tools have more niche use-cases, for instance hoes can til dirt.
*
- * Peripherals (such as the @{modem|wireless modem} or @{speaker}) can also be equipped as upgrades. These are then
+ * Peripherals (such as the [wireless modem][`modem`] or [`speaker`]) can also be equipped as upgrades. These are then
* accessible by accessing the `"left"` or `"right"` peripheral.
*
* [Turtle Graphics]: https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics"
@@ -290,7 +288,7 @@ public class TurtleAPI implements ILuaAPI {
}
/**
- * Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if
+ * Drop the currently selected stack into the inventory below the turtle, or as an item into the world if
* there is no inventory.
*
* @param count The number of items to drop. If not given, the entire stack will be dropped.
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/turtle/upgrades/TurtleToolSerialiser.java b/projects/common/src/main/java/dan200/computercraft/shared/turtle/upgrades/TurtleToolSerialiser.java
index 4d5f144db..e480b31f2 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/turtle/upgrades/TurtleToolSerialiser.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/turtle/upgrades/TurtleToolSerialiser.java
@@ -55,7 +55,7 @@ public final class TurtleToolSerialiser implements TurtleUpgradeSerialiser
- * :::note
- * All functions in the API work on absolute paths, and do not take the @{shell.dir|current directory} into account.
- * You can use @{shell.resolve} to convert a relative path into an absolute one.
- * :::
+ * > [!NOTE]
+ * > All functions in the API work on absolute paths, and do not take the [current directory][`shell.dir`] into account.
+ * > You can use [`shell.resolve`] to convert a relative path into an absolute one.
*
* ## Mounts
* While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For
@@ -333,7 +332,7 @@ public class FSAPI implements ILuaAPI {
*
* print(contents)
* }
- * As with @{os.sleep|sleep}, {@code timer} will automatically be rounded up
+ * As with [sleep][`os.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.
*
@@ -353,13 +353,12 @@ public class OSAPI implements ILuaAPI {
* * If called with {@code local}, returns the number of milliseconds since 1
* January 1970 in the server's local timezone.
*
- * :::info
- * The {@code ingame} time zone assumes that one Minecraft day consists of 86,400,000
- * milliseconds. Since one in-game day is much faster than a real day (20 minutes), this
- * will change quicker than real time - one real second is equal to 72000 in-game
- * milliseconds. If you wish to convert this value to real time, divide by 72000; to
- * convert to ticks (where a day is 24000 ticks), divide by 3600.
- * :::
+ * > [!INFO]
+ * > The {@code ingame} time zone assumes that one Minecraft day consists of 86,400,000
+ * > milliseconds. Since one in-game day is much faster than a real day (20 minutes), this
+ * > will change quicker than real time - one real second is equal to 72000 in-game
+ * > milliseconds. If you wish to convert this value to real time, divide by 72000; to
+ * > convert to ticks (where a day is 24000 ticks), divide by 3600.
*
* @param args The locale to get the milliseconds for. Defaults to {@code ingame} if not set.
* @return The milliseconds since the epoch depending on the selected locale.
diff --git a/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java b/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
index c25706a29..88bca96ab 100644
--- a/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
+++ b/projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
@@ -21,9 +21,9 @@ import java.util.List;
* strength of the redstone wired, from 0 to 15.
* - Bundled cables ({@link #setBundledOutput}/{@link #getBundledInput}): These interact with "bundled" cables, such
* as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
- * colour, with the first being @{colors.white} and the last @{colors.black}.
+ * colour, with the first being [`colors.white`] and the last [`colors.black`].
*
- * Whenever a redstone input changes, a @{event!redstone} event will be fired. This may be used instead of repeativly
+ * Whenever a redstone input changes, a [`event!redstone`] event will be fired. This may be used instead of repeativly
* polling.
*
* This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
@@ -192,7 +192,7 @@ public class RedstoneAPI implements ILuaAPI {
* @param side The side to test.
* @param mask The mask to test.
* @return If the colours are on.
- * @cc.usage Check if @{colors.white} and @{colors.black} are on above the computer.
+ * @cc.usage Check if [`colors.white`] and [`colors.black`] are on above the computer.
*
* ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you
- * can make @{colors.red} more red by setting its palette to #FF0000. This does now allow you to draw more
+ * can make [`colors.red`] more red by setting its palette to #FF0000. This does now allow you to draw more
* colours - you are still limited to 16 on the screen at one time - but you can change which colours are
* used.
*
@@ -280,7 +280,7 @@ public abstract class TermMethods {
* @cc.tparam number r The intensity of the red channel, between 0 and 1.
* @cc.tparam number g The intensity of the green channel, between 0 and 1.
* @cc.tparam number b The intensity of the blue channel, between 0 and 1.
- * @cc.usage Change the @{colors.red|red colour} from the default #CC4C4C to #FF0000.
+ * @cc.usage Change the [red colour][`colors.red`] from the default #CC4C4C to #FF0000.
* implements CommandNodeBuilder requires(Predicate predicate) {
- requires = requires == null ? predicate : requires.and(predicate);
+ if (requires != null) throw new IllegalStateException("Requires already set");
+ requires = predicate;
return this;
}
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/command/builder/HelpingArgumentBuilder.java b/projects/common/src/main/java/dan200/computercraft/shared/command/builder/HelpingArgumentBuilder.java
index 16c7811d2..1edf06554 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/command/builder/HelpingArgumentBuilder.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/command/builder/HelpingArgumentBuilder.java
@@ -10,7 +10,6 @@ import com.mojang.brigadier.builder.LiteralArgumentBuilder;
import com.mojang.brigadier.context.CommandContext;
import com.mojang.brigadier.tree.CommandNode;
import com.mojang.brigadier.tree.LiteralCommandNode;
-import dan200.computercraft.shared.command.UserLevel;
import net.minecraft.ChatFormatting;
import net.minecraft.commands.CommandSourceStack;
import net.minecraft.network.chat.ClickEvent;
@@ -31,6 +30,7 @@ import static dan200.computercraft.shared.command.text.ChatHelpers.coloured;
*/
public final class HelpingArgumentBuilder extends LiteralArgumentBuilder{@code
* local dfpwm = require("cc.audio.dfpwm")
diff --git a/projects/common/src/main/java/dan200/computercraft/shared/platform/RegistryWrappers.java b/projects/common/src/main/java/dan200/computercraft/shared/platform/RegistryWrappers.java
index 59460572e..76c289a5b 100644
--- a/projects/common/src/main/java/dan200/computercraft/shared/platform/RegistryWrappers.java
+++ b/projects/common/src/main/java/dan200/computercraft/shared/platform/RegistryWrappers.java
@@ -10,7 +10,6 @@ import net.minecraft.core.Registry;
import net.minecraft.core.registries.Registries;
import net.minecraft.network.FriendlyByteBuf;
import net.minecraft.resources.ResourceLocation;
-import net.minecraft.sounds.SoundEvent;
import net.minecraft.world.inventory.MenuType;
import net.minecraft.world.item.Item;
import net.minecraft.world.item.crafting.RecipeSerializer;
@@ -33,7 +32,6 @@ public final class RegistryWrappers {
public static final RegistryWrapper
- * @cc.usage Open a file and read all lines into a table. @{io.lines} offers an alternative way to do this.
+ * @cc.usage Open a file and read all lines into a table. [`io.lines`] offers an alternative way to do this.
* {@code
* local file = fs.open("/rom/motd.txt", "r")
* local lines = {}
diff --git a/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java b/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java
index 86b395e9b..4540acd50 100644
--- a/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java
+++ b/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java
@@ -146,7 +146,7 @@ public class OSAPI implements ILuaAPI {
* the timer fires, a {@code timer} event will be added to the queue with
* the ID returned from this function as the first parameter.
* {@code
* print(redstone.testBundledInput("top", colors.combine(colors.white, colors.black)))
* }
diff --git a/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java b/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java
index 07520827d..8c90d5aae 100644
--- a/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java
+++ b/projects/core/src/main/java/dan200/computercraft/core/apis/TermMethods.java
@@ -267,7 +267,7 @@ public abstract class TermMethods {
* Set the palette for a specific colour.
* {@code
* term.setPaletteColour(colors.red, 0xFF0000)
* term.setTextColour(colors.red)
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua
index 5bdbf9fd2..70ab61784 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua
@@ -3,20 +3,20 @@
-- SPDX-License-Identifier: LicenseRef-CCPL
--[[- Constants and functions for colour values, suitable for working with
-@{term} and @{redstone}.
+[`term`] and [`redstone`].
-This is useful in conjunction with @{redstone.setBundledOutput|Bundled Cables}
-from mods like Project Red, and @{term.setTextColour|colors on Advanced
-Computers and Advanced Monitors}.
+This is useful in conjunction with [Bundled Cables][`redstone.setBundledOutput`]
+from mods like Project Red, and [colors on Advanced Computers and Advanced
+Monitors][`term.setTextColour`].
-For the non-American English version just replace @{colors} with @{colours}.
+For the non-American English version just replace [`colors`] with [`colours`].
This alternative API is exactly the same, except the colours use British English
-(e.g. @{colors.gray} is spelt @{colours.grey}).
+(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}.
+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`.
@@ -140,67 +140,67 @@ i.e. `(red + green + blue) / 3`.
local expect = dofile("rom/modules/main/cc/expect.lua").expect
---- White: Written as `0` in paint files and @{term.blit}, has a default
+--- White: Written as `0` in paint files and [`term.blit`], has a default
-- terminal colour of #F0F0F0.
white = 0x1
---- Orange: Written as `1` in paint files and @{term.blit}, has a
+--- Orange: Written as `1` in paint files and [`term.blit`], has a
-- default terminal colour of #F2B233.
orange = 0x2
---- Magenta: Written as `2` in paint files and @{term.blit}, has a
+--- Magenta: Written as `2` in paint files and [`term.blit`], has a
-- default terminal colour of #E57FD8.
magenta = 0x4
---- Light blue: Written as `3` in paint files and @{term.blit}, has a
+--- Light blue: Written as `3` in paint files and [`term.blit`], has a
-- default terminal colour of #99B2F2.
lightBlue = 0x8
---- Yellow: Written as `4` in paint files and @{term.blit}, has a
+--- Yellow: Written as `4` in paint files and [`term.blit`], has a
-- default terminal colour of #DEDE6C.
yellow = 0x10
---- Lime: Written as `5` in paint files and @{term.blit}, has a default
+--- Lime: Written as `5` in paint files and [`term.blit`], has a default
-- 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
---- Gray: Written as `7` in paint files and @{term.blit}, has a default
+--- Gray: Written as `7` in paint files and [`term.blit`], has a default
-- terminal colour of #4C4C4C.
gray = 0x80
---- Light gray: Written as `8` in paint files and @{term.blit}, has a
+--- Light gray: Written as `8` in paint files and [`term.blit`], has a
-- default terminal colour of #999999.
lightGray = 0x100
---- Cyan: Written as `9` in paint files and @{term.blit}, has a default
+--- Cyan: Written as `9` in paint files and [`term.blit`], has a default
-- terminal colour of #4C99B2.
cyan = 0x200
---- Purple: Written as `a` in paint files and @{term.blit}, has a
+--- Purple: Written as `a` in paint files and [`term.blit`], has a
-- default terminal colour of #B266E5.
purple = 0x400
---- Blue: Written as `b` in paint files and @{term.blit}, has a default
+--- Blue: Written as `b` in paint files and [`term.blit`], has a default
-- terminal colour of #3366CC.
blue = 0x800
---- Brown: Written as `c` in paint files and @{term.blit}, has a default
+--- Brown: Written as `c` in paint files and [`term.blit`], has a default
-- terminal colour of #7F664C.
brown = 0x1000
---- Green: Written as `d` in paint files and @{term.blit}, has a default
+--- Green: Written as `d` in paint files and [`term.blit`], has a default
-- terminal colour of #57A64E.
green = 0x2000
---- Red: Written as `e` in paint files and @{term.blit}, has a default
+--- Red: Written as `e` in paint files and [`term.blit`], has a default
-- terminal colour of #CC4C4C.
red = 0x4000
---- Black: Written as `f` in paint files and @{term.blit}, has a default
+--- Black: Written as `f` in paint files and [`term.blit`], has a default
-- terminal colour of #111111.
black = 0x8000
@@ -313,18 +313,18 @@ function unpackRGB(rgb)
bit32.band(rgb, 0xFF) / 255
end
---- Either calls @{colors.packRGB} or @{colors.unpackRGB}, depending on how many
+--- Either calls [`colors.packRGB`] or [`colors.unpackRGB`], depending on how many
-- arguments it receives.
--
--- @tparam[1] number r The red channel, as an argument to @{colors.packRGB}.
--- @tparam[1] number g The green channel, as an argument to @{colors.packRGB}.
--- @tparam[1] number b The blue channel, as an argument to @{colors.packRGB}.
--- @tparam[2] number rgb The combined hexadecimal color, as an argument to @{colors.unpackRGB}.
--- @treturn[1] number The combined hexadecimal colour, as returned by @{colors.packRGB}.
--- @treturn[2] number The red channel, as returned by @{colors.unpackRGB}
--- @treturn[2] number The green channel, as returned by @{colors.unpackRGB}
--- @treturn[2] number The blue channel, as returned by @{colors.unpackRGB}
--- @deprecated Use @{packRGB} or @{unpackRGB} directly.
+-- @tparam[1] number r The red channel, as an argument to [`colors.packRGB`].
+-- @tparam[1] number g The green channel, as an argument to [`colors.packRGB`].
+-- @tparam[1] number b The blue channel, as an argument to [`colors.packRGB`].
+-- @tparam[2] number rgb The combined hexadecimal color, as an argument to [`colors.unpackRGB`].
+-- @treturn[1] number The combined hexadecimal colour, as returned by [`colors.packRGB`].
+-- @treturn[2] number The red channel, as returned by [`colors.unpackRGB`]
+-- @treturn[2] number The green channel, as returned by [`colors.unpackRGB`]
+-- @treturn[2] number The blue channel, as returned by [`colors.unpackRGB`]
+-- @deprecated Use [`packRGB`] or [`unpackRGB`] directly.
-- @usage
-- ```lua
-- colors.rgb8(0xb23399)
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua
index 7181cb85c..614af6ac5 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua
@@ -2,7 +2,7 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
---- An alternative version of @{colors} for lovers of British spelling.
+--- An alternative version of [`colors`] for lovers of British spelling.
--
-- @see colors
-- @module colours
@@ -13,14 +13,14 @@ for k, v in pairs(colors) do
colours[k] = v
end
---- Grey. Written as `7` in paint files and @{term.blit}, has a default
+--- Grey. Written as `7` in paint files and [`term.blit`], has a default
-- terminal colour of #4C4C4C.
--
-- @see colors.gray
colours.grey = colors.gray
colours.gray = nil --- @local
---- Light grey. Written as `8` in paint files and @{term.blit}, has a
+--- Light grey. Written as `8` in paint files and [`term.blit`], has a
-- default terminal colour of #999999.
--
-- @see colors.lightGray
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua
index 315e17358..3d26a4c27 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua
@@ -5,16 +5,15 @@
--[[- Execute [Minecraft commands][mc] and gather data from the results from
a command computer.
-:::note
-This API is only available on Command computers. It is not accessible to normal
-players.
-:::
+> [!NOTE]
+> This API is only available on Command computers. It is not accessible to normal
+> players.
-While one may use @{commands.exec} directly to execute a command, the
+While one may use [`commands.exec`] directly to execute a command, the
commands API also provides helper methods to execute every command. For
instance, `commands.say("Hi!")` is equivalent to `commands.exec("say Hi!")`.
-@{commands.async} provides a similar interface to execute asynchronous
+[`commands.async`] provides a similar interface to execute asynchronous
commands. `commands.async.say("Hi!")` is equivalent to
`commands.execAsync("say Hi!")`.
@@ -31,7 +30,7 @@ end
--- The builtin commands API, without any generated command helper functions
--
--- This may be useful if a built-in function (such as @{commands.list}) has been
+-- This may be useful if a built-in function (such as [`commands.list`]) has been
-- overwritten by a command.
local native = commands.native or commands
@@ -112,7 +111,7 @@ end
--- A table containing asynchronous wrappers for all commands.
--
--- As with @{commands.execAsync}, this returns the "task id" of the enqueued
+-- As with [`commands.execAsync`], this returns the "task id" of the enqueued
-- command.
-- @see execAsync
-- @usage Asynchronously sets the block above the computer to stone.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua
index cf518bfba..2ade59bed 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua
@@ -9,10 +9,9 @@ locally attached drive, specify “side” as one of the six sides (e.g. `left`)
use a remote disk drive, specify its name as printed when enabling its modem
(e.g. `drive_0`).
-:::tip
-All computers (except command computers), turtles and pocket computers can be
-placed within a disk drive to access it's internal storage like a disk.
-:::
+> [!TIP]
+> All computers (except command computers), turtles and pocket computers can be
+> placed within a disk drive to access it's internal storage like a disk.
@module disk
@since 1.2
@@ -95,7 +94,7 @@ end
--- Whether the current disk is a [music disk][disk] as opposed to a floppy disk
-- or other item.
--
--- If this returns true, you will can @{disk.playAudio|play} the record.
+-- If this returns true, you will can [play][`disk.playAudio`] the record.
--
-- [disk]: https://minecraft.gamepedia.com/Music_Disc
--
@@ -110,10 +109,10 @@ end
--- Get the title of the audio track from the music record in the drive.
--
--- This generally returns the same as @{disk.getLabel} for records.
+-- This generally returns the same as [`disk.getLabel`] for records.
--
-- @tparam string name The name of the disk drive.
--- @treturn string|false|nil The track title, @{false} if there is not a music
+-- @treturn string|false|nil The track title, [`false`] if there is not a music
-- record in the drive or `nil` if no drive is present.
function getAudioTitle(name)
if isDrive(name) then
@@ -126,7 +125,7 @@ end
--
-- If any record is already playing on any disk drive, it stops before the
-- target drive starts playing. The record stops when it reaches the end of the
--- track, when it is removed from the drive, when @{disk.stopAudio} is called, or
+-- track, when it is removed from the drive, when [`disk.stopAudio`] is called, or
-- when another record is started.
--
-- @tparam string name The name of the disk drive.
@@ -138,7 +137,7 @@ function playAudio(name)
end
--- Stops the music record in the drive from playing, if it was started with
--- @{disk.playAudio}.
+-- [`disk.playAudio`].
--
-- @tparam string name The name o the disk drive.
function stopAudio(name)
@@ -165,7 +164,7 @@ end
--- Returns a number which uniquely identifies the disk in the drive.
--
--- Note, unlike @{disk.getLabel}, this does not return anything for other media,
+-- Note, unlike [`disk.getLabel`], this does not return anything for other media,
-- such as computers or turtles.
--
-- @tparam string name The name of the disk drive.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua
index 0643fd120..a18619234 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua
@@ -13,19 +13,19 @@ local fs = _ENV
for k, v in pairs(native) do fs[k] = v end
--[[- Provides completion for a file or directory name, suitable for use with
-@{_G.read}.
+[`_G.read`].
When a directory is a possible candidate for completion, two entries are
included - one with a trailing slash (indicating that entries within this
directory exist) and one without it (meaning this entry is an immediate
-completion candidate). `include_dirs` can be set to @{false} to only include
+completion candidate). `include_dirs` can be set to [`false`] to only include
those with a trailing slash.
@tparam[1] string path The path to complete.
@tparam[1] string location The location where paths are resolved from.
-@tparam[1,opt=true] boolean include_files When @{false}, only directories will
+@tparam[1,opt=true] boolean include_files When [`false`], only directories will
be included in the returned list.
-@tparam[1,opt=true] boolean include_dirs When @{false}, "raw" directories will
+@tparam[1,opt=true] boolean include_dirs When [`false`], "raw" directories will
not be included in the returned list.
@tparam[2] string path The path to complete.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua
index d95715fe0..d1eafec2c 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua
@@ -2,21 +2,20 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
---[[- Use @{modem|modems} to locate the position of the current turtle or
+--[[- Use [modems][`modem`] to locate the position of the current turtle or
computers.
-It broadcasts a PING message over @{rednet} and wait for responses. In order for
+It broadcasts a PING message over [`rednet`] and wait for responses. In order for
this system to work, there must be at least 4 computers used as gps hosts which
will respond and allow trilateration. Three of these hosts should be in a plane,
and the fourth should be either above or below the other three. The three in a
plane should not be in a line with each other. You can set up hosts using the
gps program.
-:::note
-When entering in the coordinates for the host you need to put in the `x`, `y`,
-and `z` coordinates of the block that the modem is connected to, not the modem.
-All modem distances are measured from the block that the modem is placed on.
-:::
+> [!NOTE]
+> When entering in the coordinates for the host you need to put in the `x`, `y`,
+> and `z` coordinates of the block that the modem is connected to, not the modem.
+> All modem distances are measured from the block that the modem is placed on.
Also note that you may choose which axes x, y, or z refers to - so long as your
systems have the same definition as any GPS servers that're in range, it works
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua
index 087898b91..9e074a475 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua
@@ -74,7 +74,7 @@ decoded.
url = string, headers? = { [string] = string },
binary? = boolean, method? = string, redirect? = boolean,
timeout? = number,
-} request Options for the request. See @{http.request} for details on how
+} request Options for the request. See [`http.request`] for details on how
these options behave.
@treturn Response The resulting http response, which can be read from.
@@ -126,7 +126,7 @@ decoded.
url = string, body? = string, headers? = { [string] = string },
binary? = boolean, method? = string, redirect? = boolean,
timeout? = number,
-} request Options for the request. See @{http.request} for details on how
+} request Options for the request. See [`http.request`] for details on how
these options behave.
@treturn Response The resulting http response, which can be read from.
@@ -158,7 +158,7 @@ end
--[[- Asynchronously make a HTTP request to the given url.
-This returns immediately, a @{http_success} or @{http_failure} will be queued
+This returns immediately, a [`http_success`] or [`http_failure`] will be queued
once the request has completed.
@tparam string url The url to request
@@ -221,7 +221,7 @@ local nativeCheckURL = native.checkURL
--[[- Asynchronously determine whether a URL can be requested.
-If this returns `true`, one should also listen for @{http_check} which will
+If this returns `true`, one should also listen for [`http_check`] which will
container further information about whether the URL is allowed or not.
@tparam string url The URL to check.
@@ -237,11 +237,11 @@ checkURLAsync = nativeCheckURL
--[[- Determine whether a URL can be requested.
-If this returns `true`, one should also listen for @{http_check} which will
+If this returns `true`, one should also listen for [`http_check`] which will
container further information about whether the URL is allowed or not.
@tparam string url The URL to check.
-@treturn true When this url is valid and can be requested via @{http.request}.
+@treturn true When this url is valid and can be requested via [`http.request`].
@treturn[2] false When this url is invalid.
@treturn string A reason why this URL is not valid (for instance, if it is
malformed, or blocked).
@@ -280,7 +280,7 @@ end
--[[- Asynchronously open a websocket.
-This returns immediately, a @{websocket_success} or @{websocket_failure}
+This returns immediately, a [`websocket_success`] or [`websocket_failure`]
will be queued once the request has completed.
@tparam[1] string url The websocket url to connect to. This should have the
@@ -290,7 +290,7 @@ of the initial websocket connection.
@tparam[2] {
url = string, headers? = { [string] = string }, timeout ?= number,
-} request Options for the websocket. See @{http.websocket} for details on how
+} request Options for the websocket. See [`http.websocket`] for details on how
these options behave.
@since 1.80pr1.3
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua
index 125397900..2ffe044c7 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua
@@ -74,10 +74,10 @@ handleMetatable = {
This can be used in a for loop to iterate over all lines of a file
- Once the end of the file has been reached, @{nil} will be returned. The file is
+ Once the end of the file has been reached, [`nil`] will be returned. The file is
*not* automatically closed.
- @param ... The argument to pass to @{Handle:read} for each line.
+ @param ... The argument to pass to [`Handle:read`] for each line.
@treturn function():string|nil The line iterator.
@throws If the file cannot be opened for reading
@since 1.3
@@ -324,14 +324,14 @@ each time it is called, returns a new line from the file.
This can be used in a for loop to iterate over all lines of a file
-Once the end of the file has been reached, @{nil} will be returned. The file is
+Once the end of the file has been reached, [`nil`] will be returned. The file is
automatically closed.
-If no file name is given, the @{io.input|current input} will be used instead.
+If no file name is given, the [current input][`io.input`] will be used instead.
In this case, the handle is not used.
@tparam[opt] string filename The name of the file to extract lines from
-@param ... The argument to pass to @{Handle:read} for each line.
+@param ... The argument to pass to [`Handle:read`] for each line.
@treturn function():string|nil The line iterator.
@throws If the file cannot be opened for reading
@@ -362,7 +362,7 @@ function lines(filename, ...)
end
--- Open a file with the given mode, either returning a new file handle
--- or @{nil}, plus an error message.
+-- or [`nil`], plus an error message.
--
-- The `mode` string can be any of the following:
-- - **"r"**: Read mode
@@ -410,11 +410,11 @@ end
--- Read from the currently opened input file.
--
--- This is equivalent to `io.input():read(...)`. See @{Handle:read|the
--- documentation} there for full details.
+-- This is equivalent to `io.input():read(...)`. See [the documentation][`Handle:read`]
+-- there for full details.
--
-- @tparam string ... The formats to read, defaulting to a whole line.
--- @treturn (string|nil)... The data read, or @{nil} if nothing can be read.
+-- @treturn (string|nil)... The data read, or [`nil`] if nothing can be read.
function read(...)
return currentInput:read(...)
end
@@ -438,8 +438,8 @@ end
--- Write to the currently opened output file.
--
--- This is equivalent to `io.output():write(...)`. See @{Handle:write|the
--- documentation} there for full details.
+-- This is equivalent to `io.output():write(...)`. See [the documentation][`Handle:write`]
+-- there for full details.
--
-- @tparam string ... The strings to write
-- @changed 1.81.0 Multiple arguments are now allowed.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/keys.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/keys.lua
index cfce4b9dc..3fb07240c 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/keys.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/keys.lua
@@ -2,7 +2,7 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
---- Constants for all keyboard "key codes", as queued by the @{key} event.
+--- Constants for all keyboard "key codes", as queued by the [`key`] event.
--
-- These values are not guaranteed to remain the same between versions. It is
-- recommended that you use the constants provided by this file, rather than
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua
index d52373ce7..567043223 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua
@@ -51,7 +51,7 @@ end
--
-- @tparam string image The string containing the raw-image data.
-- @treturn table The parsed image data, suitable for use with
--- @{paintutils.drawImage}.
+-- [`paintutils.drawImage`].
-- @since 1.80pr1
function parseImage(image)
expect(1, image, "string")
@@ -69,7 +69,7 @@ end
-- @tparam string path The file to load.
--
-- @treturn table|nil The parsed image data, suitable for use with
--- @{paintutils.drawImage}, or `nil` if the file does not exist.
+-- [`paintutils.drawImage`], or `nil` if the file does not exist.
-- @usage Load an image and draw it.
--
-- local image = paintutils.loadImage("data/example.nfp")
@@ -93,7 +93,7 @@ end
--
-- @tparam number xPos The x position to draw at, where 1 is the far left.
-- @tparam number yPos The y position to draw at, where 1 is the very top.
--- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
+-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
function drawPixel(xPos, yPos, colour)
expect(1, xPos, "number")
@@ -115,7 +115,7 @@ end
-- @tparam number startY The starting y position of the line.
-- @tparam number endX The end x position of the line.
-- @tparam number endY The end y position of the line.
--- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
+-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
-- @usage paintutils.drawLine(2, 3, 30, 7, colors.red)
function drawLine(startX, startY, endX, endY, colour)
@@ -189,7 +189,7 @@ end
-- @tparam number startY The starting y position of the line.
-- @tparam number endX The end x position of the line.
-- @tparam number endY The end y position of the line.
--- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
+-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
-- @usage paintutils.drawBox(2, 3, 30, 7, colors.red)
function drawBox(startX, startY, endX, endY, nColour)
@@ -242,7 +242,7 @@ end
-- @tparam number startY The starting y position of the line.
-- @tparam number endX The end x position of the line.
-- @tparam number endY The end y position of the line.
--- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
+-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
-- @usage paintutils.drawFilledBox(2, 3, 30, 7, colors.red)
function drawFilledBox(startX, startY, endX, endY, nColour)
@@ -278,7 +278,7 @@ function drawFilledBox(startX, startY, endX, endY, nColour)
end
end
---- Draw an image loaded by @{paintutils.parseImage} or @{paintutils.loadImage}.
+--- Draw an image loaded by [`paintutils.parseImage`] or [`paintutils.loadImage`].
--
-- @tparam table image The parsed image data.
-- @tparam number xPos The x position to start drawing at.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua
index 20b2b1e8f..b228300d7 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua
@@ -6,36 +6,34 @@
Functions are not actually executed simultaneously, but rather this API will
automatically switch between them whenever they yield (e.g. whenever they call
-@{coroutine.yield}, or functions that call that - such as @{os.pullEvent} - or
+[`coroutine.yield`], or functions that call that - such as [`os.pullEvent`] - or
functions that call that, etc - basically, anything that causes the function
to "pause").
Each function executed in "parallel" gets its own copy of the event queue,
and so "event consuming" functions (again, mostly anything that causes the
-script to pause - eg @{os.sleep}, @{rednet.receive}, most of the @{turtle} API,
+script to pause - eg [`os.sleep`], [`rednet.receive`], most of the [`turtle`] API,
etc) can safely be used in one without affecting the event queue accessed by
the other.
-:::caution
-When using this API, be careful to pass the functions you want to run in
-parallel, and _not_ the result of calling those functions.
-
-For instance, the following is correct:
-
-```lua
-local function do_sleep() sleep(1) end
-parallel.waitForAny(do_sleep, rednet.receive)
-```
-
-but the following is **NOT**:
-
-```lua
-local function do_sleep() sleep(1) end
-parallel.waitForAny(do_sleep(), rednet.receive)
-```
-
-:::
+> [!WARNING]
+> When using this API, be careful to pass the functions you want to run in
+> parallel, and _not_ the result of calling those functions.
+>
+> For instance, the following is correct:
+>
+> ```lua
+> local function do_sleep() sleep(1) end
+> parallel.waitForAny(do_sleep, rednet.receive)
+> ```
+>
+> but the following is **NOT**:
+>
+> ```lua
+> local function do_sleep() sleep(1) end
+> parallel.waitForAny(do_sleep(), rednet.receive)
+> ```
@module parallel
@since 1.2
@@ -100,7 +98,7 @@ end
--[[- Switches between execution of the functions, until any of them
finishes. If any of the functions errors, the message is propagated upwards
-from the @{parallel.waitForAny} call.
+from the [`parallel.waitForAny`] call.
@tparam function ... The functions this task will run
@usage Print a message every second until the `q` key is pressed.
@@ -128,7 +126,7 @@ end
--[[- Switches between execution of the functions, until all of them are
finished. If any of the functions errors, the message is propagated upwards
-from the @{parallel.waitForAll} call.
+from the [`parallel.waitForAll`] call.
@tparam function ... The functions this task will run
@usage Start off two timers and wait for them both to run.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
index a7a291d7e..022c18059 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
@@ -5,8 +5,8 @@
--[[- Find and control peripherals attached to this computer.
Peripherals are blocks (or turtle and pocket computer upgrades) which can
-be controlled by a computer. For instance, the @{speaker} peripheral allows a
-computer to play music and the @{monitor} peripheral allows you to display text
+be controlled by a computer. For instance, the [`speaker`] peripheral allows a
+computer to play music and the [`monitor`] peripheral allows you to display text
in the world.
## Referencing peripherals
@@ -18,10 +18,10 @@ computer will be called `"bottom"` in your Lua code, one to the left called
`"right"`, `"front"`, `"back"`).
You can list the names of all peripherals with the `peripherals` program, or the
-@{peripheral.getNames} function.
+[`peripheral.getNames`] function.
It's also possible to use peripherals which are further away from your computer
-through the use of @{modem|Wired Modems}. Place one modem against your computer
+through the use of [Wired Modems][`modem`]. Place one modem against your computer
(you may need to sneak and right click), run Networking Cable to your
peripheral, and then place another modem against that block. You can then right
click the modem to use (or *attach*) the peripheral. This will print a
@@ -32,24 +32,23 @@ clipboard.
## Using peripherals
Once you have the name of a peripheral, you can call functions on it using the
-@{peripheral.call} function. This takes the name of our peripheral, the name of
+[`peripheral.call`] function. This takes the name of our peripheral, the name of
the function we want to call, and then its arguments.
-:::info
-Some bits of the peripheral API call peripheral functions *methods* instead
-(for example, the @{peripheral.getMethods} function). Don't worry, they're the
-same thing!
-:::
+> [!INFO]
+> Some bits of the peripheral API call peripheral functions *methods* instead
+> (for example, the [`peripheral.getMethods`] function). Don't worry, they're the
+> same thing!
Let's say we have a monitor above our computer (and so "top") and want to
-@{monitor.write|write some text to it}. We'd write the following:
+[write some text to it][`monitor.write`]. We'd write the following:
```lua
peripheral.call("top", "write", "This is displayed on a monitor!")
```
Once you start calling making a couple of peripheral calls this can get very
-repetitive, and so we can @{peripheral.wrap|wrap} a peripheral. This builds a
+repetitive, and so we can [wrap][`peripheral.wrap`] a peripheral. This builds a
table of all the peripheral's functions so you can use it like an API or module.
For instance, we could have written the above example as follows:
@@ -66,7 +65,7 @@ called, you just need to know it's there. For instance, if you're writing a
music player, you just need a speaker - it doesn't matter if it's above or below
the computer.
-Thankfully there's a quick way to do this: @{peripheral.find}. This takes a
+Thankfully there's a quick way to do this: [`peripheral.find`]. This takes a
*peripheral type* and returns all the attached peripherals which are of this
type.
@@ -76,10 +75,10 @@ are just called `"speaker"`, and monitors `"monitor"`. Some peripherals might
have more than one type - a Minecraft chest is both a `"minecraft:chest"` and
`"inventory"`.
-You can get all the types a peripheral has with @{peripheral.getType}, and check
-a peripheral is a specific type with @{peripheral.hasType}.
+You can get all the types a peripheral has with [`peripheral.getType`], and check
+a peripheral is a specific type with [`peripheral.hasType`].
-To return to our original example, let's use @{peripheral.find} to find an
+To return to our original example, let's use [`peripheral.find`] to find an
attached speaker:
```lua
@@ -229,7 +228,7 @@ function getMethods(name)
return nil
end
---- Get the name of a peripheral wrapped with @{peripheral.wrap}.
+--- Get the name of a peripheral wrapped with [`peripheral.wrap`].
--
-- @tparam table peripheral The peripheral to get the name of.
-- @treturn string The name of the given peripheral.
@@ -270,7 +269,7 @@ function call(name, method, ...)
end
--- Get a table containing all functions available on a peripheral. These can
--- then be called instead of using @{peripheral.call} every time.
+-- then be called instead of using [`peripheral.call`] every time.
--
-- @tparam string name The name of the peripheral to wrap.
-- @treturn table|nil The table containing the peripheral's methods, or `nil` if
@@ -305,7 +304,7 @@ function wrap(name)
end
--[[- Find all peripherals of a specific type, and return the
-@{peripheral.wrap|wrapped} peripherals.
+[wrapped][`peripheral.wrap`] peripherals.
@tparam string ty The type of peripheral to look for.
@tparam[opt] function(name:string, wrapped:table):boolean filter A
@@ -325,7 +324,7 @@ and returns if it should be included in the result.
return modem.isWireless() -- Check this modem is wireless.
end) }
-@usage This abuses the `filter` argument to call @{rednet.open} on every modem.
+@usage This abuses the `filter` argument to call [`rednet.open`] on every modem.
peripheral.find("modem", rednet.open)
@since 1.6
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua
index a2d168cc0..b14618bdb 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua
@@ -2,42 +2,41 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
---[[- Communicate with other computers by using @{modem|modems}. @{rednet}
-provides a layer of abstraction on top of the main @{modem} peripheral, making
+--[[- Communicate with other computers by using [modems][`modem`]. [`rednet`]
+provides a layer of abstraction on top of the main [`modem`] peripheral, making
it slightly easier to use.
## Basic usage
In order to send a message between two computers, each computer must have a
modem on one of its sides (or in the case of pocket computers and turtles, the
modem must be equipped as an upgrade). The two computers should then call
-@{rednet.open}, which sets up the modems ready to send and receive messages.
+[`rednet.open`], which sets up the modems ready to send and receive messages.
-Once rednet is opened, you can send messages using @{rednet.send} and receive
-them using @{rednet.receive}. It's also possible to send a message to _every_
-rednet-using computer using @{rednet.broadcast}.
+Once rednet is opened, you can send messages using [`rednet.send`] and receive
+them using [`rednet.receive`]. It's also possible to send a message to _every_
+rednet-using computer using [`rednet.broadcast`].
-:::caution Network security
-
-While rednet provides a friendly way to send messages to specific computers, it
-doesn't provide any guarantees about security. Other computers could be
-listening in to your messages, or even pretending to send messages from other computers!
-
-If you're playing on a multi-player server (or at least one where you don't
-trust other players), it's worth encrypting or signing your rednet messages.
-:::
+> [Network security][!WARNING]
+>
+> While rednet provides a friendly way to send messages to specific computers, it
+> doesn't provide any guarantees about security. Other computers could be
+> listening in to your messages, or even pretending to send messages from other computers!
+>
+> If you're playing on a multi-player server (or at least one where you don't
+> trust other players), it's worth encrypting or signing your rednet messages.
## Protocols and hostnames
Several rednet messages accept "protocol"s - simple string names describing what
-a message is about. When sending messages using @{rednet.send} and
-@{rednet.broadcast}, you can optionally specify a protocol for the message. This
-same protocol can then be given to @{rednet.receive}, to ignore all messages not
+a message is about. When sending messages using [`rednet.send`] and
+[`rednet.broadcast`], you can optionally specify a protocol for the message. This
+same protocol can then be given to [`rednet.receive`], to ignore all messages not
using this protocol.
It's also possible to look-up computers based on protocols, providing a basic
system for service discovery and [DNS]. A computer can advertise that it
-supports a particular protocol with @{rednet.host}, also providing a friendly
+supports a particular protocol with [`rednet.host`], also providing a friendly
"hostname". Other computers may then find all computers which support this
-protocol using @{rednet.lookup}.
+protocol using [`rednet.lookup`].
[DNS]: https://en.wikipedia.org/wiki/Domain_Name_System "Domain Name System"
@@ -50,7 +49,7 @@ bare-bones but flexible interface.
local expect = dofile("rom/modules/main/cc/expect.lua").expect
---- The channel used by the Rednet API to @{broadcast} messages.
+--- The channel used by the Rednet API to [`broadcast`] messages.
CHANNEL_BROADCAST = 65535
--- The channel used by the Rednet API to repeat messages.
@@ -68,12 +67,12 @@ local function id_as_channel(id)
return (id or os.getComputerID()) % MAX_ID_CHANNELS
end
---[[- Opens a modem with the given @{peripheral} name, allowing it to send and
+--[[- Opens a modem with the given [`peripheral`] name, allowing it to send and
receive messages over rednet.
This will open the modem on two channels: one which has the same
-@{os.getComputerID|ID} as the computer, and another on
-@{CHANNEL_BROADCAST|the broadcast channel}.
+[ID][`os.getComputerID`] as the computer, and another on
+[the broadcast channel][`CHANNEL_BROADCAST`].
@tparam string modem The name of the modem to open.
@throws If there is no such modem with the given name
@@ -83,7 +82,7 @@ rednet messages using it.
rednet.open("back")
@usage Open rednet on all attached modems. This abuses the "filter" argument to
-@{peripheral.find}.
+[`peripheral.find`].
peripheral.find("modem", rednet.open)
@see rednet.close
@@ -98,7 +97,7 @@ function open(modem)
peripheral.call(modem, "open", CHANNEL_BROADCAST)
end
---- Close a modem with the given @{peripheral} name, meaning it can no longer
+--- Close a modem with the given [`peripheral`] name, meaning it can no longer
-- send and receive rednet messages.
--
-- @tparam[opt] string modem The side the modem exists on. If not given, all
@@ -151,21 +150,21 @@ end
--[[- Allows a computer or turtle with an attached modem to send a message
intended for a sycomputer with a specific ID. At least one such modem must first
-be @{rednet.open|opened} before sending is possible.
+be [opened][`rednet.open`] before sending is possible.
Assuming the target was in range and also had a correctly opened modem, the
-target computer may then use @{rednet.receive} to collect the message.
+target computer may then use [`rednet.receive`] to collect the message.
@tparam number recipient The ID of the receiving computer.
-@param message The message to send. Like with @{modem.transmit}, this can
+@param message The message to send. Like with [`modem.transmit`], this can
contain any primitive type (numbers, booleans and strings) as well as
tables. Other types (like functions), as well as metatables, will not be
transmitted.
@tparam[opt] string protocol The "protocol" to send this message under. When
-using @{rednet.receive} one can filter to only receive messages sent under a
+using [`rednet.receive`] one can filter to only receive messages sent under a
particular protocol.
@treturn boolean If this message was successfully sent (i.e. if rednet is
-currently @{rednet.open|open}). Note, this does not guarantee the message was
+currently [open][`rednet.open`]). Note, this does not guarantee the message was
actually _received_.
@changed 1.6 Added protocol parameter.
@changed 1.82.0 Now returns whether the message was successfully sent.
@@ -217,13 +216,13 @@ function send(recipient, message, protocol)
return sent
end
---[[- Broadcasts a string message over the predefined @{CHANNEL_BROADCAST}
+--[[- Broadcasts a string message over the predefined [`CHANNEL_BROADCAST`]
channel. The message will be received by every device listening to rednet.
@param message The message to send. This should not contain coroutines or
-functions, as they will be converted to @{nil}.
+functions, as they will be converted to [`nil`].
@tparam[opt] string protocol The "protocol" to send this message under. When
-using @{rednet.receive} one can filter to only receive messages sent under a
+using [`rednet.receive`] one can filter to only receive messages sent under a
particular protocol.
@see rednet.receive
@changed 1.6 Added protocol parameter.
@@ -311,7 +310,7 @@ function receive(protocol_filter, timeout)
end
--[[- Register the system as "hosting" the desired protocol under the specified
-name. If a rednet @{rednet.lookup|lookup} is performed for that protocol (and
+name. If a rednet [lookup][`rednet.lookup`] is performed for that protocol (and
maybe name) on the same network, the registered system will automatically
respond via a background process, hence providing the system performing the
lookup with its ID number.
@@ -343,8 +342,8 @@ function host(protocol, hostname)
end
end
---- Stop @{rednet.host|hosting} a specific protocol, meaning it will no longer
--- respond to @{rednet.lookup} requests.
+--- Stop [hosting][`rednet.host`] a specific protocol, meaning it will no longer
+-- respond to [`rednet.lookup`] requests.
--
-- @tparam string protocol The protocol to unregister your self from.
-- @since 1.6
@@ -353,7 +352,7 @@ function unhost(protocol)
hostnames[protocol] = nil
end
---[[- Search the local rednet network for systems @{rednet.host|hosting} the
+--[[- Search the local rednet network for systems [hosting][`rednet.host`] the
desired protocol and returns any computer IDs that respond as "registered"
against it.
@@ -365,7 +364,7 @@ match is found).
@treturn[1] number... A list of computer IDs hosting the given protocol.
@treturn[2] number|nil The computer ID with the provided hostname and protocol,
-or @{nil} if none exists.
+or [`nil`] if none exists.
@since 1.6
@usage Find all computers which are hosting the `"chat"` protocol.
@@ -450,7 +449,7 @@ end
local started = false
--- Listen for modem messages and converts them into rednet messages, which may
--- then be @{receive|received}.
+-- then be [received][`receive`].
--
-- This is automatically started in the background on computer startup, and
-- should not be called manually.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua
index d1481401b..91af31c11 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua
@@ -5,13 +5,12 @@
--[[- Read and write configuration options for CraftOS and your programs.
When a computer starts, it reads the current value of settings from the
-`/.settings` file. These values then may be @{settings.get|read} or
-@{settings.set|modified}.
+`/.settings` file. These values then may be [read][`settings.get`] or
+[modified][`settings.set`].
-:::caution
-Calling @{settings.set} does _not_ update the settings file by default. You
-_must_ call @{settings.save} to persist values.
-:::
+> [!WARNING]
+> Calling [`settings.set`] does _not_ update the settings file by default. You
+> _must_ call [`settings.save`] to persist values.
@module settings
@since 1.78
@@ -59,9 +58,9 @@ for _, v in ipairs(valid_types) do valid_types[v] = true end
-- Options for this setting. This table accepts the following fields:
--
-- - `description`: A description which may be printed when running the `set` program.
--- - `default`: A default value, which is returned by @{settings.get} if the
+-- - `default`: A default value, which is returned by [`settings.get`] if the
-- setting has not been changed.
--- - `type`: Require values to be of this type. @{set|Setting} the value to another type
+-- - `type`: Require values to be of this type. [Setting][`set`] the value to another type
-- will error.
-- @since 1.87.0
function define(name, options)
@@ -85,9 +84,9 @@ function define(name, options)
details[name] = options
end
---- Remove a @{define|definition} of a setting.
+--- Remove a [definition][`define`] of a setting.
--
--- If a setting has been changed, this does not remove its value. Use @{settings.unset}
+-- If a setting has been changed, this does not remove its value. Use [`settings.unset`]
-- for that.
--
-- @tparam string name The name of this option
@@ -113,14 +112,13 @@ end
--[[- Set the value of a setting.
-:::caution
-Calling @{settings.set} does _not_ update the settings file by default. You
-_must_ call @{settings.save} to persist values.
-:::
+> [!WARNING]
+> Calling [`settings.set`] does _not_ update the settings file by default. You
+> _must_ call [`settings.save`] to persist values.
@tparam string name The name of the setting to set
@param value The setting's value. This cannot be `nil`, and must be
-serialisable by @{textutils.serialize}.
+serialisable by [`textutils.serialize`].
@throws If this value cannot be serialised
@see settings.unset
]]
@@ -159,7 +157,7 @@ end
--
-- @tparam string name The name of the setting to get.
-- @treturn { description? = string, default? = any, type? = string, value? = any }
--- Information about this setting. This includes all information from @{settings.define},
+-- Information about this setting. This includes all information from [`settings.define`],
-- as well as this setting's value.
-- @since 1.87.0
function getDetails(name)
@@ -173,8 +171,8 @@ end
--- Remove the value of a setting, setting it to the default.
--
--- @{settings.get} will return the default value until the setting's value is
--- @{settings.set|set}, or the computer is rebooted.
+-- [`settings.get`] will return the default value until the setting's value is
+-- [set][`settings.set`], or the computer is rebooted.
--
-- @tparam string name The name of the setting to unset.
-- @see settings.set
@@ -184,7 +182,7 @@ function unset(name)
set_value(name, nil)
end
---- Resets the value of all settings. Equivalent to calling @{settings.unset}
+--- Resets the value of all settings. Equivalent to calling [`settings.unset`]
--- on every setting.
--
-- @see settings.unset
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua
index 2bfa72b8b..30aaa5355 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua
@@ -17,9 +17,9 @@ end
local term = _ENV
---- Redirects terminal output to a monitor, a @{window}, or any other custom
+--- Redirects terminal output to a monitor, a [`window`], or any other custom
-- terminal object. Once the redirect is performed, any calls to a "term"
--- function - or to a function that makes use of a term function, as @{print} -
+-- function - or to a function that makes use of a term function, as [`print`] -
-- will instead operate with the new terminal object.
--
-- A "terminal object" is simply a table that contains functions with the same
@@ -29,9 +29,9 @@ local term = _ENV
-- The redirect can be undone by pointing back to the previous terminal object
-- (which this function returns whenever you switch).
--
--- @tparam Redirect target The terminal redirect the @{term} API will draw to.
+-- @tparam Redirect target The terminal redirect the [`term`] API will draw to.
-- @treturn Redirect The previous redirect object, as returned by
--- @{term.current}.
+-- [`term.current`].
-- @since 1.31
-- @usage
-- Redirect to a monitor on the right of the computer.
@@ -60,7 +60,7 @@ end
-- @treturn Redirect The current terminal redirect
-- @since 1.6
-- @usage
--- Create a new @{window} which draws to the current redirect target.
+-- Create a new [`window`] which draws to the current redirect target.
--
-- window.create(term.current(), 1, 1, 10, 10)
term.current = function()
@@ -70,7 +70,7 @@ end
--- Get the native terminal object of the current computer.
--
-- It is recommended you do not use this function unless you absolutely have
--- to. In a multitasked environment, @{term.native} will _not_ be the current
+-- to. In a multitasked environment, [`term.native`] will _not_ be the current
-- terminal object, and so drawing may interfere with other programs.
--
-- @treturn Redirect The native terminal redirect.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
index 3d34c27b3..caf14668e 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
@@ -14,7 +14,7 @@ local wrap = dofile("rom/modules/main/cc/strings.lua").wrap
--- Slowly writes string text at current cursor position,
-- character-by-character.
--
--- Like @{_G.write}, this does not insert a newline at the end.
+-- Like [`_G.write`], this does not insert a newline at the end.
--
-- @tparam string text The the text to write to the screen
-- @tparam[opt] number rate The number of characters to write each second,
@@ -42,7 +42,7 @@ end
--- Slowly prints string text at current cursor position,
-- character-by-character.
--
--- Like @{print}, this inserts a newline after printing.
+-- Like [`print`], this inserts a newline after printing.
--
-- @tparam string sText The the text to write to the screen
-- @tparam[opt] number nRate The number of characters to write each second,
@@ -56,7 +56,7 @@ end
--- Takes input time and formats it in a more readable format such as `6:30 PM`.
--
--- @tparam number nTime The time to format, as provided by @{os.time}.
+-- @tparam number nTime The time to format, as provided by [`os.time`].
-- @tparam[opt] boolean bTwentyFourHour Whether to format this as a 24-hour
-- clock (`18:30`) rather than a 12-hour one (`6:30 AM`)
-- @treturn string The formatted time
@@ -114,7 +114,7 @@ end
--[[- Prints a given string to the display.
If the action can be completed without scrolling, it acts much the same as
-@{print}; otherwise, it will throw up a "Press any key to continue" prompt at
+[`print`]; otherwise, it will throw up a "Press any key to continue" prompt at
the bottom of the display. Each press will cause it to scroll down and write a
single line more before prompting again, if need be.
@@ -253,7 +253,7 @@ end
--[[- Prints tables in a structured form, stopping and prompting for input should
the result not fit on the terminal.
-This functions identically to @{textutils.tabulate}, but will prompt for user
+This functions identically to [`textutils.tabulate`], but will prompt for user
input should the whole output not fit on the display.
@tparam {string...}|number ... The rows and text colors to display.
@@ -702,13 +702,13 @@ do
--[[- Converts a serialised JSON string back into a reassembled Lua object.
- This may be used with @{textutils.serializeJSON}, or when communicating
+ This may be used with [`textutils.serializeJSON`], or when communicating
with command blocks or web APIs.
If a `null` value is encountered, it is converted into `nil`. It can be converted
- into @{textutils.json_null} with the `parse_null` option.
+ into [`textutils.json_null`] with the `parse_null` option.
- If an empty array is encountered, it is converted into @{textutils.empty_json_array}.
+ If an empty array is encountered, it is converted into [`textutils.empty_json_array`].
It can be converted into a new empty table with the `parse_empty_array` option.
@tparam string s The serialised string to deserialise.
@@ -717,10 +717,10 @@ do
- `nbt_style`: When true, this will accept [stringified NBT][nbt] strings,
as produced by many commands.
- - `parse_null`: When true, `null` will be parsed as @{json_null}, rather than
+ - `parse_null`: When true, `null` will be parsed as [`json_null`], rather than
`nil`.
- `parse_empty_array`: When false, empty arrays will be parsed as a new table.
- By default (or when this value is true), they are parsed as @{empty_json_array}.
+ By default (or when this value is true), they are parsed as [`empty_json_array`].
[nbt]: https://minecraft.gamepedia.com/NBT_format
@return[1] The deserialised object
@@ -734,7 +734,7 @@ do
textutils.unserialiseJSON('{"name": "Steve", "age": null}')
- @usage Unserialise a basic JSON object, returning null values as @{json_null}.
+ @usage Unserialise a basic JSON object, returning null values as [`json_null`].
textutils.unserialiseJSON('{"name": "Steve", "age": null}', { parse_null = true })
]]
@@ -813,7 +813,7 @@ serialise = serialize -- GB version
--- Converts a serialised string back into a reassembled Lua object.
--
--- This is mainly used together with @{textutils.serialise}.
+-- This is mainly used together with [`textutils.serialise`].
--
-- @tparam string s The serialised string to deserialise.
-- @return[1] The deserialised object
@@ -837,19 +837,19 @@ unserialise = unserialize -- GB version
This function attempts to guess whether a table is a JSON array or
object. However, empty tables are assumed to be empty objects - use
-@{textutils.empty_json_array} to mark an empty array.
+[`textutils.empty_json_array`] to mark an empty array.
This is largely intended for interacting with various functions from the
-@{commands} API, though may also be used in making @{http} requests.
+[`commands`] API, though may also be used in making [`http`] requests.
-@param[1] t The value to serialise. Like @{textutils.serialise}, this should not
+@param[1] t The value to serialise. Like [`textutils.serialise`], this should not
contain recursive tables or functions.
@tparam[1,opt] { nbt_style? = boolean, unicode_strings? = boolean } options Options for serialisation.
- `nbt_style`: Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON.
- `unicode_strings`: Whether to treat strings as containing UTF-8 characters instead of
using the default 8-bit character set.
-@param[2] t The value to serialise. Like @{textutils.serialise}, this should not
+@param[2] t The value to serialise. Like [`textutils.serialise`], this should not
contain recursive tables or functions.
@tparam[2] boolean bNBTStyle Whether to produce NBT-style JSON (non-quoted keys)
instead of standard JSON.
@@ -929,7 +929,7 @@ local tEmpty = {}
-- variable name or table index.
--
-- @tparam[opt] table tSearchTable The table to find variables in, defaulting to
--- the global environment (@{_G}). The function also searches the "parent"
+-- the global environment ([`_G`]). The function also searches the "parent"
-- environment via the `__index` metatable field.
--
-- @treturn { string... } The (possibly empty) list of completions.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua
index e4d204062..71f4be94f 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua
@@ -4,7 +4,7 @@
--- A basic 3D vector type and some common vector operations. This may be useful
-- when working with coordinates in Minecraft's world (such as those from the
--- @{gps} API).
+-- [`gps`] API).
--
-- An introduction to vectors can be found on [Wikipedia][wiki].
--
@@ -180,7 +180,7 @@ local vmetatable = {
__eq = vector.equals,
}
---- Construct a new @{Vector} with the given coordinates.
+--- Construct a new [`Vector`] with the given coordinates.
--
-- @tparam number x The X coordinate or direction of the vector.
-- @tparam number y The Y coordinate or direction of the vector.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua
index 62c86d361..848ccfb91 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua
@@ -2,10 +2,10 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
---[[- A @{term.Redirect|terminal redirect} occupying a smaller area of an
+--[[- A [terminal redirect][`term.Redirect`] occupying a smaller area of an
existing terminal. This allows for easy definition of spaces within the display
that can be written/drawn to, then later redrawn/repositioned/etc as need
-be. The API itself contains only one function, @{window.create}, which returns
+be. The API itself contains only one function, [`window.create`], which returns
the windows themselves.
Windows are considered terminal objects - as such, they have access to nearly
@@ -60,11 +60,11 @@ local string_sub = string.sub
--[[- Returns a terminal object that is a space within the specified parent
terminal object. This can then be used (or even redirected to) in the same
-manner as eg a wrapped monitor. Refer to @{term|the term API} for a list of
+manner as eg a wrapped monitor. Refer to [the term API][`term`] for a list of
functions available to it.
-@{term} itself may not be passed as the parent, though @{term.native} is
-acceptable. Generally, @{term.current} or a wrapped monitor will be most
+[`term`] itself may not be passed as the parent, though [`term.native`] is
+acceptable. Generally, [`term.current`] or a wrapped monitor will be most
suitable, though windows may even have other windows assigned as their
parents.
@@ -247,7 +247,7 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
end
end
- --- The window object. Refer to the @{window|module's documentation} for
+ --- The window object. Refer to the [module's documentation][`window`] for
-- a full description.
--
-- @type Window
@@ -454,8 +454,8 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
--
-- @tparam number y The y position of the line to get.
-- @treturn string The textual content of this line.
- -- @treturn string The text colours of this line, suitable for use with @{term.blit}.
- -- @treturn string The background colours of this line, suitable for use with @{term.blit}.
+ -- @treturn string The text colours of this line, suitable for use with [`term.blit`].
+ -- @treturn string The background colours of this line, suitable for use with [`term.blit`].
-- @throws If `y` is not between 1 and this window's height.
-- @since 1.84.0
function window.getLine(y)
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua
index fb35af58b..01ca95ee3 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua
@@ -9,11 +9,11 @@ DFPWM (Dynamic Filter Pulse Width Modulation) is an audio codec designed by Grea
format compared to raw PCM data, only using 1 bit per sample, but is simple enough to simple enough to encode and decode
in real time.
-Typically DFPWM audio is read from @{fs.BinaryReadHandle|the filesystem} or a @{http.Response|a web request} as a
-string, and converted a format suitable for @{speaker.playAudio}.
+Typically DFPWM audio is read from [the filesystem][`fs.BinaryReadHandle`] or a [a web request][`http.Response`] as a
+string, and converted a format suitable for [`speaker.playAudio`].
## Encoding and decoding files
-This modules exposes two key functions, @{make_decoder} and @{make_encoder}, which construct a new decoder or encoder.
+This modules exposes two key functions, [`make_decoder`] and [`make_encoder`], which construct a new decoder or encoder.
The returned encoder/decoder is itself a function, which converts between the two kinds of data.
These encoders and decoders have lots of hidden state, so you should be careful to use the same encoder or decoder for
@@ -95,10 +95,9 @@ end
The returned encoder is itself a function. This function accepts a table of amplitude data between -128 and 127 and
returns the encoded DFPWM data.
-:::caution Reusing encoders
-Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple
-streams, or use different encoders for the same stream, the resulting audio may not sound correct.
-:::
+> [Reusing encoders][!WARNING]
+> Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple
+> streams, or use different encoders for the same stream, the resulting audio may not sound correct.
@treturn function(pcm: { number... }):string The encoder function
@see encode A helper function for encoding an entire file of audio at once.
@@ -138,10 +137,9 @@ end
The returned decoder is itself a function. This function accepts a string and returns a table of amplitudes, each value
between -128 and 127.
-:::caution Reusing decoders
-Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for multiple
-streams, or use different decoders for the same stream, the resulting audio may not sound correct.
-:::
+> [Reusing decoders][!WARNING]
+> Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for
+> multiple streams, or use different decoders for the same stream, the resulting audio may not sound correct.
@treturn function(dfpwm: string):{ number... } The encoder function
@see decode A helper function for decoding an entire file of audio at once.
@@ -167,7 +165,7 @@ local function make_decoder()
local low_pass_charge = 0
local previous_charge, previous_bit = 0, false
- return function (input, output)
+ return function (input)
expect(1, input, "string")
local output, output_n = {}, 0
@@ -200,7 +198,7 @@ end
--[[- A convenience function for decoding a complete file of audio at once.
This should only be used for short files. For larger files, one should read the file in chunks and process it using
-@{make_decoder}.
+[`make_decoder`].
@tparam string input The DFPWM data to convert.
@treturn { number... } The produced amplitude data.
@@ -214,7 +212,7 @@ end
--[[- A convenience function for encoding a complete file of audio at once.
This should only be used for complete pieces of audio. If you are writing writing multiple chunks to the same place,
-you should use an encoder returned by @{make_encoder} instead.
+you should use an encoder returned by [`make_encoder`] instead.
@tparam { number... } input The table of amplitude data.
@treturn string The encoded DFPWM data.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua
index 4b5bf9619..843d02f14 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua
@@ -3,11 +3,11 @@
-- SPDX-License-Identifier: LicenseRef-CCPL
--- A collection of helper methods for working with input completion, such
--- as that require by @{_G.read}.
+-- as that require by [`_G.read`].
--
-- @module cc.completion
-- @see cc.shell.completion For additional helpers to use with
--- @{shell.setCompletionFunction}.
+-- [`shell.setCompletionFunction`].
-- @since 1.85.0
local expect = require "cc.expect".expect
@@ -34,7 +34,7 @@ end
-- @tparam { string... } choices The list of choices to complete from.
-- @tparam[opt] boolean add_space Whether to add a space after the completed item.
-- @treturn { string... } A list of suffixes of matching strings.
--- @usage Call @{_G.read}, completing the names of various animals.
+-- @usage Call [`_G.read`], completing the names of various animals.
--
-- local completion = require "cc.completion"
-- local animals = { "dog", "cat", "lion", "unicorn" }
@@ -76,7 +76,7 @@ local function side(text, add_space)
return choice_impl(text, sides, add_space)
end
---- Complete a @{settings|setting}.
+--- Complete a [setting][`settings`].
--
-- @tparam string text The input string to complete.
-- @tparam[opt] boolean add_space Whether to add a space after the completed settings.
@@ -92,7 +92,7 @@ end
local command_list
---- Complete the name of a Minecraft @{commands|command}.
+--- Complete the name of a Minecraft [command][`commands`].
--
-- @tparam string text The input string to complete.
-- @tparam[opt] boolean add_space Whether to add a space after the completed command.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua
index 02b6c510c..f4cade7f4 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua
@@ -2,7 +2,7 @@
--
-- SPDX-License-Identifier: MPL-2.0
---[[- The @{cc.expect} library provides helper functions for verifying that
+--[[- The [`cc.expect`] library provides helper functions for verifying that
function arguments are well-formed and of the correct type.
@module cc.expect
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua
index 154332f22..8ba116f0f 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua
@@ -5,7 +5,7 @@
--- Read and draw nft ("Nitrogen Fingers Text") images.
--
-- nft ("Nitrogen Fingers Text") is a file format for drawing basic images.
--- Unlike the images that @{paintutils.parseImage} uses, nft supports coloured
+-- Unlike the images that [`paintutils.parseImage`] uses, nft supports coloured
-- text as well as simple coloured pixels.
--
-- @module cc.image.nft
@@ -87,7 +87,7 @@ end
--- Draw an nft image to the screen.
--
--- @tparam table image An image, as returned from @{load} or @{draw}.
+-- @tparam table image An image, as returned from [`load`] or [`parse`].
-- @tparam number xPos The x position to start drawing at.
-- @tparam number xPos The y position to start drawing at.
-- @tparam[opt] term.Redirect target The terminal redirect to draw to. Defaults to the
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua
index 6619bee90..9f320f053 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua
@@ -4,10 +4,9 @@
--[[- A pretty-printer for Lua errors.
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
This consumes a list of messages and "annotations" and displays the error to the
terminal.
@@ -100,7 +99,7 @@ local code_accent = pretty.text("\x95", colours.cyan)
over the underlying source, exposing the following functions:
- `get_pos`: Get the line and column of an opaque position.
- `get_line`: Get the source code for an opaque position.
-@tparam table message The message to display, as produced by @{cc.internal.syntax.errors}.
+@tparam table message The message to display, as produced by [`cc.internal.syntax.errors`].
]]
return function(context, message)
expect(1, context, "table")
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua
index c2def8c61..64156934f 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua
@@ -4,10 +4,9 @@
--[[- Internal tools for working with errors.
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
@local
]]
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua
index 8b03e3c4c..fab51881a 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua
@@ -2,12 +2,11 @@
--
-- SPDX-License-Identifier: MPL-2.0
---[[- Upload a list of files, as received by the @{event!file_transfer} event.
+--[[- Upload a list of files, as received by the [`event!file_transfer`] event.
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
@local
]]
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua
index 2fcf9aa10..1bd652e42 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua
@@ -4,14 +4,13 @@
--[[- The error messages reported by our lexer and parser.
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
This provides a list of factory methods which take source positions and produce
appropriate error messages targeting that location. These error messages can
-then be displayed to the user via @{cc.internal.error_printer}.
+then be displayed to the user via [`cc.internal.error_printer`].
@local
]]
@@ -121,7 +120,7 @@ function errors.unfinished_string(start_pos, end_pos, quote)
end
--[[- A string which ends with an escape sequence (so a literal `"foo\`). This
-is slightly different from @{unfinished_string}, as we don't want to suggest
+is slightly different from [`unfinished_string`], as we don't want to suggest
adding a quote.
@tparam number start_pos The start position of the string.
@@ -467,7 +466,7 @@ function errors.standalone_name(pos)
}
end
---[[- A statement of the form `x.y`. This is similar to @{standalone_name}, but
+--[[- A statement of the form `x.y`. This is similar to [`standalone_name`], but
when the next token is on another line.
@tparam number pos The position right after this name.
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua
index 59125c945..2a69d890f 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua
@@ -4,10 +4,9 @@
--[[- The main entrypoint to our Lua parser
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
@local
]]
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua
index e775d590b..278b2b749 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua
@@ -4,17 +4,16 @@
--[[- A lexer for Lua source code.
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
This module provides utilities for lexing Lua code, returning tokens compatible
-with @{cc.internal.syntax.parser}. While all lexers are roughly the same, there
+with [`cc.internal.syntax.parser`]. While all lexers are roughly the same, there
are some design choices worth drawing attention to:
- - The lexer uses Lua patterns (i.e. @{string.find}) as much as possible,
- trying to avoid @{string.sub} loops except when needed. This allows us to
+ - The lexer uses Lua patterns (i.e. [`string.find`]) as much as possible,
+ trying to avoid [`string.sub`] loops except when needed. This allows us to
move string processing to native code, which ends up being much faster.
- We try to avoid allocating where possible. There are some cases we need to
@@ -178,7 +177,7 @@ end
-- @tparam number start The start position, after the input boundary.
-- @tparam number len The expected length of the boundary. Equal to 1 + the
-- number of `=`.
--- @treturn number|nil The end position, or @{nil} if this is not terminated.
+-- @treturn number|nil The end position, or [`nil`] if this is not terminated.
local function lex_long_str(context, str, start, len)
local pos = start
while true do
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua
index 507f03928..4e60da420 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua
@@ -4,10 +4,9 @@
--[[- A parser for Lua programs and expressions.
-:::warning
-This is an internal module and SHOULD NOT be used in your own code. It may
-be removed or changed at any time.
-:::
+> [!DANGER]
+> This is an internal module and SHOULD NOT be used in your own code. It may
+> be removed or changed at any time.
Most of the code in this module is automatically generated from the Lua grammar,
hence being mostly unreadable!
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua
index d0cdf6c41..7ef6a7950 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua
@@ -5,12 +5,12 @@
--[[- A pretty printer for rendering data structures in an aesthetically
pleasing manner.
-In order to display something using @{cc.pretty}, you build up a series of
-@{Doc|documents}. These behave a little bit like strings; you can concatenate
+In order to display something using [`cc.pretty`], you build up a series of
+[documents][`Doc`]. These behave a little bit like strings; you can concatenate
them together and then print them to the screen.
However, documents also allow you to control how they should be printed. There
-are several functions (such as @{nest} and @{group}) which allow you to control
+are several functions (such as [`nest`] and [`group`]) which allow you to control
the "layout" of the document. When you come to display the document, the 'best'
(most compact) layout is used.
@@ -37,7 +37,7 @@ local expect, field = expect.expect, expect.field
local type, getmetatable, setmetatable, colours, str_write, tostring = type, getmetatable, setmetatable, colours, write, tostring
local debug_info, debug_local = debug.getinfo, debug.getlocal
---- @{table.insert} alternative, but with the length stored inline.
+--- [`table.insert`] alternative, but with the length stored inline.
local function append(out, value)
local n = out.n + 1
out[n], out.n = value, n
@@ -59,10 +59,10 @@ local empty = mk_doc({ tag = "nil" })
--- A document with a single space in it.
local space = mk_doc({ tag = "text", text = " " })
---- A line break. When collapsed with @{group}, this will be replaced with @{empty}.
+--- A line break. When collapsed with [`group`], this will be replaced with [`empty`].
local line = mk_doc({ tag = "line", flat = empty })
---- A line break. When collapsed with @{group}, this will be replaced with @{space}.
+--- A line break. When collapsed with [`group`], this will be replaced with [`space`].
local space_line = mk_doc({ tag = "line", flat = space })
local text_cache = { [""] = empty, [" "] = space, ["\n"] = space_line }
@@ -73,7 +73,7 @@ end
--- Create a new document from a string.
--
--- If your string contains multiple lines, @{group} will flatten the string
+-- If your string contains multiple lines, [`group`] will flatten the string
-- into a single line, with spaces between each line.
--
-- @tparam string text The string to construct a new document with.
@@ -453,7 +453,7 @@ end
--- Pretty-print an arbitrary object, converting it into a document.
--
--- This can then be rendered with @{write} or @{print}.
+-- This can then be rendered with [`write`] or [`print`].
--
-- @param obj The object to pretty-print.
-- @tparam[opt] { function_args = boolean, function_source = boolean } options
@@ -479,7 +479,7 @@ local function pretty(obj, options)
return pretty_impl(obj, actual_options, {})
end
---[[- A shortcut for calling @{pretty} and @{print} together.
+--[[- A shortcut for calling [`pretty`] and [`print`] together.
@param obj The object to pretty-print.
@tparam[opt] { function_args = boolean, function_source = boolean } options
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua
index b6ae8bbee..0edf201f5 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua
@@ -2,8 +2,8 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
---[[- A pure Lua implementation of the builtin @{require} function and
-@{package} library.
+--[[- A pure Lua implementation of the builtin [`require`] function and
+[`package`] library.
Generally you do not need to use this module - it is injected into the every
program's environment. However, it may be useful when building a custom shell or
@@ -11,7 +11,7 @@ when running programs yourself.
@module cc.require
@since 1.88.0
-@see using_require For an introduction on how to use @{require}.
+@see using_require For an introduction on how to use [`require`].
@usage Construct the package and require function, and insert them into a
custom environment.
@@ -110,13 +110,13 @@ local function make_require(package)
end
end
---- Build an implementation of Lua's @{package} library, and a @{require}
+--- Build an implementation of Lua's [`package`] library, and a [`require`]
-- function to load modules within it.
--
-- @tparam table env The environment to load packages into.
-- @tparam string dir The directory that relative packages are loaded from.
--- @treturn function The new @{require} function.
--- @treturn table The new @{package} library.
+-- @treturn function The new [`require`] function.
+-- @treturn table The new [`package`] library.
local function make_package(env, dir)
expect(1, env, "table")
expect(2, dir, "string")
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua
index a701e571c..33963e2ee 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua
@@ -4,16 +4,16 @@
--[[- A collection of helper methods for working with shell completion.
-Most programs may be completed using the @{build} helper method, rather than
+Most programs may be completed using the [`build`] helper method, rather than
manually switching on the argument index.
Note, the helper functions within this module do not accept an argument index,
-and so are not directly usable with the @{shell.setCompletionFunction}. Instead,
-wrap them using @{build}, or your own custom function.
+and so are not directly usable with the [`shell.setCompletionFunction`]. Instead,
+wrap them using [`build`], or your own custom function.
@module cc.shell.completion
@since 1.85.0
-@see cc.completion For more general helpers, suitable for use with @{_G.read}.
+@see cc.completion For more general helpers, suitable for use with [`_G.read`].
@see shell.setCompletionFunction
@usage Register a completion handler for example.lua which prompts for a
@@ -135,15 +135,15 @@ end
--[[- A helper function for building shell completion arguments.
This accepts a series of single-argument completion functions, and combines
-them into a function suitable for use with @{shell.setCompletionFunction}.
+them into a function suitable for use with [`shell.setCompletionFunction`].
-@tparam nil|table|function ... Every argument to @{build} represents an argument
+@tparam nil|table|function ... Every argument to [`build`] represents an argument
to the program you wish to complete. Each argument can be one of three types:
- `nil`: This argument will not be completed.
- A function: This argument will be completed with the given function. It is
- called with the @{shell} object, the string to complete and the arguments
+ called with the [`shell`] object, the string to complete and the arguments
before this one.
- A table: This acts as a more powerful version of the function case. The table
@@ -197,12 +197,12 @@ return {
programWithArgs = programWithArgs,
-- Re-export various other functions
- help = wrap(help.completeTopic), --- Wraps @{help.completeTopic} as a @{build} compatible function.
- choice = wrap(completion.choice), --- Wraps @{cc.completion.choice} as a @{build} compatible function.
- peripheral = wrap(completion.peripheral), --- Wraps @{cc.completion.peripheral} as a @{build} compatible function.
- side = wrap(completion.side), --- Wraps @{cc.completion.side} as a @{build} compatible function.
- setting = wrap(completion.setting), --- Wraps @{cc.completion.setting} as a @{build} compatible function.
- command = wrap(completion.command), --- Wraps @{cc.completion.command} as a @{build} compatible function.
+ help = wrap(help.completeTopic), --- Wraps [`help.completeTopic`] as a [`build`] compatible function.
+ choice = wrap(completion.choice), --- Wraps [`cc.completion.choice`] as a [`build`] compatible function.
+ peripheral = wrap(completion.peripheral), --- Wraps [`cc.completion.peripheral`] as a [`build`] compatible function.
+ side = wrap(completion.side), --- Wraps [`cc.completion.side`] as a [`build`] compatible function.
+ setting = wrap(completion.setting), --- Wraps [`cc.completion.setting`] as a [`build`] compatible function.
+ command = wrap(completion.command), --- Wraps [`cc.completion.command`] as a [`build`] compatible function.
build = build,
}
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua
index 11bf4cad4..e28356d85 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua
@@ -13,7 +13,7 @@ local expect = (require and require("cc.expect") or dofile("rom/modules/main/cc/
--[[- Wraps a block of text, so that each line fits within the given width.
This may be useful if you want to wrap text before displaying it to a
-@{monitor} or @{printer} without using @{_G.print|print}.
+[`monitor`] or [`printer`] without using [print][`_G.print`].
@tparam string text The string to wrap.
@tparam[opt] number width The width to constrain to, defaults to the width of
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua
index 8ab5b7bcf..f2cd68b88 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua
@@ -6,17 +6,17 @@
--
-- When multiple programs are running, it displays a tab bar at the top of the
-- screen, which allows you to switch between programs. New programs can be
--- launched using the `fg` or `bg` programs, or using the @{shell.openTab} and
--- @{multishell.launch} functions.
+-- launched using the `fg` or `bg` programs, or using the [`shell.openTab`] and
+-- [`multishell.launch`] functions.
--
-- Each process is identified by its ID, which corresponds to its position in
-- the tab list. As tabs may be opened and closed, this ID is _not_ constant
-- over a program's run. As such, be careful not to use stale IDs.
--
--- As with @{shell}, @{multishell} is not a "true" API. Instead, it is a
+-- As with [`shell`], [`multishell`] is not a "true" API. Instead, it is a
-- standard program, which launches a shell and injects its API into the shell's
-- environment. This API is not available in the global environment, and so is
--- not available to @{os.loadAPI|APIs}.
+-- not available to [APIs][`os.loadAPI`].
--
-- @module[module] multishell
-- @since 1.6
@@ -222,7 +222,7 @@ local multishell = {} --- @export
--- Get the currently visible process. This will be the one selected on
-- the tab bar.
--
--- Note, this is different to @{getCurrent}, which returns the process which is
+-- Note, this is different to [`getCurrent`], which returns the process which is
-- currently executing.
--
-- @treturn number The currently visible process's index.
@@ -235,7 +235,7 @@ end
--
-- @tparam number n The process index to switch to.
-- @treturn boolean If the process was changed successfully. This will
--- return @{false} if there is no process with this id.
+-- return [`false`] if there is no process with this id.
-- @see getFocus
function multishell.setFocus(n)
expect(1, n, "number")
@@ -250,9 +250,9 @@ end
--- Get the title of the given tab.
--
-- This starts as the name of the program, but may be changed using
--- @{multishell.setTitle}.
+-- [`multishell.setTitle`].
-- @tparam number n The process index.
--- @treturn string|nil The current process title, or @{nil} if the
+-- @treturn string|nil The current process title, or [`nil`] if the
-- process doesn't exist.
function multishell.getTitle(n)
expect(1, n, "number")
diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua
index 96c75ad9f..eedf27eb0 100644
--- a/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua
+++ b/projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua
@@ -4,26 +4,26 @@
--[[- The shell API provides access to CraftOS's command line interface.
-It allows you to @{run|start programs}, @{setCompletionFunction|add completion
-for a program}, and much more.
+It allows you to [start programs][`run`], [add completion for a
+program][`setCompletionFunction`], and much more.
-@{shell} is not a "true" API. Instead, it is a standard program, which injects
+[`shell`] is not a "true" API. Instead, it is a standard program, which injects
its API into the programs that it launches. This allows for multiple shells to
run at the same time, but means that the API is not available in the global
-environment, and so is unavailable to other @{os.loadAPI|APIs}.
+environment, and so is unavailable to other [APIs][`os.loadAPI`].
## Programs and the program path
When you run a command with the shell, either from the prompt or
-@{shell.run|from Lua code}, the shell API performs several steps to work out
+[from Lua code][`shell.run`], the shell API performs several steps to work out
which program to run:
- 1. Firstly, the shell attempts to resolve @{shell.aliases|aliases}. This allows
+ 1. Firstly, the shell attempts to resolve [aliases][`shell.aliases`]. This allows
us to use multiple names for a single command. For example, the `list`
program has two aliases: `ls` and `dir`. When you write `ls /rom`, that's
expanded to `list /rom`.
2. Next, the shell attempts to find where the program actually is. For this, it
- uses the @{shell.path|program path}. This is a colon separated list of
+ uses the [program path][`shell.path`]. This is a colon separated list of
directories, each of which is checked to see if it contains the program.
`list` or `list.lua` doesn't exist in `.` (the current directory), so the
@@ -192,7 +192,7 @@ end
--- Run a program with the supplied arguments.
--
--- Unlike @{shell.run}, each argument is passed to the program verbatim. While
+-- Unlike [`shell.run`], each argument is passed to the program verbatim. While
-- `shell.run("echo", "b c")` runs `echo` with `b` and `c`,
-- `shell.execute("echo", "b c")` runs `echo` with a single argument `b c`.
--
@@ -276,7 +276,7 @@ function shell.exit()
end
--- Return the current working directory. This is what is displayed before the
--- `> ` of the shell prompt, and is used by @{shell.resolve} to handle relative
+-- `> ` of the shell prompt, and is used by [`shell.resolve`] to handle relative
-- paths.
--
-- @treturn string The current working directory.
@@ -313,10 +313,10 @@ function shell.path()
return sPath
end
---- Set the @{path|current program path}.
+--- Set the [current program path][`path`].
--
-- Be careful to prefix directories with a `/`. Otherwise they will be searched
--- for from the @{shell.dir|current directory}, rather than the computer's root.
+-- for from the [current directory][`shell.dir`], rather than the computer's root.
--
-- @tparam string path The new program path.
-- @since 1.2
@@ -327,8 +327,8 @@ end
--- Resolve a relative path to an absolute path.
--
--- The @{fs} and @{io} APIs work using absolute paths, and so we must convert
--- any paths relative to the @{dir|current directory} to absolute ones. This
+-- The [`fs`] and [`io`] APIs work using absolute paths, and so we must convert
+-- any paths relative to the [current directory][`dir`] to absolute ones. This
-- does nothing when the path starts with `/`.
--
-- @tparam string path The path to resolve.
@@ -357,10 +357,10 @@ local function pathWithExtension(_sPath, _sExt)
return _sPath .. "." .. _sExt
end
---- Resolve a program, using the @{path|program path} and list of @{aliases|aliases}.
+--- Resolve a program, using the [program path][`path`] and list of [aliases][`aliases`].
--
-- @tparam string command The name of the program
--- @treturn string|nil The absolute path to the program, or @{nil} if it could
+-- @treturn string|nil The absolute path to the program, or [`nil`] if it could
-- not be found.
-- @since 1.2
-- @changed 1.80pr1 Now searches for files with and without the `.lua` extension.
@@ -406,7 +406,7 @@ function shell.resolveProgram(command)
return nil
end
---- Return a list of all programs on the @{shell.path|path}.
+--- Return a list of all programs on the [path][`shell.path`].
--
-- @tparam[opt] boolean include_hidden Include hidden files. Namely, any which
-- start with `.`.
@@ -518,7 +518,7 @@ end
-- completed to `ls rom/`.
--
-- Completion handlers for your program may be registered with
--- @{shell.setCompletionFunction}.
+-- [`shell.setCompletionFunction`].
--
-- @tparam string sLine The input to complete.
-- @treturn { string }|nil The list of possible completions.
@@ -614,7 +614,7 @@ end
--- Get a table containing all completion functions.
--
-- This should only be needed when building custom shells. Use
--- @{setCompletionFunction} to add a completion function.
+-- [`setCompletionFunction`] to add a completion function.
--
-- @treturn { [string] = { fnComplete = function } } A table mapping the
-- absolute path of programs, to their completion functions.
@@ -676,12 +676,12 @@ function shell.aliases()
end
if multishell then
- --- Open a new @{multishell} tab running a command.
+ --- Open a new [`multishell`] tab running a command.
--
- -- This behaves similarly to @{shell.run}, but instead returns the process
+ -- This behaves similarly to [`shell.run`], but instead returns the process
-- index.
--
- -- This function is only available if the @{multishell} API is.
+ -- This function is only available if the [`multishell`] API is.
--
-- @tparam string ... The command line to run.
-- @see shell.run
@@ -706,7 +706,7 @@ if multishell then
end
end
- --- Switch to the @{multishell} tab with the given index.
+ --- Switch to the [`multishell`] tab with the given index.
--
-- @tparam number id The tab to switch to.
-- @see multishell.setFocus
diff --git a/projects/core/src/test/resources/test-rom/mcfly.lua b/projects/core/src/test/resources/test-rom/mcfly.lua
index 7eba0c5dc..971fddb3f 100644
--- a/projects/core/src/test/resources/test-rom/mcfly.lua
+++ b/projects/core/src/test/resources/test-rom/mcfly.lua
@@ -55,7 +55,7 @@ local function default_stub() end
-- @tparam string key The variable to stub
-- @param[opt] value The value to stub it with. If this is a function, one can
-- use the various stub expectation methods to determine what it was called
--- with. Defaults to an empty function - pass @{nil} in explicitly to set the
+-- with. Defaults to an empty function - pass [`nil`] in explicitly to set the
-- value to nil.
-- @treturn Stub The resulting stub
local function stub(tbl, key, ...)
diff --git a/projects/core/src/test/resources/test-rom/spec/modules/cc/internal/syntax/syntax_helpers.lua b/projects/core/src/test/resources/test-rom/spec/modules/cc/internal/syntax/syntax_helpers.lua
index 87022065d..887139c8d 100644
--- a/projects/core/src/test/resources/test-rom/spec/modules/cc/internal/syntax/syntax_helpers.lua
+++ b/projects/core/src/test/resources/test-rom/spec/modules/cc/internal/syntax/syntax_helpers.lua
@@ -27,7 +27,7 @@ end
--[[- Run a parser on an input string, capturing its output.
This uses a simplified method of displaying errors (compared with
-@{cc.internal.error_printer}), which is suitable for printing to a file.
+[`cc.internal.error_printer`]), which is suitable for printing to a file.
@tparam string input The input string to parse.
@tparam[opt=false] boolean print_tokens Whether to print each token as its parsed.
diff --git a/projects/core/src/testFixtures/java/dan200/computercraft/test/core/StructuralEqualities.java b/projects/core/src/testFixtures/java/dan200/computercraft/test/core/StructuralEqualities.java
new file mode 100644
index 000000000..a35a4a04c
--- /dev/null
+++ b/projects/core/src/testFixtures/java/dan200/computercraft/test/core/StructuralEqualities.java
@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2023 The CC: Tweaked Developers
+//
+// SPDX-License-Identifier: MPL-2.0
+
+package dan200.computercraft.test.core;
+
+import org.hamcrest.Description;
+import org.hamcrest.TypeSafeMatcher;
+
+import javax.annotation.Nullable;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Function;
+
+/**
+ * Concrete implementations for {@link StructuralEquality}.
+ */
+final class StructuralEqualities {
+ static final DefaultEquality DEFAULT = new DefaultEquality();
+
+ private StructuralEqualities() {
+ }
+
+ static