From d449cbc3e71d84babed6af34c423408a91853cab Mon Sep 17 00:00:00 2001 From: Jonathan Coates Date: Wed, 9 Sep 2026 10:07:36 +0100 Subject: [PATCH] Some basic datapack documentation --- doc/reference/breaking_changes.md | 3 +- doc/reference/data_pack.md | 67 +++++++++++++++++++ doc/reference/startup.md | 3 +- .../computercraft/api/ComputerCraftTags.java | 38 +++++++++++ .../computercraft/core/apis/RedstoneAPI.java | 2 +- .../computerthread/ComputerThread.java | 2 +- .../data/computercraft/lua/rom/help/http.txt | 2 +- .../computercraft/lua/rom/help/pastebin.txt | 2 +- .../data/computercraft/lua/rom/help/wget.txt | 2 +- 9 files changed, 112 insertions(+), 9 deletions(-) create mode 100644 doc/reference/data_pack.md diff --git a/doc/reference/breaking_changes.md b/doc/reference/breaking_changes.md index b7327bb57..ba8cdbd5a 100644 --- a/doc/reference/breaking_changes.md +++ b/doc/reference/breaking_changes.md @@ -63,7 +63,7 @@ as documentation for breaking changes and "gotchas" one should look out for betw - Due to how data packs are read by CC: Tweaked, you may need to use the `/reload` command to see changes to your pack show up on the computer. - See [the example datapack][datapack-example] for how to get started. + See [`data_pack`] for more information. - Turtles can now be waterlogged and move "through" water sources rather than breaking them. @@ -79,4 +79,3 @@ as documentation for breaking changes and "gotchas" one should look out for betw [flattening]: https://minecraft.wiki/w/Java_Edition_1.13/Flattening [legal_data_pack]: https://minecraft.wiki/w/Tutorials/Creating_a_data_pack#Legal_characters -[datapack-example]: https://github.com/cc-tweaked/datapack-example "An example datapack for CC: Tweaked" diff --git a/doc/reference/data_pack.md b/doc/reference/data_pack.md new file mode 100644 index 000000000..d6621a050 --- /dev/null +++ b/doc/reference/data_pack.md @@ -0,0 +1,67 @@ +--- +module: [kind=reference] data_pack +--- + + + +# Data packs +CC: Tweaked allows customising and extending many of its features via [data packs][data pack wiki], such as adding new +programs to the ROM, or providing new turtle tools. This page serves as a reference for CC:T's data pack functionality. + +> [Data pack compatibility][!NOTE] +> +> Unlike other parts of this documentation, the format of data packs change between Minecraft versions. Make sure you're +> using the right documentation for your Minecraft version. +> +> - [Minecraft 1.20.1](/mc-1.20.x/reference/data_pack.html) +> - [Minecraft 1.21.1](/mc-1.21.x/reference/data_pack.html) +> - [Minecraft 26.2](/mc-26.2/reference/data_pack.html) + +In addition to this documentation, we also provide an [online data pack builder][data pack builder] and an +[example/template data pack][data pack example]. + +## CraftOS ROM +Datapacks can be used to add or overwrite files in CraftOS's ROM, allowing you to add new programs or modules, or adjust +the behaviour of existing ones. Files should be placed in `data/computercraft/lua/rom`. For example, a datapack +containing `data/computercraft/lua/rom/programs/example.lua` will add a new program `example`. + +> [File naming][!WARNING] +> +> Data packs [impose some restrictions on file names][legal data pack]. As a result, all file and directory names must +> be lower case. + + - Files under `rom/autorun` will be run on computer startup. + - Files under `rom/modules/main` can be loaded via `require`. + - Files located in `rom/apis/` will be loaded via `os.loadAPI` on startup. Similarly: + - Files under `rom/apis/http` will be loaded if the HTTP API is enabled. + - Files under `rom/apis/turtle` will be loaded on all turtles. + - Files under `rom/apis/pocket` will be loaded on all pocket computers. + - Files under `rom/apis/command` will be loaded on all command computers. + +## Tags +CC:T provides several [block][block tags] and [item][item tags] tags. While most tags are just used to group related +blocks/items (e.g. `computercraft:turtles` is the list of all turtles), several can be extended by data packs to tweak +functionality: + + - `computercraft:turtle_can_place` item tag: This tag lists items turtles can use with [`turtle.place`]. By default + this contains glass bottles and boats, + - `computercraft:turtle_can_use` block tag: This tag lists blocks turtles can interact with [`turtle.place`]. By + default this contains beehives, cauldrons and the composter. The [data pack builder] has options for adding + levers/buttons and modems to this list, allowing turtles to toggle them. + - `computercraft:always_breakable` block tag: All turtle tools are capable of breaking instant-break blocks, such as + saplings. This tag specifies additional blocks that can be broken by all tools. By default, this includes leaves, + bamboo and bamboo saplings. + - `computercraft:turtle_shovel_harvestable`, `computercraft:turtle_sword_harvestable`, + `computercraft:turtle_hoe_harvestable` block tags: These tags specify which blocks can be broken by the shovel, sword + and hoe respectively. + +[block tags]: ../../javadoc/dan200/computercraft/api/ComputerCraftTags.Blocks.html "ComputerCraftTags.Blocks javadoc" +[data pack builder]: https://datapacks.madefor.cc/ +[data pack example]: https://github.com/cc-tweaked/datapack-example "An example data pack for CC: Tweaked" +[data pack wiki]: https://minecraft.wiki/w/Data_pack "Data pack on the Minecraft wiki" +[item tags]: ../../javadoc/dan200/computercraft/api/ComputerCraftTags.Items.html "ComputerCraftTags.Items javadoc" +[legal data pack]: https://minecraft.wiki/w/Tutorials/Creating_a_data_pack#Legal_characters diff --git a/doc/reference/startup.md b/doc/reference/startup.md index 23292fe54..ad546f10e 100644 --- a/doc/reference/startup.md +++ b/doc/reference/startup.md @@ -15,8 +15,7 @@ When a computer turns on, it searches for files to run as part of the startup pr For information about creating a basic startup file, see [`guide!startup`]. 1. `/rom/autorun`: Computers first look in the `/rom/autorun` folder, and run every file in that folder. This folder is - empty by default, but may be extended by datapacks or other mods. See the [example - datapack](https://github.com/cc-tweaked/datapack-example) for an example. + empty by default, but may be extended by datapacks or other mods. See [`data_pack`] for more information. 2. If the `shell.allow_disk_startup` [setting][`settings`] is `true`, then connected disk drives are searched for a `startup` file, `startup.lua` file, or `startup/` directory. The first disk containing these files will be used for diff --git a/projects/common-api/src/main/java/dan200/computercraft/api/ComputerCraftTags.java b/projects/common-api/src/main/java/dan200/computercraft/api/ComputerCraftTags.java index f8d446dc8..4bab76ce3 100644 --- a/projects/common-api/src/main/java/dan200/computercraft/api/ComputerCraftTags.java +++ b/projects/common-api/src/main/java/dan200/computercraft/api/ComputerCraftTags.java @@ -20,10 +20,29 @@ import net.minecraft.world.phys.BlockHitResult; * Tags provided by ComputerCraft. */ public class ComputerCraftTags { + /** + * Item tags provided by ComputerCraft. + */ public static class Items { + /** + * All computers. This includes normal, advanced, and command computers. It does not include turtles or pocket + * computers. + */ public static final TagKey COMPUTER = make("computer"); + + /** + * All turtles. This includes normal and advanced turtles. + */ public static final TagKey TURTLE = make("turtle"); + + /** + * All modems. This includes the multi-part and full-block modem. + */ public static final TagKey WIRED_MODEM = make("wired_modem"); + + /** + * All monitors. This includes normal and advanced monitors. + */ public static final TagKey MONITOR = make("monitor"); /** @@ -54,10 +73,29 @@ public class ComputerCraftTags { } } + /** + * Block tags provided by ComputerCraft. + */ public static class Blocks { + /** + * All computers. This includes normal, advanced, and command computers. It does not include turtles or pocket + * computers. + */ public static final TagKey COMPUTER = make("computer"); + + /** + * All turtles. This includes normal and advanced turtles. + */ public static final TagKey TURTLE = make("turtle"); + + /** + * All modems. This includes the multi-part and full-block modem. + */ public static final TagKey WIRED_MODEM = make("wired_modem"); + + /** + * All monitors. This includes normal and advanced monitors. + */ public static final TagKey MONITOR = make("monitor"); /** 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 212afca30..0ef8589d6 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 @@ -18,7 +18,7 @@ import java.util.List; * - Binary input/output ({@link #setOutput}/{@link #getInput}): These simply check if a redstone wire has any input or * output. A signal strength of 1 and 15 are treated the same. * - Analogue input/output ({@link #setAnalogOutput}/{@link #getAnalogInput}): These work with the actual signal - * strength of the redstone wired, from 0 to 15. + * strength of the redstone wires, 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`]. diff --git a/projects/core/src/main/java/dan200/computercraft/core/computer/computerthread/ComputerThread.java b/projects/core/src/main/java/dan200/computercraft/core/computer/computerthread/ComputerThread.java index bc2a735c2..1a819dbad 100644 --- a/projects/core/src/main/java/dan200/computercraft/core/computer/computerthread/ComputerThread.java +++ b/projects/core/src/main/java/dan200/computercraft/core/computer/computerthread/ComputerThread.java @@ -291,7 +291,7 @@ public final class ComputerThread implements ComputerScheduler { * * @param executor The computer to execute work on. */ - void queue(ExecutorImpl executor) { + private void queue(ExecutorImpl executor) { computerLock.lock(); try { if (state.get() != RUNNING) throw new IllegalStateException("ComputerThread is no longer running"); diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/help/http.txt b/projects/core/src/main/resources/data/computercraft/lua/rom/help/http.txt index 27d2be100..290aabc51 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/help/http.txt +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/help/http.txt @@ -5,5 +5,5 @@ http.request( url, [postData], [headers] ) http.get( url, [headers] ) http.post( url, postData, [headers] ) -The HTTP API may be disabled in ComputerCraft.cfg +The HTTP API may be disabled in the server config. A period of time after a http.request() call is made, a "http_success" or "http_failure" event will be raised. Arguments are the url and a file handle if successful. Arguments are nil, an error message, and (optionally) a file handle if the request failed. http.get() and http.post() block until this event fires instead. diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/help/pastebin.txt b/projects/core/src/main/resources/data/computercraft/lua/rom/help/pastebin.txt index 8f5589828..3ecf5f4e5 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/help/pastebin.txt +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/help/pastebin.txt @@ -1,5 +1,5 @@ pastebin is a program for uploading files to and downloading files from pastebin.com. This is useful for sharing programs with other players. -The HTTP API must be enabled in ComputerCraft.cfg to use this program. +The HTTP API must be enabled in the server config to use this program. ex: "pastebin put foo" will upload the file "foo" to pastebin.com, and print the URL. diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/help/wget.txt b/projects/core/src/main/resources/data/computercraft/lua/rom/help/wget.txt index 65e580c08..e940f5cc7 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/help/wget.txt +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/help/wget.txt @@ -1,6 +1,6 @@ wget is a program for downloading files from the internet. This is useful for downloading programs created by other players. If no filename is specified wget will try to determine the filename from the URL by stripping any anchors, parameters and trailing slashes and then taking everything remaining after the last slash. -The HTTP API must be enabled in ComputerCraft.cfg to use this program. +The HTTP API must be enabled in the server config to use this program. ex: "wget http://pastebin.com/raw/CxaWmPrX test" will download the file from the URL http://pastebin.com/raw/CxaWmPrX, and save it as "test". "wget http://example.org/test.lua/?foo=bar#qzu" will download the file from the URL http://example.org/test.lua/?foo=bar#qzu and save it as "test.lua"