mirror of
https://github.com/SquidDev-CC/CC-Tweaked
synced 2024-10-02 17:00:47 +00:00
Write an introduction to the turtle API
It's better at least, I just don't know if it's good.
This commit is contained in:
parent
0f9ddac83c
commit
bed2e0b658
@ -22,7 +22,7 @@ import dan200.computercraft.core.computer.ComputerSide;
|
|||||||
* as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
|
* 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 {@code 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.
|
* polling.
|
||||||
*
|
*
|
||||||
* This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
|
* This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
|
||||||
|
@ -25,10 +25,9 @@ import java.util.Map;
|
|||||||
import java.util.Optional;
|
import java.util.Optional;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The turtle API allows you to control your turtle.
|
* Doc stub. Exists in turtle.lua instead.
|
||||||
*
|
*
|
||||||
* @cc.module turtle
|
* @cc.module turtle
|
||||||
* @cc.since 1.3
|
|
||||||
*/
|
*/
|
||||||
public class TurtleAPI implements ILuaAPI
|
public class TurtleAPI implements ILuaAPI
|
||||||
{
|
{
|
||||||
|
@ -2,13 +2,13 @@
|
|||||||
|
|
||||||
Functions are not actually executed simultaniously, but rather this API will
|
Functions are not actually executed simultaniously, but rather this API will
|
||||||
automatically switch between them whenever they yield (eg whenever they call
|
automatically switch between them whenever they yield (eg whenever they call
|
||||||
@{coroutine.yield}, or functions that call that - eg `os.pullEvent` - or
|
@{coroutine.yield}, or functions that call that - eg @{os.pullEvent} - or
|
||||||
functions that call that, etc - basically, anything that causes the function
|
functions that call that, etc - basically, anything that causes the function
|
||||||
to "pause").
|
to "pause").
|
||||||
|
|
||||||
Each function executed in "parallel" gets its own copy of the event queue,
|
Each function executed in "parallel" gets its own copy of the event queue,
|
||||||
and so "event consuming" functions (again, mostly anything that causes the
|
and so "event consuming" functions (again, mostly anything that causes the
|
||||||
script to pause - eg `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
|
etc) can safely be used in one without affecting the event queue accessed by
|
||||||
the other.
|
the other.
|
||||||
|
|
||||||
|
@ -108,39 +108,48 @@ local function makePagedScroll(_term, _nFreeLines)
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
--- Prints a given string to the display.
|
--[[- Prints a given string to the display.
|
||||||
--
|
|
||||||
-- If the action can be completed without scrolling, it acts much the same as
|
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
|
the bottom of the display. Each press will cause it to scroll down and write a
|
||||||
-- a single line more before prompting again, if need be.
|
single line more before prompting again, if need be.
|
||||||
--
|
|
||||||
-- @tparam string _sText The text to print to the screen.
|
@tparam string text The text to print to the screen.
|
||||||
-- @tparam[opt] number _nFreeLines The number of lines which will be
|
@tparam[opt] number free_lines The number of lines which will be
|
||||||
-- automatically scrolled before the first prompt appears (meaning _nFreeLines +
|
automatically scrolled before the first prompt appears (meaning free_lines +
|
||||||
-- 1 lines will be printed). This can be set to the terminal's height - 2 to
|
1 lines will be printed). This can be set to the cursor's y position - 2 to
|
||||||
-- always try to fill the screen. Defaults to 0, meaning only one line is
|
always try to fill the screen. Defaults to 0, meaning only one line is
|
||||||
-- displayed before prompting.
|
displayed before prompting.
|
||||||
-- @treturn number The number of lines printed.
|
@treturn number The number of lines printed.
|
||||||
-- @usage
|
|
||||||
-- local width, height = term.getSize()
|
@usage Generates several lines of text and then prints it, paging once the
|
||||||
-- textutils.pagedPrint(("This is a rather verbose dose of repetition.\n"):rep(30), height - 2)
|
bottom of the terminal is reached.
|
||||||
function pagedPrint(_sText, _nFreeLines)
|
|
||||||
expect(2, _nFreeLines, "number", "nil")
|
local lines = {}
|
||||||
|
for i = 1, 30 do lines[i] = ("This is line #%d"):format(i) end
|
||||||
|
local message = table.concat(lines, "\n")
|
||||||
|
|
||||||
|
local width, height = term.getCursorPos()
|
||||||
|
textutils.pagedPrint(message, height - 2)
|
||||||
|
]]
|
||||||
|
function pagedPrint(text, free_lines)
|
||||||
|
expect(2, free_lines, "number", "nil")
|
||||||
-- Setup a redirector
|
-- Setup a redirector
|
||||||
local oldTerm = term.current()
|
local oldTerm = term.current()
|
||||||
local newTerm = {}
|
local newTerm = {}
|
||||||
for k, v in pairs(oldTerm) do
|
for k, v in pairs(oldTerm) do
|
||||||
newTerm[k] = v
|
newTerm[k] = v
|
||||||
end
|
end
|
||||||
newTerm.scroll = makePagedScroll(oldTerm, _nFreeLines)
|
|
||||||
|
newTerm.scroll = makePagedScroll(oldTerm, free_lines)
|
||||||
term.redirect(newTerm)
|
term.redirect(newTerm)
|
||||||
|
|
||||||
-- Print the text
|
-- Print the text
|
||||||
local result
|
local result
|
||||||
local ok, err = pcall(function()
|
local ok, err = pcall(function()
|
||||||
if _sText ~= nil then
|
if text ~= nil then
|
||||||
result = print(_sText)
|
result = print(text)
|
||||||
else
|
else
|
||||||
result = print()
|
result = print()
|
||||||
end
|
end
|
||||||
@ -214,32 +223,45 @@ local function tabulateCommon(bPaged, ...)
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
--- Prints tables in a structured form.
|
--[[- Prints tables in a structured form.
|
||||||
--
|
|
||||||
-- This accepts multiple arguments, either a table or a number. When
|
This accepts multiple arguments, either a table or a number. When
|
||||||
-- encountering a table, this will be treated as a table row, with each column
|
encountering a table, this will be treated as a table row, with each column
|
||||||
-- width being auto-adjusted.
|
width being auto-adjusted.
|
||||||
--
|
|
||||||
-- When encountering a number, this sets the text color of the subsequent rows to it.
|
When encountering a number, this sets the text color of the subsequent rows to it.
|
||||||
--
|
|
||||||
-- @tparam {string...}|number ... The rows and text colors to display.
|
@tparam {string...}|number ... The rows and text colors to display.
|
||||||
-- @usage textutils.tabulate(colors.orange, { "1", "2", "3" }, colors.lightBlue, { "A", "B", "C" })
|
@since 1.3
|
||||||
-- @since 1.3
|
@usage
|
||||||
|
|
||||||
|
textutils.tabulate(
|
||||||
|
colors.orange, { "1", "2", "3" },
|
||||||
|
colors.lightBlue, { "A", "B", "C" }
|
||||||
|
)
|
||||||
|
]]
|
||||||
function tabulate(...)
|
function tabulate(...)
|
||||||
return tabulateCommon(false, ...)
|
return tabulateCommon(false, ...)
|
||||||
end
|
end
|
||||||
|
|
||||||
--- Prints tables in a structured form, stopping and prompting for input should
|
--[[- Prints tables in a structured form, stopping and prompting for input should
|
||||||
-- the result not fit on the terminal.
|
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.
|
input should the whole output not fit on the display.
|
||||||
--
|
|
||||||
-- @tparam {string...}|number ... The rows and text colors to display.
|
@tparam {string...}|number ... The rows and text colors to display.
|
||||||
-- @usage textutils.tabulate(colors.orange, { "1", "2", "3" }, colors.lightBlue, { "A", "B", "C" })
|
@see textutils.tabulate
|
||||||
-- @see textutils.tabulate
|
@see textutils.pagedPrint
|
||||||
-- @see textutils.pagedPrint
|
@since 1.3
|
||||||
-- @since 1.3
|
|
||||||
|
@usage Generates a long table, tabulates it, and prints it to the screen.
|
||||||
|
|
||||||
|
local rows = {}
|
||||||
|
for i = 1, 30 do rows[i] = {("Row #%d"):format(i), math.random(1, 400)} end
|
||||||
|
|
||||||
|
textutils.tabulate(colors.orange, {"Column", "Value"}, colors.lightBlue, table.unpack(rows))
|
||||||
|
]]
|
||||||
function pagedTabulate(...)
|
function pagedTabulate(...)
|
||||||
return tabulateCommon(true, ...)
|
return tabulateCommon(true, ...)
|
||||||
end
|
end
|
||||||
@ -692,11 +714,11 @@ saving in a file or pretty-printing.
|
|||||||
@throws If the object contains a value which cannot be
|
@throws If the object contains a value which cannot be
|
||||||
serialised. This includes functions and tables which appear multiple
|
serialised. This includes functions and tables which appear multiple
|
||||||
times.
|
times.
|
||||||
@see cc.pretty.pretty An alternative way to display a table, often more suitable for
|
@see cc.pretty.pretty_print An alternative way to display a table, often more
|
||||||
pretty printing.
|
suitable for pretty printing.
|
||||||
@since 1.3
|
@since 1.3
|
||||||
@changed 1.97.0 Added `opts` argument.
|
@changed 1.97.0 Added `opts` argument.
|
||||||
@usage Pretty print a basic table.
|
@usage Serialise a basic table.
|
||||||
|
|
||||||
textutils.serialise({ 1, 2, 3, a = 1, ["another key"] = { true } })
|
textutils.serialise({ 1, 2, 3, a = 1, ["another key"] = { true } })
|
||||||
|
|
||||||
|
@ -1,6 +1,51 @@
|
|||||||
--- The turtle API allows you to control your turtle.
|
--[[- Turtles are a robotic device, which can break and place blocks, attack mobs, and move about the world. They have
|
||||||
--
|
an internal inventory of 16 slots, allowing them to store blocks they have broken or would like to place.
|
||||||
-- @module turtle
|
|
||||||
|
## Movement
|
||||||
|
Turtles are capable of moving throug the world. As turtles are blocks themselves, they are confined to Minecraft's grid,
|
||||||
|
moving a single block at a time.
|
||||||
|
|
||||||
|
@{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!
|
||||||
|
:::
|
||||||
|
|
||||||
|
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 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.
|
||||||
|
:::
|
||||||
|
|
||||||
|
## 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}
|
||||||
|
functions.
|
||||||
|
|
||||||
|
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
|
||||||
|
accessible by accessing the `"left"` or `"right"` peripheral.
|
||||||
|
|
||||||
|
[Turtle Graphics]: https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics"
|
||||||
|
|
||||||
|
@module turtle
|
||||||
|
@since 1.3
|
||||||
|
]]
|
||||||
|
|
||||||
if not turtle then
|
if not turtle then
|
||||||
error("Cannot load turtle API on computer", 2)
|
error("Cannot load turtle API on computer", 2)
|
||||||
@ -8,9 +53,8 @@ end
|
|||||||
|
|
||||||
--- The builtin turtle API, without any generated helper functions.
|
--- The builtin turtle API, without any generated helper functions.
|
||||||
--
|
--
|
||||||
-- Generally you should not need to use this table - it only exists for
|
-- @deprecated Historically this table behaved differently to the main turtle API, but this is no longer the base. You
|
||||||
-- backwards compatibility reasons.
|
-- should not need to use it.
|
||||||
-- @deprecated
|
|
||||||
native = turtle.native or turtle
|
native = turtle.native or turtle
|
||||||
|
|
||||||
local function addCraftMethod(object)
|
local function addCraftMethod(object)
|
||||||
|
@ -224,8 +224,8 @@ end
|
|||||||
|
|
||||||
--- Display a document on the terminal.
|
--- Display a document on the terminal.
|
||||||
--
|
--
|
||||||
-- @tparam Doc doc The document to render
|
-- @tparam Doc doc The document to render
|
||||||
-- @tparam[opt] number ribbon_frac The maximum fraction of the width that we should write in.
|
-- @tparam[opt=0.6] number ribbon_frac The maximum fraction of the width that we should write in.
|
||||||
local function write(doc, ribbon_frac)
|
local function write(doc, ribbon_frac)
|
||||||
if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
|
if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
|
||||||
expect(2, ribbon_frac, "number", "nil")
|
expect(2, ribbon_frac, "number", "nil")
|
||||||
@ -286,8 +286,8 @@ end
|
|||||||
|
|
||||||
--- Display a document on the terminal with a trailing new line.
|
--- Display a document on the terminal with a trailing new line.
|
||||||
--
|
--
|
||||||
-- @tparam Doc doc The document to render.
|
-- @tparam Doc doc The document to render.
|
||||||
-- @tparam[opt] number ribbon_frac The maximum fraction of the width that we should write in.
|
-- @tparam[opt=0.6] number ribbon_frac The maximum fraction of the width that we should write in.
|
||||||
local function print(doc, ribbon_frac)
|
local function print(doc, ribbon_frac)
|
||||||
if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
|
if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
|
||||||
expect(2, ribbon_frac, "number", "nil")
|
expect(2, ribbon_frac, "number", "nil")
|
||||||
@ -297,10 +297,10 @@ end
|
|||||||
|
|
||||||
--- Render a document, converting it into a string.
|
--- Render a document, converting it into a string.
|
||||||
--
|
--
|
||||||
-- @tparam Doc doc The document to render.
|
-- @tparam Doc doc The document to render.
|
||||||
-- @tparam[opt] number width The maximum width of this document. Note that long strings will not be wrapped to
|
-- @tparam[opt] number width The maximum width of this document. Note that long strings will not be wrapped to fit
|
||||||
-- fit this width - it is only used for finding the best layout.
|
-- this width - it is only used for finding the best layout.
|
||||||
-- @tparam[opt] number ribbon_frac The maximum fraction of the width that we should write in.
|
-- @tparam[opt=0.6] number ribbon_frac The maximum fraction of the width that we should write in.
|
||||||
-- @treturn string The rendered document as a string.
|
-- @treturn string The rendered document as a string.
|
||||||
local function render(doc, width, ribbon_frac)
|
local function render(doc, width, ribbon_frac)
|
||||||
if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
|
if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
|
||||||
@ -483,7 +483,7 @@ Controls how various properties are displayed.
|
|||||||
- `function_args`: Show the arguments to a function if known (`false` by default).
|
- `function_args`: Show the arguments to a function if known (`false` by default).
|
||||||
- `function_source`: Show where the function was defined, instead of
|
- `function_source`: Show where the function was defined, instead of
|
||||||
`function: xxxxxxxx` (`false` by default).
|
`function: xxxxxxxx` (`false` by default).
|
||||||
@tparam[opt] number ribbon_frac The maximum fraction of the width that we should write in.
|
@tparam[opt=0.6] number ribbon_frac The maximum fraction of the width that we should write in.
|
||||||
|
|
||||||
@usage Display a table on the screen.
|
@usage Display a table on the screen.
|
||||||
|
|
||||||
|
@ -171,7 +171,7 @@ end
|
|||||||
local current_section = nil
|
local current_section = nil
|
||||||
local offset = 0
|
local offset = 0
|
||||||
|
|
||||||
--- Find the currently visible seciton, or nil if this document has no sections.
|
--- Find the currently visible section, or nil if this document has no sections.
|
||||||
--
|
--
|
||||||
-- This could potentially be a binary search, but right now it's not worth it.
|
-- This could potentially be a binary search, but right now it's not worth it.
|
||||||
local function find_section()
|
local function find_section()
|
||||||
|
Loading…
Reference in New Issue
Block a user