mirror of
https://github.com/SquidDev-CC/CC-Tweaked
synced 2025-08-28 00:12:16 +00:00
Remove CC: Tweaked doc files.
Must've included these in a merge on accident. No reason for us to have them right now.
This commit is contained in:
Toad-Dev
parent
9c00124d38
commit
af863469e6
@ -1,21 +0,0 @@
|
||||
---
|
||||
module: [kind=event] alarm
|
||||
see: os.setAlarm To start an alarm.
|
||||
---
|
||||
|
||||
The @{timer} event is fired when an alarm started with @{os.setAlarm} completes.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The ID of the alarm that finished.
|
||||
|
||||
## Example
|
||||
Starts a timer and then prints its ID:
|
||||
```lua
|
||||
local alarmID = os.setAlarm(os.time() + 0.05)
|
||||
local event, id
|
||||
repeat
|
||||
event, id = os.pullEvent("alarm")
|
||||
until id == alarmID
|
||||
print("Alarm with ID " .. id .. " was fired")
|
||||
```
|
||||
@ -1,24 +0,0 @@
|
||||
---
|
||||
module: [kind=event] char
|
||||
see: key To listen to any key press.
|
||||
---
|
||||
|
||||
The @{char} event is fired when a character is _typed_ on the keyboard.
|
||||
|
||||
The @{char} event is different to a key press. Sometimes multiple key presses may result in one character being
|
||||
typed (for instance, on some European keyboards). Similarly, some keys (e.g. <kbd>Ctrl</kbd>) do not have any
|
||||
corresponding character. The @{key} should be used if you want to listen to key presses themselves.
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The string representing the character that was pressed.
|
||||
|
||||
|
||||
## Example
|
||||
Prints each character the user presses:
|
||||
```lua
|
||||
while true do
|
||||
local event, character = os.pullEvent("char")
|
||||
print(character .. " was pressed.")
|
||||
end
|
||||
```
|
||||
@ -1,18 +0,0 @@
|
||||
---
|
||||
module: [kind=event] computer_command
|
||||
---
|
||||
|
||||
The @{computer_command} event is fired when the `/computercraft queue` command is run for the current computer.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
... @{string}: The arguments passed to the command.
|
||||
|
||||
## Example
|
||||
Prints the contents of messages sent:
|
||||
```lua
|
||||
while true do
|
||||
local event = {os.pullEvent("computer_command")}
|
||||
print("Received message:", table.unpack(event, 2))
|
||||
end
|
||||
```
|
||||
@ -1,19 +0,0 @@
|
||||
---
|
||||
module: [kind=event] disk
|
||||
see: disk_eject For the event sent when a disk is removed.
|
||||
---
|
||||
|
||||
The @{disk} event is fired when a disk is inserted into an adjacent or networked disk drive.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side of the disk drive that had a disk inserted.
|
||||
|
||||
## Example
|
||||
Prints a message when a disk is inserted:
|
||||
```lua
|
||||
while true do
|
||||
local event, side = os.pullEvent("disk")
|
||||
print("Inserted a disk on side " .. side)
|
||||
end
|
||||
```
|
||||
@ -1,19 +0,0 @@
|
||||
---
|
||||
module: [kind=event] disk_eject
|
||||
see: disk For the event sent when a disk is inserted.
|
||||
---
|
||||
|
||||
The @{disk_eject} event is fired when a disk is removed from an adjacent or networked disk drive.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side of the disk drive that had a disk removed.
|
||||
|
||||
## Example
|
||||
Prints a message when a disk is removed:
|
||||
```lua
|
||||
while true do
|
||||
local event, side = os.pullEvent("disk_eject")
|
||||
print("Removed a disk on side " .. side)
|
||||
end
|
||||
```
|
||||
@ -1,14 +0,0 @@
|
||||
---
|
||||
module: [kind=event] http_check
|
||||
see: http.checkURLAsync To check a URL asynchronously.
|
||||
---
|
||||
|
||||
The @{http_check} event is fired when a URL check finishes.
|
||||
|
||||
This event is normally handled inside @{http.checkURL}, but it can still be seen when using @{http.checkURLAsync}.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL requested to be checked.
|
||||
3. @{boolean}: Whether the check succeeded.
|
||||
4. @{string|nil}: If the check failed, a reason explaining why the check failed.
|
||||
@ -1,39 +0,0 @@
|
||||
---
|
||||
module: [kind=event] http_failure
|
||||
see: http.request To send an HTTP request.
|
||||
---
|
||||
|
||||
The @{http_failure} event is fired when an HTTP request fails.
|
||||
|
||||
This event is normally handled inside @{http.get} and @{http.post}, but it can still be seen when using @{http.request}.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL of the site requested.
|
||||
3. @{string}: An error describing the failure.
|
||||
4. @{http.Response|nil}: A response handle if the connection succeeded, but the server's response indicated failure.
|
||||
|
||||
## Example
|
||||
Prints an error why the website cannot be contacted:
|
||||
```lua
|
||||
local myURL = "https://does.not.exist.tweaked.cc"
|
||||
http.request(myURL)
|
||||
local event, url, err
|
||||
repeat
|
||||
event, url, err = os.pullEvent("http_failure")
|
||||
until url == myURL
|
||||
print("The URL " .. url .. " could not be reached: " .. err)
|
||||
```
|
||||
|
||||
Prints the contents of a webpage that does not exist:
|
||||
```lua
|
||||
local myURL = "https://tweaked.cc/this/does/not/exist"
|
||||
http.request(myURL)
|
||||
local event, url, err, handle
|
||||
repeat
|
||||
event, url, err, handle = os.pullEvent("http_failure")
|
||||
until url == myURL
|
||||
print("The URL " .. url .. " could not be reached: " .. err)
|
||||
print(handle.getResponseCode())
|
||||
handle.close()
|
||||
```
|
||||
@ -1,27 +0,0 @@
|
||||
---
|
||||
module: [kind=event] http_success
|
||||
see: http.request To make an HTTP request.
|
||||
---
|
||||
|
||||
The @{http_success} event is fired when an HTTP request returns successfully.
|
||||
|
||||
This event is normally handled inside @{http.get} and @{http.post}, but it can still be seen when using @{http.request}.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL of the site requested.
|
||||
3. @{http.Response}: The handle for the response text.
|
||||
|
||||
## Example
|
||||
Prints the content of a website (this may fail if the request fails):
|
||||
```lua
|
||||
local myURL = "https://tweaked.cc/"
|
||||
http.request(myURL)
|
||||
local event, url, handle
|
||||
repeat
|
||||
event, url, handle = os.pullEvent("http_success")
|
||||
until url == myURL
|
||||
print("Contents of " .. url .. ":")
|
||||
print(handle.readAll())
|
||||
handle.close()
|
||||
```
|
||||
@ -1,26 +0,0 @@
|
||||
---
|
||||
module: [kind=event] key
|
||||
---
|
||||
|
||||
This event is fired when any key is pressed while the terminal is focused.
|
||||
|
||||
This event returns a numerical "key code" (for instance, <kbd>F1</kbd> is 290). This value may vary between versions and
|
||||
so it is recommended to use the constants in the @{keys} API rather than hard coding numeric values.
|
||||
|
||||
If the button pressed represented a printable character, then the @{key} event will be followed immediately by a @{char}
|
||||
event. If you are consuming text input, use a @{char} event instead!
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The numerical key value of the key pressed.
|
||||
3. @{boolean}: Whether the key event was generated while holding the key (@{true}), rather than pressing it the first time (@{false}).
|
||||
|
||||
## Example
|
||||
Prints each key when the user presses it, and if the key is being held.
|
||||
|
||||
```lua
|
||||
while true do
|
||||
local event, key, is_held = os.pullEvent("key")
|
||||
print(("%s held=%s"):format(keys.getName(key), is_held))
|
||||
end
|
||||
```
|
||||
@ -1,24 +0,0 @@
|
||||
---
|
||||
module: [kind=event] key_up
|
||||
see: keys For a lookup table of the given keys.
|
||||
---
|
||||
|
||||
Fired whenever a key is released (or the terminal is closed while a key was being pressed).
|
||||
|
||||
This event returns a numerical "key code" (for instance, <kbd>F1</kbd> is 290). This value may vary between versions and
|
||||
so it is recommended to use the constants in the @{keys} API rather than hard coding numeric values.
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The numerical key value of the key pressed.
|
||||
|
||||
## Example
|
||||
Prints each key released on the keyboard whenever a @{key_up} event is fired.
|
||||
|
||||
```lua
|
||||
while true do
|
||||
local event, key = os.pullEvent("key_up")
|
||||
local name = keys.getName(key) or "unknown key"
|
||||
print(name .. " was released.")
|
||||
end
|
||||
```
|
||||
@ -1,26 +0,0 @@
|
||||
---
|
||||
module: [kind=event] modem_message
|
||||
---
|
||||
|
||||
The @{modem_message} event is fired when a message is received on an open channel on any @{modem}.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side of the modem that received the message.
|
||||
3. @{number}: The channel that the message was sent on.
|
||||
4. @{number}: The reply channel set by the sender.
|
||||
5. @{any}: The message as sent by the sender.
|
||||
6. @{number}: The distance between the sender and the receiver, in blocks.
|
||||
|
||||
## Example
|
||||
Wraps a @{modem} peripheral, opens channel 0 for listening, and prints all received messages.
|
||||
|
||||
```lua
|
||||
local modem = peripheral.find("modem") or error("No modem attached", 0)
|
||||
modem.open(0)
|
||||
|
||||
while true do
|
||||
local event, side, channel, replyChannel, message, distance = os.pullEvent("modem_message")
|
||||
print(("Message received on side %s on channel %d (reply to %d) from %f blocks away with message %s"):format(side, channel, replyChannel, distance, tostring(message)))
|
||||
end
|
||||
```
|
||||
@ -1,18 +0,0 @@
|
||||
---
|
||||
module: [kind=event] monitor_resize
|
||||
---
|
||||
|
||||
The @{monitor_resize} event is fired when an adjacent or networked monitor's size is changed.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side or network ID of the monitor that resized.
|
||||
|
||||
## Example
|
||||
Prints a message when a monitor is resized:
|
||||
```lua
|
||||
while true do
|
||||
local event, side = os.pullEvent("monitor_resize")
|
||||
print("The monitor on side " .. side .. " was resized.")
|
||||
end
|
||||
```
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
module: [kind=event] monitor_touch
|
||||
---
|
||||
|
||||
The @{monitor_touch} event is fired when an adjacent or networked Advanced Monitor is right-clicked.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side or network ID of the monitor that was touched.
|
||||
3. @{number}: The X coordinate of the touch, in characters.
|
||||
4. @{number}: The Y coordinate of the touch, in characters.
|
||||
|
||||
## Example
|
||||
Prints a message when a monitor is touched:
|
||||
```lua
|
||||
while true do
|
||||
local event, side, x, y = os.pullEvent("monitor_touch")
|
||||
print("The monitor on side " .. side .. " was touched at (" .. x .. ", " .. y .. ")")
|
||||
end
|
||||
```
|
||||
@ -1,34 +0,0 @@
|
||||
---
|
||||
module: [kind=event] mouse_click
|
||||
---
|
||||
|
||||
This event is fired when the terminal is clicked with a mouse. This event is only fired on advanced computers (including
|
||||
advanced turtles and pocket computers).
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The mouse button that was clicked.
|
||||
3. @{number}: The X-coordinate of the click.
|
||||
4. @{number}: The Y-coordinate of the click.
|
||||
|
||||
## Mouse buttons
|
||||
Several mouse events (@{mouse_click}, @{mouse_up}, @{mouse_scroll}) contain a "mouse button" code. This takes a
|
||||
numerical value depending on which button on your mouse was last pressed when this event occurred.
|
||||
|
||||
<table class="pretty-table">
|
||||
<!-- Our markdown parser doesn't work on tables!? Guess I'll have to roll my own soonish :/. -->
|
||||
<tr><th>Button code</th><th>Mouse button</th></tr>
|
||||
<tr><td align="right">1</td><td>Left button</td></tr>
|
||||
<tr><td align="right">2</td><td>Middle button</td></tr>
|
||||
<tr><td align="right">3</td><td>Right button</td></tr>
|
||||
</table>
|
||||
|
||||
## Example
|
||||
Print the button and the coordinates whenever the mouse is clicked.
|
||||
|
||||
```lua
|
||||
while true do
|
||||
local event, button, x, y = os.pullEvent("mouse_click")
|
||||
print(("The mouse button %s was pressed at %d, %d"):format(button, x, y))
|
||||
end
|
||||
```
|
||||
@ -1,22 +0,0 @@
|
||||
---
|
||||
module: [kind=event] mouse_drag
|
||||
see: mouse_click For when a mouse button is initially pressed.
|
||||
---
|
||||
|
||||
This event is fired every time the mouse is moved while a mouse button is being held.
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The [mouse button](mouse_click.html#Mouse_buttons) that is being pressed.
|
||||
3. @{number}: The X-coordinate of the mouse.
|
||||
4. @{number}: The Y-coordinate of the mouse.
|
||||
|
||||
## Example
|
||||
Print the button and the coordinates whenever the mouse is dragged.
|
||||
|
||||
```lua
|
||||
while true do
|
||||
local event, button, x, y = os.pullEvent("mouse_drag")
|
||||
print(("The mouse button %s was dragged at %d, %d"):format(button, x, y))
|
||||
end
|
||||
```
|
||||
@ -1,21 +0,0 @@
|
||||
---
|
||||
module: [kind=event] mouse_scroll
|
||||
---
|
||||
|
||||
This event is fired when a mouse wheel is scrolled in the terminal.
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The direction of the scroll. (-1 = up, 1 = down)
|
||||
3. @{number}: The X-coordinate of the mouse when scrolling.
|
||||
4. @{number}: The Y-coordinate of the mouse when scrolling.
|
||||
|
||||
## Example
|
||||
Prints the direction of each scroll, and the position of the mouse at the time.
|
||||
|
||||
```lua
|
||||
while true do
|
||||
local event, dir, x, y = os.pullEvent("mouse_scroll")
|
||||
print(("The mouse was scrolled in direction %s at %d, %d"):format(dir, x, y))
|
||||
end
|
||||
```
|
||||
@ -1,21 +0,0 @@
|
||||
---
|
||||
module: [kind=event] mouse_up
|
||||
---
|
||||
|
||||
This event is fired when a mouse button is released or a held mouse leaves the computer's terminal.
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The [mouse button](mouse_click.html#Mouse_buttons) that was released.
|
||||
3. @{number}: The X-coordinate of the mouse.
|
||||
4. @{number}: The Y-coordinate of the mouse.
|
||||
|
||||
## Example
|
||||
Prints the coordinates and button number whenever the mouse is released.
|
||||
|
||||
```lua
|
||||
while true do
|
||||
local event, button, x, y = os.pullEvent("mouse_up")
|
||||
print(("The mouse button %s was released at %d, %d"):format(button, x, y))
|
||||
end
|
||||
```
|
||||
@ -1,18 +0,0 @@
|
||||
---
|
||||
module: [kind=event] paste
|
||||
---
|
||||
|
||||
The @{paste} event is fired when text is pasted into the computer through Ctrl-V (or ⌘V on Mac).
|
||||
|
||||
## Return values
|
||||
1. @{string}: The event name.
|
||||
2. @{string} The text that was pasted.
|
||||
|
||||
## Example
|
||||
Prints pasted text:
|
||||
```lua
|
||||
while true do
|
||||
local event, text = os.pullEvent("paste")
|
||||
print('"' .. text .. '" was pasted')
|
||||
end
|
||||
```
|
||||
@ -1,19 +0,0 @@
|
||||
---
|
||||
module: [kind=event] peripheral
|
||||
see: peripheral_detach For the event fired when a peripheral is detached.
|
||||
---
|
||||
|
||||
The @{peripheral} event is fired when a peripheral is attached on a side or to a modem.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side the peripheral was attached to.
|
||||
|
||||
## Example
|
||||
Prints a message when a peripheral is attached:
|
||||
```lua
|
||||
while true do
|
||||
local event, side = os.pullEvent("peripheral")
|
||||
print("A peripheral was attached on side " .. side)
|
||||
end
|
||||
```
|
||||
@ -1,19 +0,0 @@
|
||||
---
|
||||
module: [kind=event] peripheral_detach
|
||||
see: peripheral For the event fired when a peripheral is attached.
|
||||
---
|
||||
|
||||
The @{peripheral_detach} event is fired when a peripheral is detached from a side or from a modem.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The side the peripheral was detached from.
|
||||
|
||||
## Example
|
||||
Prints a message when a peripheral is detached:
|
||||
```lua
|
||||
while true do
|
||||
local event, side = os.pullEvent("peripheral_detach")
|
||||
print("A peripheral was detached on side " .. side)
|
||||
end
|
||||
```
|
||||
@ -1,30 +0,0 @@
|
||||
---
|
||||
module: [kind=event] rednet_message
|
||||
see: modem_message For raw modem messages sent outside of Rednet.
|
||||
see: rednet.receive To wait for a Rednet message with an optional timeout and protocol filter.
|
||||
---
|
||||
|
||||
The @{rednet_message} event is fired when a message is sent over Rednet.
|
||||
|
||||
This event is usually handled by @{rednet.receive}, but it can also be pulled manually.
|
||||
|
||||
@{rednet_message} events are sent by @{rednet.run} in the top-level coroutine in response to @{modem_message} events. A @{rednet_message} event is always preceded by a @{modem_message} event. They are generated inside CraftOS rather than being sent by the ComputerCraft machine.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The ID of the sending computer.
|
||||
3. @{any}: The message sent.
|
||||
4. @{string|nil}: The protocol of the message, if provided.
|
||||
|
||||
## Example
|
||||
Prints a message when one is sent:
|
||||
```lua
|
||||
while true do
|
||||
local event, sender, message, protocol = os.pullEvent("rednet_message")
|
||||
if protocol ~= nil then
|
||||
print("Received message from " .. sender .. " with protocol " .. protocol .. " and message " .. tostring(message))
|
||||
else
|
||||
print("Received message from " .. sender .. " with message " .. tostring(message))
|
||||
end
|
||||
end
|
||||
```
|
||||
@ -1,14 +0,0 @@
|
||||
---
|
||||
module: [kind=event] redstone
|
||||
---
|
||||
|
||||
The @{event!redstone} event is fired whenever any redstone inputs on the computer change.
|
||||
|
||||
## Example
|
||||
Prints a message when a redstone input changes:
|
||||
```lua
|
||||
while true do
|
||||
os.pullEvent("redstone")
|
||||
print("A redstone input has changed!")
|
||||
end
|
||||
```
|
||||
@ -1,27 +0,0 @@
|
||||
---
|
||||
module: [kind=event] speaker_audio_empty
|
||||
see: speaker.playAudio To play audio using the speaker
|
||||
---
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The name of the speaker which is available to play more audio.
|
||||
|
||||
|
||||
## Example
|
||||
This uses @{io.lines} to read audio data in blocks of 16KiB from "example_song.dfpwm", and then attempts to play it
|
||||
using @{speaker.playAudio}. If the speaker's buffer is full, it waits for an event and tries again.
|
||||
|
||||
```lua {data-peripheral=speaker}
|
||||
local dfpwm = require("cc.audio.dfpwm")
|
||||
local speaker = peripheral.find("speaker")
|
||||
|
||||
local decoder = dfpwm.make_decoder()
|
||||
for chunk in io.lines("data/example.dfpwm", 16 * 1024) do
|
||||
local buffer = decoder(chunk)
|
||||
|
||||
while not speaker.playAudio(buffer) do
|
||||
os.pullEvent("speaker_audio_empty")
|
||||
end
|
||||
end
|
||||
```
|
||||
@ -1,28 +0,0 @@
|
||||
---
|
||||
module: [kind=event] task_complete
|
||||
see: commands.execAsync To run a command which fires a task_complete event.
|
||||
---
|
||||
|
||||
The @{task_complete} event is fired when an asynchronous task completes. This is usually handled inside the function call that queued the task; however, functions such as @{commands.execAsync} return immediately so the user can wait for completion.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The ID of the task that completed.
|
||||
3. @{boolean}: Whether the command succeeded.
|
||||
4. @{string}: If the command failed, an error message explaining the failure. (This is not present if the command succeeded.)
|
||||
...: Any parameters returned from the command.
|
||||
|
||||
## Example
|
||||
Prints the results of an asynchronous command:
|
||||
```lua
|
||||
local taskID = commands.execAsync("say Hello")
|
||||
local event
|
||||
repeat
|
||||
event = {os.pullEvent("task_complete")}
|
||||
until event[2] == taskID
|
||||
if event[3] == true then
|
||||
print("Task " .. event[2] .. " succeeded:", table.unpack(event, 4))
|
||||
else
|
||||
print("Task " .. event[2] .. " failed: " .. event[4])
|
||||
end
|
||||
```
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
module: [kind=event] term_resize
|
||||
---
|
||||
|
||||
The @{term_resize} event is fired when the main terminal is resized. For instance:
|
||||
- When a the tab bar is shown or hidden in @{multishell}.
|
||||
- When the terminal is redirected to a monitor via the "monitor" program and the monitor is resized.
|
||||
|
||||
When this event fires, some parts of the terminal may have been moved or deleted. Simple terminal programs (those
|
||||
not using @{term.setCursorPos}) can ignore this event, but more complex GUI programs should redraw the entire screen.
|
||||
|
||||
## Example
|
||||
Prints :
|
||||
```lua
|
||||
while true do
|
||||
os.pullEvent("term_resize")
|
||||
local w, h = term.getSize()
|
||||
print("The term was resized to (" .. w .. ", " .. h .. ")")
|
||||
end
|
||||
```
|
||||
@ -1,25 +0,0 @@
|
||||
---
|
||||
module: [kind=event] terminate
|
||||
---
|
||||
|
||||
The @{terminate} event is fired when <kbd>Ctrl-T</kbd> is held down.
|
||||
|
||||
This event is normally handled by @{os.pullEvent}, and will not be returned. However, @{os.pullEventRaw} will return this event when fired.
|
||||
|
||||
@{terminate} will be sent even when a filter is provided to @{os.pullEventRaw}. When using @{os.pullEventRaw} with a filter, make sure to check that the event is not @{terminate}.
|
||||
|
||||
## Example
|
||||
Prints a message when Ctrl-T is held:
|
||||
```lua
|
||||
while true do
|
||||
local event = os.pullEventRaw("terminate")
|
||||
if event == "terminate" then print("Terminate requested!") end
|
||||
end
|
||||
```
|
||||
|
||||
Exits when Ctrl-T is held:
|
||||
```lua
|
||||
while true do
|
||||
os.pullEvent()
|
||||
end
|
||||
```
|
||||
@ -1,21 +0,0 @@
|
||||
---
|
||||
module: [kind=event] timer
|
||||
see: os.startTimer To start a timer.
|
||||
---
|
||||
|
||||
The @{timer} event is fired when a timer started with @{os.startTimer} completes.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{number}: The ID of the timer that finished.
|
||||
|
||||
## Example
|
||||
Starts a timer and then prints its ID:
|
||||
```lua
|
||||
local timerID = os.startTimer(2)
|
||||
local event, id
|
||||
repeat
|
||||
event, id = os.pullEvent("timer")
|
||||
until id == timerID
|
||||
print("Timer with ID " .. id .. " was fired")
|
||||
```
|
||||
@ -1,14 +0,0 @@
|
||||
---
|
||||
module: [kind=event] turtle_inventory
|
||||
---
|
||||
|
||||
The @{turtle_inventory} event is fired when a turtle's inventory is changed.
|
||||
|
||||
## Example
|
||||
Prints a message when the inventory is changed:
|
||||
```lua
|
||||
while true do
|
||||
os.pullEvent("turtle_inventory")
|
||||
print("The inventory was changed.")
|
||||
end
|
||||
```
|
||||
@ -1,21 +0,0 @@
|
||||
---
|
||||
module: [kind=event] websocket_closed
|
||||
---
|
||||
|
||||
The @{websocket_closed} event is fired when an open WebSocket connection is closed.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL of the WebSocket that was closed.
|
||||
|
||||
## Example
|
||||
Prints a message when a WebSocket is closed (this may take a minute):
|
||||
```lua
|
||||
local myURL = "wss://example.tweaked.cc/echo"
|
||||
local ws = http.websocket(myURL)
|
||||
local event, url
|
||||
repeat
|
||||
event, url = os.pullEvent("websocket_closed")
|
||||
until url == myURL
|
||||
print("The WebSocket at " .. url .. " was closed.")
|
||||
```
|
||||
@ -1,25 +0,0 @@
|
||||
---
|
||||
module: [kind=event] websocket_failure
|
||||
see: http.websocketAsync To send an HTTP request.
|
||||
---
|
||||
|
||||
The @{websocket_failure} event is fired when a WebSocket connection request fails.
|
||||
|
||||
This event is normally handled inside @{http.websocket}, but it can still be seen when using @{http.websocketAsync}.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL of the site requested.
|
||||
3. @{string}: An error describing the failure.
|
||||
|
||||
## Example
|
||||
Prints an error why the website cannot be contacted:
|
||||
```lua
|
||||
local myURL = "wss://example.tweaked.cc/not-a-websocket"
|
||||
http.websocketAsync(myURL)
|
||||
local event, url, err
|
||||
repeat
|
||||
event, url, err = os.pullEvent("websocket_failure")
|
||||
until url == myURL
|
||||
print("The URL " .. url .. " could not be reached: " .. err)
|
||||
```
|
||||
@ -1,27 +0,0 @@
|
||||
---
|
||||
module: [kind=event] websocket_message
|
||||
---
|
||||
|
||||
The @{websocket_message} event is fired when a message is received on an open WebSocket connection.
|
||||
|
||||
This event is normally handled by @{http.Websocket.receive}, but it can also be pulled manually.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL of the WebSocket.
|
||||
3. @{string}: The contents of the message.
|
||||
4. @{boolean}: Whether this is a binary message.
|
||||
|
||||
## Example
|
||||
Prints a message sent by a WebSocket:
|
||||
```lua
|
||||
local myURL = "wss://example.tweaked.cc/echo"
|
||||
local ws = http.websocket(myURL)
|
||||
ws.send("Hello!")
|
||||
local event, url, message
|
||||
repeat
|
||||
event, url, message = os.pullEvent("websocket_message")
|
||||
until url == myURL
|
||||
print("Received message from " .. url .. " with contents " .. message)
|
||||
ws.close()
|
||||
```
|
||||
@ -1,28 +0,0 @@
|
||||
---
|
||||
module: [kind=event] websocket_success
|
||||
see: http.websocketAsync To open a WebSocket asynchronously.
|
||||
---
|
||||
|
||||
The @{websocket_success} event is fired when a WebSocket connection request returns successfully.
|
||||
|
||||
This event is normally handled inside @{http.websocket}, but it can still be seen when using @{http.websocketAsync}.
|
||||
|
||||
## Return Values
|
||||
1. @{string}: The event name.
|
||||
2. @{string}: The URL of the site.
|
||||
3. @{http.Websocket}: The handle for the WebSocket.
|
||||
|
||||
## Example
|
||||
Prints the content of a website (this may fail if the request fails):
|
||||
```lua
|
||||
local myURL = "wss://example.tweaked.cc/echo"
|
||||
http.websocketAsync(myURL)
|
||||
local event, url, handle
|
||||
repeat
|
||||
event, url, handle = os.pullEvent("websocket_success")
|
||||
until url == myURL
|
||||
print("Connected to " .. url)
|
||||
handle.send("Hello!")
|
||||
print(handle.receive())
|
||||
handle.close()
|
||||
```
|
||||
@ -1,200 +0,0 @@
|
||||
---
|
||||
module: [kind=guide] speaker_audio
|
||||
see: speaker.playAudio Play PCM audio using a speaker.
|
||||
see: cc.audio.dfpwm Provides utilities for encoding and decoding DFPWM files.
|
||||
---
|
||||
|
||||
# Playing audio with speakers
|
||||
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.
|
||||
|
||||
## A short introduction to digital audio
|
||||
When sound is recorded it is captured as an analogue signal, effectively the electrical version of a sound
|
||||
wave. However, this signal is continuous, and so can't be used directly by a computer. Instead, we measure (or *sample*)
|
||||
the amplitude of the wave many times a second and then *quantise* that amplitude, rounding it to the nearest
|
||||
representable value.
|
||||
|
||||
This representation of sound - a long, uniformally sampled list of amplitudes is referred to as [Pulse-code
|
||||
Modulation][PCM] (PCM). PCM can be thought of as the "standard" audio format, as it's incredibly easy to work with. For
|
||||
instance, to mix two pieces of audio together, you can just samples from the two tracks together and take the average.
|
||||
|
||||
CC: Tweaked's speakers also work with PCM audio. It plays back 48,000 samples a second, where each sample is an integer
|
||||
between -128 and 127. This is more commonly referred to as 48kHz and an 8-bit resolution.
|
||||
|
||||
Let's now look at a quick example. We're going to generate a [Sine Wave] at 220Hz, which sounds like a low monotonous
|
||||
hum. First we wrap our speaker peripheral, and then we fill a table (also referred to as a *buffer*) with 128×1024
|
||||
samples - this is the maximum number of samples a speaker can accept in one go.
|
||||
|
||||
In order to fill this buffer, we need to do a little maths. We want to play 220 sine waves each second, where each sine
|
||||
wave completes a full oscillation in 2π "units". This means one seconds worth of audio is 2×π×220 "units" long. We then
|
||||
need to split this into 48k samples, basically meaning for each sample we move 2×π×220/48k "along" the sine curve.
|
||||
|
||||
```lua {data-peripheral=speaker}
|
||||
local speaker = peripheral.find("speaker")
|
||||
|
||||
local buffer = {}
|
||||
local t, dt = 0, 2 * math.pi * 220 / 48000
|
||||
for i = 1, 128 * 1024 do
|
||||
buffer[i] = math.floor(math.sin(t) * 127)
|
||||
t = (t + dt) % (math.pi * 2)
|
||||
end
|
||||
|
||||
speaker.playAudio(buffer)
|
||||
```
|
||||
|
||||
## Streaming audio
|
||||
You might notice that the above snippet only generates a short bit of audio - 2.7s seconds to be precise. While we could
|
||||
try increasing the number of loop iterations, we'll get an error when we try to play it through the speaker: the sound
|
||||
buffer is too large for it to handle.
|
||||
|
||||
Our 2.7 seconds of audio is stored in a table with over 130 _thousand_ elements. If we wanted to play a full minute of
|
||||
sine waves (and why wouldn't you?), you'd need a table with almost 3 _million_. Suddenly you find these numbers adding
|
||||
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
|
||||
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.
|
||||
|
||||
Let's adapt our example from above to do that instead.
|
||||
|
||||
```lua {data-peripheral=speaker}
|
||||
local speaker = peripheral.find("speaker")
|
||||
|
||||
local t, dt = 0, 2 * math.pi * 220 / 48000
|
||||
while true do
|
||||
local buffer = {}
|
||||
for i = 1, 16 * 1024 * 8 do
|
||||
buffer[i] = math.floor(math.sin(t) * 127)
|
||||
t = (t + dt) % (math.pi * 2)
|
||||
end
|
||||
|
||||
while not speaker.playAudio(buffer) do
|
||||
os.pullEvent("speaker_audio_empty")
|
||||
end
|
||||
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}.
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
store it to disk. Compare the size of a WAV file (which uses PCM) to an equivalent MP3, it's often 5 times the size.
|
||||
Instead, we store audio in special formats (or *codecs*) and then convert them to PCM when we need to do processing on
|
||||
them.
|
||||
|
||||
Modern audio codecs use some incredibly impressive techniques to compress the audio as much as possible while preserving
|
||||
sound quality. However, due to CC: Tweaked's limited processing power, it's not really possible to use these from your
|
||||
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
|
||||
using the speaker.
|
||||
|
||||
Let's dive in with an example, and we'll explain things afterwards:
|
||||
|
||||
```lua {data-peripheral=speaker}
|
||||
local dfpwm = require("cc.audio.dfpwm")
|
||||
local speaker = peripheral.find("speaker")
|
||||
|
||||
local decoder = dfpwm.make_decoder()
|
||||
for chunk in io.lines("data/example.dfpwm", 16 * 1024) do
|
||||
local buffer = decoder(chunk)
|
||||
|
||||
while not speaker.playAudio(buffer) do
|
||||
os.pullEvent("speaker_audio_empty")
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
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
|
||||
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 to 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.
|
||||
|
||||
## 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.
|
||||
You can mix together samples from different streams by adding their amplitudes, change the rate of playback by removing
|
||||
samples, etc...
|
||||
|
||||
Let's put together a small demonstration here. We're going to add a small delay effect to the song above, so that you
|
||||
hear a faint echo about a second later.
|
||||
|
||||
In order to do this, we'll follow a format similar to the previous example, decoding the audio and then playing it.
|
||||
However, we'll also add some new logic between those two steps, which loops over every sample in our chunk of audio, and
|
||||
adds the sample from one second ago to it.
|
||||
|
||||
For this, we'll need to keep track of the last 48k samples - exactly one seconds worth of audio. We can do this using a
|
||||
[Ring Buffer], which helps makes things a little more efficient.
|
||||
|
||||
```lua {data-peripheral=speaker}
|
||||
local dfpwm = require("cc.audio.dfpwm")
|
||||
local speaker = peripheral.find("speaker")
|
||||
|
||||
-- Speakers play at 48kHz, so one second is 48k samples. We first fill our buffer
|
||||
-- with 0s, as there's nothing to echo at the start of the track!
|
||||
local samples_i, samples_n = 1, 48000
|
||||
local samples = {}
|
||||
for i = 1, samples_n do samples[i] = 0 end
|
||||
|
||||
local decoder = dfpwm.make_decoder()
|
||||
for chunk in io.lines("data/example.dfpwm", 16 * 1024) do
|
||||
local buffer = decoder(chunk)
|
||||
|
||||
for i = 1, #buffer do
|
||||
local original_value = buffer[i]
|
||||
|
||||
-- Replace this sample with its current amplitude plus the amplitude from one second ago.
|
||||
-- We scale both to ensure the resulting value is still between -128 and 127.
|
||||
buffer[i] = original_value * 0.6 + samples[samples_i] * 0.4
|
||||
|
||||
-- Now store the current sample, and move the "head" of our ring buffer forward one place.
|
||||
samples[samples_i] = original_value
|
||||
samples_i = samples_i + 1
|
||||
if samples_i > samples_n then samples_i = 1 end
|
||||
end
|
||||
|
||||
while not speaker.playAudio(buffer) do
|
||||
os.pullEvent("speaker_audio_empty")
|
||||
end
|
||||
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 [Discord] 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.
|
||||
For this, you'd need to use the [Fast Fourier transform][FFT] to convert the stream of amplitudes to frequencies,
|
||||
process those, and then convert them back to amplitudes.
|
||||
|
||||
This is, I'm afraid, left as an exercise to the reader.
|
||||
|
||||
[Computronics]: https://github.com/Vexatos/Computronics/ "Computronics on GitHub"
|
||||
[FFT]: https://en.wikipedia.org/wiki/Fast_Fourier_transform "Fast Fourier transform - Wikipedia"
|
||||
[PCM]: https://en.wikipedia.org/wiki/Pulse-code_modulation "Pulse-code Modulation - Wikipedia"
|
||||
[Ring Buffer]: https://en.wikipedia.org/wiki/Circular_buffer "Circular buffer - Wikipedia"
|
||||
[Sine Wave]: https://en.wikipedia.org/wiki/Sine_wave "Sine wave - Wikipedia"
|
||||
|
||||
[Discord]: https://discord.computercraft.cc "The Minecraft Computer Mods Discord"
|
||||
[IRC]: http://webchat.esper.net/?channels=computercraft "IRC webchat on EsperNet"
|
||||
@ -1,83 +0,0 @@
|
||||
---
|
||||
module: [kind=guide] using_require
|
||||
---
|
||||
|
||||
# Reusing code with require
|
||||
A library is a collection of useful functions and other definitions which is stored separately to your main program. You
|
||||
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
|
||||
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.
|
||||
|
||||
Start off by creating a file called `more_term.lua`:
|
||||
|
||||
```lua {data-snippet=more_term}
|
||||
local function reset()
|
||||
term.clear()
|
||||
term.setCursorPos(1, 1)
|
||||
end
|
||||
|
||||
local function write_center(text)
|
||||
local x, y = term.getCursorPos()
|
||||
local width, height = term.getSize()
|
||||
term.setCursorPos(math.floor((width - #text) / 2) + 1, y)
|
||||
term.write(text)
|
||||
end
|
||||
|
||||
return { reset = reset, write_center = write_center }
|
||||
```
|
||||
|
||||
Now, what's going on here? We define our two functions as one might expect, and then at the bottom return a table with
|
||||
the two functions. When we require this library, this table is what is returned. With that, we can then call the
|
||||
original functions. Now create a new file, with the following:
|
||||
|
||||
```lua {data-mount=more_term:more_term.lua}
|
||||
local more_term = require("more_term")
|
||||
more_term.reset()
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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:
|
||||
|
||||
* `?.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
|
||||
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...
|
||||
|
||||
One other caveat is loading libraries from sub-directories. For instance, say we have a file
|
||||
`my/fancy/library.lua`. This can be loaded by using `require("my.fancy.library")` - the '.'s are replaced with '/'
|
||||
before we start looking for the library.
|
||||
|
||||
## External links
|
||||
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).
|
||||
@ -1 +0,0 @@
|
||||
<meta name="theme-color" content="#c8d87c">
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 194 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 163 KiB |
55
doc/index.md
55
doc/index.md
@ -1,55 +0,0 @@
|
||||
# 
|
||||
CC: Tweaked is a mod for Minecraft which adds programmable computers, turtles and more to the game. A fork of the
|
||||
much-beloved [ComputerCraft], it continues its legacy with better performance, stability, and a wealth of new features.
|
||||
|
||||
CC: Tweaked can be installed from [CurseForge] or [Modrinth]. It requires the [Minecraft Forge][forge] mod loader, but
|
||||
[versions are available for Fabric][ccrestitched].
|
||||
|
||||
## Features
|
||||
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
|
||||
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
|
||||
little daunting getting started. Thankfully, there's several fantastic tutorials out there:
|
||||
|
||||
- [Direwolf20's ComputerCraft tutorials](https://www.youtube.com/watch?v=wrUHUhfCY5A "ComputerCraft Tutorial Episode 1 - HELP! and Hello World")
|
||||
- [Sethbling's ComputerCraft series](https://www.youtube.com/watch?v=DSsx4VSe-Uk "Programming Tutorial with Minecraft Turtles -- Ep. 1: Intro to Turtles and If-Then-Else_End")
|
||||
- [Lyqyd's Computer Basics 1](http://www.computercraft.info/forums2/index.php?/topic/15033-computer-basics-i/ "Computer Basics I")
|
||||
|
||||
Once you're a little more familiar with the mod, the sidebar and links below provide more detailed documentation on the
|
||||
various APIs and peripherals provided by the mod.
|
||||
|
||||
If you get stuck, do pop in to the [Minecraft Computer Mod Discord guild][discord] or ComputerCraft's
|
||||
[IRC channel][irc].
|
||||
|
||||
## Get Involved
|
||||
CC: Tweaked lives on [GitHub]. If you've got any ideas, feedback or bugs please do [create an issue][bug].
|
||||
|
||||
[github]: https://github.com/cc-tweaked/CC-Tweaked/ "CC: Tweaked on GitHub"
|
||||
[bug]: https://github.com/cc-tweaked/CC-Tweaked/issues/new/choose
|
||||
[computercraft]: https://github.com/dan200/ComputerCraft "ComputerCraft on GitHub"
|
||||
[curseforge]: https://minecraft.curseforge.com/projects/cc-tweaked "Download CC: Tweaked from CurseForge"
|
||||
[modrinth]: https://modrinth.com/mod/gu7yAYhd "Download CC: Tweaked from Modrinth"
|
||||
[forge]: https://files.minecraftforge.net/ "Download Minecraft Forge."
|
||||
[ccrestitched]: https://www.curseforge.com/minecraft/mc-mods/cc-restitched "Download CC: Restitched from CurseForge"
|
||||
[lua]: https://www.lua.org/ "Lua's main website"
|
||||
[discord]: https://discord.computercraft.cc "The Minecraft Computer Mods Discord"
|
||||
[irc]: http://webchat.esper.net/?channels=computercraft "IRC webchat on EsperNet"
|
||||
BIN
doc/logo.png
BIN
doc/logo.png
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 KiB |
@ -1,36 +0,0 @@
|
||||
--- The FS API allows you to manipulate files and the filesystem.
|
||||
--
|
||||
-- @module fs
|
||||
|
||||
--- Returns true if a path is mounted to the parent filesystem.
|
||||
--
|
||||
-- The root filesystem "/" is considered a mount, along with disk folders and
|
||||
-- the rom folder. Other programs (such as network shares) can exstend this to
|
||||
-- make other mount types by correctly assigning their return value for getDrive.
|
||||
--
|
||||
-- @tparam string path The path to check.
|
||||
-- @treturn boolean If the path is mounted, rather than a normal file/folder.
|
||||
-- @throws If the path does not exist.
|
||||
-- @see getDrive
|
||||
-- @since 1.87.0
|
||||
function isDriveRoot(path) end
|
||||
|
||||
--[[- Provides completion for a file or directory name, suitable for use with
|
||||
@{_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
|
||||
those with a trailing slash.
|
||||
|
||||
@tparam string path The path to complete.
|
||||
@tparam string location The location where paths are resolved from.
|
||||
@tparam[opt] boolean include_files When @{false}, only directories will be
|
||||
included in the returned list.
|
||||
@tparam[opt] boolean include_dirs When @{false}, "raw" directories will not be
|
||||
included in the returned list.
|
||||
@treturn { string... } A list of possible completion candidates.
|
||||
@since 1.74
|
||||
]]
|
||||
function complete(path, location, include_files, include_dirs) end
|
||||
@ -1,133 +0,0 @@
|
||||
--[[-
|
||||
Functions in the global environment, defined in `bios.lua`. This does not
|
||||
include standard Lua functions.
|
||||
|
||||
@module _G
|
||||
]]
|
||||
|
||||
--[[- Pauses execution for the specified number of seconds.
|
||||
|
||||
As it waits for a fixed amount of world ticks, `time` will automatically be
|
||||
rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines
|
||||
or the @{parallel|parallel API}, it will only pause execution of the current
|
||||
thread, not the whole program.
|
||||
|
||||
:::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}.
|
||||
:::
|
||||
|
||||
@tparam number time The number of seconds to sleep for, rounded up to the
|
||||
nearest multiple of 0.05.
|
||||
|
||||
@see os.startTimer
|
||||
@usage Sleep for three seconds.
|
||||
|
||||
print("Sleeping for three seconds")
|
||||
sleep(3)
|
||||
print("Done!")
|
||||
]]
|
||||
function sleep(time) end
|
||||
|
||||
--- Writes a line of text to the screen without a newline at the end, wrapping
|
||||
-- text if necessary.
|
||||
--
|
||||
-- @tparam string text The text to write to the string
|
||||
-- @treturn number The number of lines written
|
||||
-- @see print A wrapper around write that adds a newline and accepts multiple arguments
|
||||
-- @usage write("Hello, world")
|
||||
function write(text) end
|
||||
|
||||
--- Prints the specified values to the screen separated by spaces, wrapping if
|
||||
-- necessary. After printing, the cursor is moved to the next line.
|
||||
--
|
||||
-- @param ... The values to print on the screen
|
||||
-- @treturn number The number of lines written
|
||||
-- @usage print("Hello, world!")
|
||||
function print(...) end
|
||||
|
||||
--- Prints the specified values to the screen in red, separated by spaces,
|
||||
-- wrapping if necessary. After printing, the cursor is moved to the next line.
|
||||
--
|
||||
-- @param ... The values to print on the screen
|
||||
-- @usage printError("Something went wrong!")
|
||||
function printError(...) end
|
||||
|
||||
--[[- Reads user input from the terminal, automatically handling arrow keys,
|
||||
pasting, character replacement, history scrollback, auto-completion, and
|
||||
default values.
|
||||
|
||||
@tparam[opt] string replaceChar A character to replace each typed character with.
|
||||
This can be used for hiding passwords, for example.
|
||||
@tparam[opt] table history A table holding history items that can be scrolled
|
||||
back to with the up/down arrow keys. The oldest item is at index 1, while the
|
||||
newest item is at the highest index.
|
||||
@tparam[opt] function(partial: string):({ string... }|nil) completeFn A function
|
||||
to be used for completion. This function should take the partial text typed so
|
||||
far, and returns a list of possible completion options.
|
||||
@tparam[opt] string default Default text which should already be entered into
|
||||
the prompt.
|
||||
|
||||
@treturn string The text typed in.
|
||||
|
||||
@see cc.completion For functions to help with completion.
|
||||
@usage Read a string and echo it back to the user
|
||||
|
||||
write("> ")
|
||||
local msg = read()
|
||||
print(msg)
|
||||
|
||||
@usage Prompt a user for a password.
|
||||
|
||||
while true do
|
||||
write("Password> ")
|
||||
local pwd = read("*")
|
||||
if pwd == "let me in" then break end
|
||||
print("Incorrect password, try again.")
|
||||
end
|
||||
print("Logged in!")
|
||||
|
||||
@usage A complete example with completion, history and a default value.
|
||||
|
||||
local completion = require "cc.completion"
|
||||
local history = { "potato", "orange", "apple" }
|
||||
local choices = { "apple", "orange", "banana", "strawberry" }
|
||||
write("> ")
|
||||
local msg = read(nil, history, function(text) return completion.choice(text, choices) end, "app")
|
||||
print(msg)
|
||||
|
||||
@changed 1.74 Added `completeFn` parameter.
|
||||
@changed 1.80pr1 Added `default` parameter.
|
||||
]]
|
||||
function read(replaceChar, history, completeFn, default) end
|
||||
|
||||
--- The ComputerCraft and Minecraft version of the current computer environment.
|
||||
--
|
||||
-- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.
|
||||
-- @usage _HOST
|
||||
-- @since 1.76
|
||||
_HOST = _HOST
|
||||
|
||||
--[[- The default computer settings as defined in the ComputerCraft
|
||||
configuration.
|
||||
|
||||
This is a comma-separated list of settings pairs defined by the mod
|
||||
configuration or server owner. By default, it is empty.
|
||||
|
||||
An example value to disable autocompletion:
|
||||
|
||||
shell.autocomplete=false,lua.autocomplete=false,edit.autocomplete=false
|
||||
|
||||
@usage _CC_DEFAULT_SETTINGS
|
||||
@since 1.77
|
||||
]]
|
||||
_CC_DEFAULT_SETTINGS = _CC_DEFAULT_SETTINGS
|
||||
@ -1,181 +0,0 @@
|
||||
--- The http library allows communicating with web servers, sending and
|
||||
-- receiving data from them.
|
||||
--
|
||||
-- @module http
|
||||
-- @since 1.1
|
||||
|
||||
--- Asynchronously make a HTTP request to the given url.
|
||||
--
|
||||
-- This returns immediately, a [`http_success`](#http-success-event) or
|
||||
-- [`http_failure`](#http-failure-event) will be queued once the request has
|
||||
-- completed.
|
||||
--
|
||||
-- @tparam string url The url to request
|
||||
-- @tparam[opt] string body An optional string containing the body of the
|
||||
-- request. If specified, a `POST` request will be made instead.
|
||||
-- @tparam[opt] { [string] = string } headers Additional headers to send as part
|
||||
-- of this request.
|
||||
-- @tparam[opt] boolean binary Whether to make a binary HTTP request. If true,
|
||||
-- the body will not be UTF-8 encoded, and the received response will not be
|
||||
-- decoded.
|
||||
--
|
||||
-- @tparam[2] {
|
||||
-- url = string, body? = string, headers? = { [string] = string },
|
||||
-- binary? = boolean, method? = string, redirect? = boolean,
|
||||
-- } request Options for the request.
|
||||
--
|
||||
-- This table form is an expanded version of the previous syntax. All arguments
|
||||
-- from above are passed in as fields instead (for instance,
|
||||
-- `http.request("https://example.com")` becomes `http.request { url =
|
||||
-- "https://example.com" }`).
|
||||
--
|
||||
-- This table also accepts several additional options:
|
||||
--
|
||||
-- - `method`: Which HTTP method to use, for instance `"PATCH"` or `"DELETE"`.
|
||||
-- - `redirect`: Whether to follow HTTP redirects. Defaults to true.
|
||||
--
|
||||
-- @see http.get For a synchronous way to make GET requests.
|
||||
-- @see http.post For a synchronous way to make POST requests.
|
||||
--
|
||||
-- @changed 1.63 Added argument for headers.
|
||||
-- @changed 1.80pr1 Added argument for binary handles.
|
||||
-- @changed 1.80pr1.6 Added support for table argument.
|
||||
-- @changed 1.86.0 Added PATCH and TRACE methods.
|
||||
function request(...) end
|
||||
|
||||
--- Make a HTTP GET request to the given url.
|
||||
--
|
||||
-- @tparam string url The url to request
|
||||
-- @tparam[opt] { [string] = string } headers Additional headers to send as part
|
||||
-- of this request.
|
||||
-- @tparam[opt] boolean binary Whether to make a binary HTTP request. If true,
|
||||
-- the body will not be UTF-8 encoded, and the received response will not be
|
||||
-- decoded.
|
||||
--
|
||||
-- @tparam[2] {
|
||||
-- url = string, headers? = { [string] = string },
|
||||
-- binary? = boolean, method? = string, redirect? = boolean,
|
||||
-- } 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.
|
||||
-- @treturn[2] nil When the http request failed, such as in the event of a 404
|
||||
-- error or connection timeout.
|
||||
-- @treturn string A message detailing why the request failed.
|
||||
-- @treturn Response|nil The failing http response, if available.
|
||||
--
|
||||
-- @changed 1.63 Added argument for headers.
|
||||
-- @changed 1.80pr1 Response handles are now returned on error if available.
|
||||
-- @changed 1.80pr1 Added argument for binary handles.
|
||||
-- @changed 1.80pr1.6 Added support for table argument.
|
||||
-- @changed 1.86.0 Added PATCH and TRACE methods.
|
||||
--
|
||||
-- @usage Make a request to [example.tweaked.cc](https://example.tweaked.cc),
|
||||
-- and print the returned page.
|
||||
-- ```lua
|
||||
-- local request = http.get("https://example.tweaked.cc")
|
||||
-- print(request.readAll())
|
||||
-- -- => HTTP is working!
|
||||
-- request.close()
|
||||
-- ```
|
||||
function get(...) end
|
||||
|
||||
--- Make a HTTP POST request to the given url.
|
||||
--
|
||||
-- @tparam string url The url to request
|
||||
-- @tparam string body The body of the POST request.
|
||||
-- @tparam[opt] { [string] = string } headers Additional headers to send as part
|
||||
-- of this request.
|
||||
-- @tparam[opt] boolean binary Whether to make a binary HTTP request. If true,
|
||||
-- the body will not be UTF-8 encoded, and the received response will not be
|
||||
-- decoded.
|
||||
--
|
||||
-- @tparam[2] {
|
||||
-- url = string, body? = string, headers? = { [string] = string },
|
||||
-- binary? = boolean, method? = string, redirect? = boolean,
|
||||
-- } 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.
|
||||
-- @treturn[2] nil When the http request failed, such as in the event of a 404
|
||||
-- error or connection timeout.
|
||||
-- @treturn string A message detailing why the request failed.
|
||||
-- @treturn Response|nil The failing http response, if available.
|
||||
--
|
||||
-- @since 1.31
|
||||
-- @changed 1.63 Added argument for headers.
|
||||
-- @changed 1.80pr1 Response handles are now returned on error if available.
|
||||
-- @changed 1.80pr1 Added argument for binary handles.
|
||||
-- @changed 1.80pr1.6 Added support for table argument.
|
||||
-- @changed 1.86.0 Added PATCH and TRACE methods.
|
||||
function post(...) end
|
||||
|
||||
--- Asynchronously determine whether a URL can be requested.
|
||||
--
|
||||
-- If this returns `true`, one should also listen for [`http_check`
|
||||
-- events](#http-check-event) 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 not invalid. This does not imply that it is
|
||||
-- allowed - see the comment above.
|
||||
-- @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).
|
||||
--
|
||||
-- @see http.checkURL For a synchronous version.
|
||||
function checkURLAsync(url) end
|
||||
|
||||
--- Determine whether a URL can be requested.
|
||||
--
|
||||
-- If this returns `true`, one should also listen for [`http_check`
|
||||
-- events](#http-check-event) 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[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).
|
||||
--
|
||||
-- @see http.checkURLAsync For an asynchronous version.
|
||||
--
|
||||
-- @usage
|
||||
-- ```lua
|
||||
-- print(http.checkURL("https://example.tweaked.cc/"))
|
||||
-- -- => true
|
||||
-- print(http.checkURL("http://localhost/"))
|
||||
-- -- => false Domain not permitted
|
||||
-- print(http.checkURL("not a url"))
|
||||
-- -- => false URL malformed
|
||||
-- ```
|
||||
function checkURL(url) end
|
||||
|
||||
--- Open a websocket.
|
||||
--
|
||||
-- @tparam string url The websocket url to connect to. This should have the
|
||||
-- `ws://` or `wss://` protocol.
|
||||
-- @tparam[opt] { [string] = string } headers Additional headers to send as part
|
||||
-- of the initial websocket connection.
|
||||
--
|
||||
-- @treturn Websocket The websocket connection.
|
||||
-- @treturn[2] false If the websocket connection failed.
|
||||
-- @treturn string An error message describing why the connection failed.
|
||||
-- @since 1.80pr1.1
|
||||
-- @changed 1.80pr1.3 No longer asynchronous.
|
||||
-- @changed 1.95.3 Added User-Agent to default headers.
|
||||
function websocket(url, headers) end
|
||||
|
||||
--- Asynchronously open a websocket.
|
||||
--
|
||||
-- This returns immediately, a [`websocket_success`](#websocket-success-event)
|
||||
-- or [`websocket_failure`](#websocket-failure-event) will be queued once the
|
||||
-- request has completed.
|
||||
--
|
||||
-- @tparam string url The websocket url to connect to. This should have the
|
||||
-- `ws://` or `wss://` protocol.
|
||||
-- @tparam[opt] { [string] = string } headers Additional headers to send as part
|
||||
-- of the initial websocket connection.
|
||||
-- @since 1.80pr1.3
|
||||
-- @changed 1.95.3 Added User-Agent to default headers.
|
||||
function websocketAsync(url, headers) end
|
||||
128
doc/stub/os.lua
128
doc/stub/os.lua
@ -1,128 +0,0 @@
|
||||
-- Defined in bios.lua
|
||||
|
||||
--[[- Loads the given API into the global environment.
|
||||
|
||||
This function loads and executes the file at the given path, and all global
|
||||
variables and functions exported by it will by available through the use of
|
||||
`myAPI.<function name>`, where `myAPI` is the base name of the API file.
|
||||
|
||||
@tparam string path The path of the API to load.
|
||||
@treturn boolean Whether or not the API was successfully loaded.
|
||||
@since 1.2
|
||||
|
||||
@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.
|
||||
]]
|
||||
function loadAPI(path) end
|
||||
|
||||
--- Unloads an API which was loaded by @{os.loadAPI}.
|
||||
--
|
||||
-- This effectively removes the specified table from `_G`.
|
||||
--
|
||||
-- @tparam string name The name of the API to unload.
|
||||
-- @since 1.2
|
||||
-- @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
|
||||
to be resumed with a vararg list where the first element matches `filter`.
|
||||
If no `filter` is supplied, this will match all events.
|
||||
|
||||
Unlike @{os.pullEventRaw}, it will stop the application upon a "terminate"
|
||||
event, printing the error "Terminated".
|
||||
|
||||
@tparam[opt] string filter Event to filter for.
|
||||
@treturn string event The name of the event that fired.
|
||||
@treturn any param... Optional additional parameters of the event.
|
||||
@usage Listen for `mouse_click` events.
|
||||
|
||||
while true do
|
||||
local event, button, x, y = os.pullEvent("mouse_click")
|
||||
print("Button", button, "was clicked at", x, ",", y)
|
||||
end
|
||||
|
||||
@usage Listen for multiple events.
|
||||
|
||||
while true do
|
||||
local eventData = {os.pullEvent()}
|
||||
local event = eventData[1]
|
||||
|
||||
if event == "mouse_click" then
|
||||
print("Button", eventData[2], "was clicked at", eventData[3], ",", eventData[4])
|
||||
elseif event == "key" then
|
||||
print("Key code", eventData[2], "was pressed")
|
||||
end
|
||||
end
|
||||
|
||||
@see os.pullEventRaw To pull the terminate event.
|
||||
@changed 1.3 Added filter argument.
|
||||
]]
|
||||
function pullEvent(filter) end
|
||||
|
||||
--[[- Pause execution of the current thread and waits for events, including the
|
||||
`terminate` event.
|
||||
|
||||
This behaves almost the same as @{os.pullEvent}, except it allows you to handle
|
||||
the `terminate` event yourself - the program will not stop execution when
|
||||
<kbd>Ctrl+T</kbd> is pressed.
|
||||
|
||||
@tparam[opt] string filter Event to filter for.
|
||||
@treturn string event The name of the event that fired.
|
||||
@treturn any param... Optional additional parameters of the event.
|
||||
@usage Listen for `terminate` events.
|
||||
|
||||
while true do
|
||||
local event = os.pullEventRaw()
|
||||
if event == "terminate" then
|
||||
print("Caught terminate event!")
|
||||
end
|
||||
end
|
||||
|
||||
@see os.pullEvent To pull events normally.
|
||||
]]
|
||||
function pullEventRaw(filter) end
|
||||
|
||||
--- Pauses execution for the specified number of seconds, alias of @{_G.sleep}.
|
||||
--
|
||||
-- @tparam number time The number of seconds to sleep for, rounded up to the
|
||||
-- nearest multiple of 0.05.
|
||||
function sleep(time) end
|
||||
|
||||
--- Get the current CraftOS version (for example, `CraftOS 1.8`).
|
||||
--
|
||||
-- This is defined by `bios.lua`. For the current version of CC:Tweaked, this
|
||||
-- should return `CraftOS 1.8`.
|
||||
--
|
||||
-- @treturn string The current CraftOS version.
|
||||
-- @usage os.version()
|
||||
function version() end
|
||||
|
||||
--[[- Run the program at the given path with the specified environment and
|
||||
arguments.
|
||||
|
||||
This function does not resolve program names like the shell does. This means
|
||||
that, for example, `os.run("edit")` will not work. As well as this, it does not
|
||||
provide access to the @{shell} API in the environment. For this behaviour, use
|
||||
@{shell.run} instead.
|
||||
|
||||
If the program cannot be found, or failed to run, it will print the error and
|
||||
return `false`. If you want to handle this more gracefully, use an alternative
|
||||
such as @{loadfile}.
|
||||
|
||||
@tparam table env The environment to run the program with.
|
||||
@tparam string path The exact path of the program to run.
|
||||
@param ... The arguments to pass to the program.
|
||||
@treturn boolean Whether or not the program ran successfully.
|
||||
@usage Run the default shell from within your program:
|
||||
|
||||
os.run({}, "/rom/programs/shell.lua")
|
||||
|
||||
@see shell.run
|
||||
@see loadfile
|
||||
]]
|
||||
function run(env, path, ...) end
|
||||
@ -1,14 +0,0 @@
|
||||
--[[- Craft a recipe based on the turtle's inventory.
|
||||
|
||||
The turtle's inventory should set up like a crafting grid. For instance, to
|
||||
craft sticks, slots 1 and 5 should contain planks. _All_ other slots should be
|
||||
empty, including those outside the crafting "grid".
|
||||
|
||||
@tparam[opt=64] number limit The maximum number of crafting steps to run.
|
||||
@throws When limit is less than 1 or greater than 64.
|
||||
@treturn[1] true If crafting succeeds.
|
||||
@treturn[2] false If crafting fails.
|
||||
@treturn string A string describing why crafting failed.
|
||||
@since 1.4
|
||||
]]
|
||||
function craft(limit) end
|
||||
Loading…
x
Reference in New Issue
Block a user