Added docs
This commit is contained in:
parent
5ed5343691
commit
d130532fb1
|
|
@ -0,0 +1,2 @@
|
|||
node_modules/
|
||||
src/.vuepress/dist
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
pids
|
||||
logs
|
||||
node_modules
|
||||
npm-debug.log
|
||||
coverage/
|
||||
run
|
||||
dist
|
||||
.DS_Store
|
||||
.nyc_output
|
||||
.basement
|
||||
config.local.js
|
||||
basement_dist
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,19 @@
|
|||
{
|
||||
"name": "movescript-docs",
|
||||
"version": "0.0.1",
|
||||
"description": "Documentation for Movescript and associated libraries.",
|
||||
"main": "index.js",
|
||||
"authors": {
|
||||
"name": "Andrew Lalis",
|
||||
"email": "andrewlalisofficial@gmail.com"
|
||||
},
|
||||
"repository": "https://github.com/andrewlalis/movescript/Movescript",
|
||||
"scripts": {
|
||||
"dev": "vuepress dev src",
|
||||
"build": "vuepress build src"
|
||||
},
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"vuepress": "^1.5.3"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
<template>
|
||||
<p class="demo">
|
||||
{{ msg }}
|
||||
</p>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Hello this is <Foo-Bar>'
|
||||
}
|
||||
}
|
||||
}
|
||||
</script>
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
<template>
|
||||
<p class="demo">This is another component</p>
|
||||
</template>
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
<template>
|
||||
<p class="demo">
|
||||
{{ msg }}
|
||||
</p>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
msg: 'Hello this is <demo-component>'
|
||||
}
|
||||
}
|
||||
}
|
||||
</script>
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
const { description } = require('../../package')
|
||||
|
||||
module.exports = {
|
||||
/**
|
||||
* Ref：https://v1.vuepress.vuejs.org/config/#title
|
||||
*/
|
||||
title: 'Movescript Docs',
|
||||
/**
|
||||
* Ref：https://v1.vuepress.vuejs.org/config/#description
|
||||
*/
|
||||
description: description,
|
||||
|
||||
/**
|
||||
* Extra tags to be injected to the page HTML `<head>`
|
||||
*
|
||||
* ref：https://v1.vuepress.vuejs.org/config/#head
|
||||
*/
|
||||
head: [
|
||||
['meta', { name: 'theme-color', content: '#3eaf7c' }],
|
||||
['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
|
||||
['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }]
|
||||
],
|
||||
|
||||
/**
|
||||
* Theme configuration, here is the default theme configuration for VuePress.
|
||||
*
|
||||
* ref：https://v1.vuepress.vuejs.org/theme/default-theme-config.html
|
||||
*/
|
||||
themeConfig: {
|
||||
repo: '',
|
||||
editLinks: false,
|
||||
docsDir: '',
|
||||
editLinkText: '',
|
||||
lastUpdated: false,
|
||||
nav: [
|
||||
{
|
||||
text: 'Movescript',
|
||||
link: '/guide/movescript/',
|
||||
},
|
||||
{
|
||||
text: 'Itemscript',
|
||||
link: '/guide/itemscript/'
|
||||
},
|
||||
{
|
||||
text: 'GitHub',
|
||||
link: 'https://github.com/andrewlalis/movescript'
|
||||
}
|
||||
],
|
||||
sidebar: {
|
||||
'/guide/movescript/': [
|
||||
{
|
||||
title: 'Movescript Module',
|
||||
collapsable: false,
|
||||
children: [
|
||||
'',
|
||||
'spec',
|
||||
'settings'
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* Apply plugins，ref：https://v1.vuepress.vuejs.org/zh/plugin/
|
||||
*/
|
||||
plugins: [
|
||||
'@vuepress/plugin-back-to-top',
|
||||
'@vuepress/plugin-medium-zoom',
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
/**
|
||||
* Client app enhancement file.
|
||||
*
|
||||
* https://v1.vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements
|
||||
*/
|
||||
|
||||
export default ({
|
||||
Vue, // the version of Vue being used in the VuePress app
|
||||
options, // the options for the root Vue instance
|
||||
router, // the router instance for the app
|
||||
siteData // site metadata
|
||||
}) => {
|
||||
// ...apply enhancements for the site.
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 3.3 KiB |
|
|
@ -0,0 +1,8 @@
|
|||
/**
|
||||
* Custom Styles here.
|
||||
*
|
||||
* ref：https://v1.vuepress.vuejs.org/config/#index-styl
|
||||
*/
|
||||
|
||||
.home .hero img
|
||||
max-width 450px!important
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
/**
|
||||
* Custom palette here.
|
||||
*
|
||||
* ref：https://v1.vuepress.vuejs.org/zh/config/#palette-styl
|
||||
*/
|
||||
|
||||
$accentColor = #3eaf7c
|
||||
$textColor = #2c3e50
|
||||
$borderColor = #eaecef
|
||||
$codeBgColor = #282c34
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
sidebar: auto
|
||||
---
|
||||
|
||||
# Config
|
||||
|
||||
## foo
|
||||
|
||||
- Type: `string`
|
||||
- Default: `/`
|
||||
|
||||
## bar
|
||||
|
||||
- Type: `string`
|
||||
- Default: `/`
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# About Movescript
|
||||
|
||||
Movescript is a set of libraries that remove the prohibitive tedium of writing turtle code by hand. It consists of the following modules:
|
||||
|
||||
| Module | Description |
|
||||
| --------------------------- | -------------------------------------------------------------------- |
|
||||
| [Movescript](./movescript/) | A small scripting language to simplify repetitive turtle tasks. |
|
||||
| [Itemscript](./itemscript/) | A collection of helper functions that simplify inventory management. |
|
||||
|
||||
These modules are intended to be used with the Turtle robots provided by the [CC:Tweaked](https://tweaked.cc/) mod for Minecraft.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Getting Started
|
||||
|
||||
> This page is a work-in-progress.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# Getting Started
|
||||
|
||||
The Movescript module provides a simple interface for executing *movescript sources* as turtle programs. A *movescript source* is a compact set of instructions that can be interpreted by the Movescript module to tell the turtle to behave according to them.
|
||||
|
||||
## Installing
|
||||
|
||||
To install this module, run the following command from your turtle's console:
|
||||
|
||||
```shell
|
||||
wget https://raw.githubusercontent.com/andrewlalis/movescript/main/src/movescript.lua movescript.lua
|
||||
```
|
||||
|
||||
And then use it in a script:
|
||||
|
||||
```lua
|
||||
local ms = require("movescript")
|
||||
ms.run("5F2R2U5F2D2L")
|
||||
```
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
# Settings
|
||||
|
||||
As you've seen in some examples, scripts can be run via `movescript.run("3F")`. But under the hood, every script is run using a table of settings that help to define what to do in certain situations to allow for predictable, safe behavior.
|
||||
|
||||
| Setting | Type | Description | Default Value |
|
||||
| ------- | ---- | ----------- | ------------- |
|
||||
| `debug` | boolean | If true, extra debug information will be printed as your script is run. | `false` |
|
||||
| `safe` | boolean | Tells whether the turtle should move safely; safe movement means repeating a movement until we confirm that it succeeds. | `true` |
|
||||
| `destructive` | boolean | Tells whether the turtle should destroy blocks in its movement path in order to complete its actions. | `false` |
|
||||
| `fuels` | table of strings | A list of names of items that the turtle should consider to be fuel, in case it needs to refuel itself. | `{"minecraft:coal", "minecraft:charcoal"}` |
|
||||
|
||||
## User-Defined
|
||||
|
||||
If you'd like to change how your script is executed, you can pass your own settings table to `movescript.run`, like in the example below:
|
||||
|
||||
```lua
|
||||
local ms = require("movescript")
|
||||
local mySettings = {
|
||||
debug = true,
|
||||
safe = true,
|
||||
destructive = true,
|
||||
fuels = {"minecraft:charcoal", "minecraft:spruce_log"}
|
||||
}
|
||||
ms.run("10F", mySettings)
|
||||
```
|
||||
|
||||
Please make sure that if you decide to customize settings, that you thoroughly read and understand what they mean. Failure to do so could lead to an inoperable turtle, or at worst, unintended destruction.
|
||||
|
||||
## Updating Defaults
|
||||
While not recommended, you are also able to override the default settings for Movescript once, and have them take effect globally to all scripts run by the module. To do so, simply modify the `defaultSettings` table included in the movescript module.
|
||||
|
||||
```lua
|
||||
-- Example: Enable debug for all scripts that will be executed.
|
||||
local ms = require("movescript")
|
||||
ms.defaultSettings.debug = true
|
||||
|
||||
ms.run("3F")
|
||||
ms.run("3B")
|
||||
```
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# Script Specification
|
||||
|
||||
Every movescript must follow the outline defined in this specification.
|
||||
|
||||
Each script consists of zero or more **instructions**, separated by zero or more whitespace characters.
|
||||
|
||||
## Instructions
|
||||
|
||||
An instruction consists of an optional positive integer number, followed by a required uppercase character, and optionally followed by a series of lowercase characters.
|
||||
|
||||
```lua
|
||||
-- The regex used to parse instructions.
|
||||
instruction = string.find(script, "%W*(%d*%u%l*)%W*")
|
||||
```
|
||||
|
||||
Each instruction can be split into two parts: the **action**, and the **count**. The action is the textual part of the instruction, and maps to a turtle behavior. The count is the optional numerical part of the instruction, and defaults to `1` if no number is provided.
|
||||
|
||||
## Actions
|
||||
|
||||
The following table lists all actions that are available in Movescript. Attempting to invoke an action not listed here will result in an error that will terminate your script.
|
||||
|
||||
| Action | Description | Needs Fuel |
|
||||
| ------ | ------------------------------------------------ | ---------- |
|
||||
| `U` | Move up. | ✅ |
|
||||
| `D` | Move down. | ✅ |
|
||||
| `L` | Turn left. | ❌ |
|
||||
| `R` | Turn right. | ❌ |
|
||||
| `F` | Move forward. | ✅ |
|
||||
| `B` | Move backward. | ✅ |
|
||||
| `P` | Place the selected item in front of the turtle. | ❌ |
|
||||
| `Pu` | Place the selected item above the turtle. | ❌ |
|
||||
| `Pd` | Place the selected item below the turtle. | ❌ |
|
||||
| `A` | Attack in front of the turtle. | ❌ |
|
||||
| `Au` | Attack above the turtle. | ❌ |
|
||||
| `Ad` | Attack below the turtle. | ❌ |
|
||||
|
||||
For example, if we want our turtle to go forward 3 times, instead of writing `turtle.forward()` 3 times, we can just do the following:
|
||||
|
||||
```lua
|
||||
local ms = require("movescript")
|
||||
ms.run("3F")
|
||||
```
|
||||
|
||||
### Fueled Actions
|
||||
|
||||
Some actions require fuel to execute successfully. Movescript will compute the fuel required to perform the upcoming behaviors in its script, and if needed, it will automatically refuel itself using any items matching the list of fuels defined in [settings](settings.md).
|
||||
|
||||
If the turtle isn't able to attain the required fuel from its own inventory, it will pause execution of the script and prompt the operator to insert fuel into the turtle's inventory before it will resume.
|
||||
|
||||
> Note: If the `safe` setting is set to `false`, no fuel checks will be done. The operator is responsible for ensuring the turtle will have enough fuel to complete its actions.
|
||||
|
||||
## Examples
|
||||
|
||||
The following snippets show a few example scripts, along with a description of what they'll do.
|
||||
|
||||
`3F2U1L` - Move forward 3 blocks, then up 2 blocks, and turn left.
|
||||
|
||||
`B2RAd` - Move back 2 blocks, then turn right twice, and then attack downward.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
home: true
|
||||
heroImage: /images/icon_256.png
|
||||
tagline: Documentation for Movescript and its associated libraries.
|
||||
actionText: Get Started →
|
||||
actionLink: /guide/
|
||||
features:
|
||||
- title: Simple Turtle Control
|
||||
details: Define complex behavior with a compact, easy-to-learn syntax.
|
||||
- title: Safety
|
||||
details: Trust that your script will behave deterministically, and account for possible compromising situations.
|
||||
- title: Helpful Utilities
|
||||
details: Besides movescript, there's also some other utilities to help with item management and structure design.
|
||||
footer: Made by Andrew Lalis
|
||||
---
|
||||
|
|
@ -0,0 +1,97 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
width="32"
|
||||
height="32"
|
||||
viewBox="0 0 8.4666667 8.4666667"
|
||||
version="1.1"
|
||||
id="svg8"
|
||||
inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)"
|
||||
sodipodi:docname="icon.svg"
|
||||
inkscape:export-filename="/home/andrew/Programming/github-andrewlalis/movescript/icon_256.png"
|
||||
inkscape:export-xdpi="768"
|
||||
inkscape:export-ydpi="768">
|
||||
<defs
|
||||
id="defs2" />
|
||||
<sodipodi:namedview
|
||||
id="base"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:zoom="11.313709"
|
||||
inkscape:cx="-11.690042"
|
||||
inkscape:cy="7.6015816"
|
||||
inkscape:document-units="px"
|
||||
inkscape:current-layer="layer1"
|
||||
showgrid="false"
|
||||
units="px"
|
||||
inkscape:window-width="1920"
|
||||
inkscape:window-height="1009"
|
||||
inkscape:window-x="0"
|
||||
inkscape:window-y="0"
|
||||
inkscape:window-maximized="1" />
|
||||
<metadata
|
||||
id="metadata5">
|
||||
<rdf:RDF>
|
||||
<cc:Work
|
||||
rdf:about="">
|
||||
<dc:format>image/svg+xml</dc:format>
|
||||
<dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||
<dc:title />
|
||||
</cc:Work>
|
||||
</rdf:RDF>
|
||||
</metadata>
|
||||
<g
|
||||
inkscape:label="Layer 1"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
transform="translate(0,-288.53333)">
|
||||
<rect
|
||||
y="290.37268"
|
||||
x="2.7418582"
|
||||
height="5.1657028"
|
||||
width="5.1446185"
|
||||
id="rect817"
|
||||
style="opacity:1;fill:#1d1d1d;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1.24491346;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
<rect
|
||||
style="opacity:1;fill:#ffe369;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1.22705293;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
|
||||
id="rect815"
|
||||
width="5.039196"
|
||||
height="5.1235337"
|
||||
x="3.2268009"
|
||||
y="290.01425" />
|
||||
<path
|
||||
style="fill:none;stroke:#818181;stroke-width:1.00188446;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="M 0.63340673,291.25821 H 3.1635472"
|
||||
id="path819"
|
||||
inkscape:connector-curvature="0" />
|
||||
<path
|
||||
inkscape:connector-curvature="0"
|
||||
id="path821"
|
||||
d="M 0.63340673,292.82901 H 3.1635472"
|
||||
style="fill:none;stroke:#818181;stroke-width:1.00188446;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
|
||||
<path
|
||||
style="fill:none;stroke:#818181;stroke-width:1.00188446;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="M 0.63340673,294.3998 H 3.1635472"
|
||||
id="path823"
|
||||
inkscape:connector-curvature="0" />
|
||||
<rect
|
||||
style="opacity:1;fill:#1d1d1d;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1.00188446;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
|
||||
id="rect825"
|
||||
width="2.0873661"
|
||||
height="0.40060556"
|
||||
x="6.1786313"
|
||||
y="290.56247" />
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.3 KiB |
|
|
@ -14,6 +14,13 @@ local t = turtle
|
|||
-- The movescript module. Functions defined within this table are exported.
|
||||
local movescript = {}
|
||||
|
||||
movescript.defaultSettings = {
|
||||
debug = false,
|
||||
safe = true,
|
||||
destructive = false,
|
||||
fuels = {"minecraft:coal", "minecraft:charcoal"}
|
||||
}
|
||||
|
||||
local function debug(msg, settings)
|
||||
if settings and settings.debug then
|
||||
print("[MS] " .. msg)
|
||||
|
|
@ -39,17 +46,10 @@ function t.detectBack()
|
|||
return result
|
||||
end
|
||||
|
||||
-- The default settings to apply to any robot movement, if none are specified.
|
||||
local defaultMovementSettings = {
|
||||
safe = true,
|
||||
destructive = false,
|
||||
fuels = {"minecraft:coal", "minecraft:charcoal"}
|
||||
}
|
||||
|
||||
local function goDirection(dirFunction, digFunction, detectFunction, settings)
|
||||
settings = settings or defaultMovementSettings
|
||||
safe = settings.safe or defaultMovementSettings.safe
|
||||
destructive = settings.destructive or defaultMovementSettings.destructive
|
||||
settings = settings or movescript.defaultSettings
|
||||
safe = settings.safe or movescript.defaultSettings.safe
|
||||
destructive = settings.destructive or movescript.defaultSettings.destructive
|
||||
local success = dirFunction()
|
||||
if not safe then return end
|
||||
while not success do
|
||||
|
|
@ -111,7 +111,7 @@ local actionMap = {
|
|||
-- Returns a boolean indicating if at least one piece of fuel was consumed.
|
||||
local function refuelAll(settings)
|
||||
debug("Refueling...", settings)
|
||||
local fuels = settings.fuels or defaultMovementSettings.fuels
|
||||
local fuels = settings.fuels or movescript.defaultSettings.fuels
|
||||
local refueled = false
|
||||
for slot = 1, 16 do
|
||||
local item = t.getItemDetail(slot)
|
||||
|
|
@ -134,7 +134,7 @@ local function refuelToAtLeast(requiredLevel, settings)
|
|||
"[MS] Fuel level is too low. Level: " .. t.getFuelLevel() .. ". Required: " .. requiredLevel ..
|
||||
". Please add some of the following fuels:"
|
||||
)
|
||||
local fuels = settings.fuels or defaultMovementSettings.fuels
|
||||
local fuels = settings.fuels or movescript.defaultSettings.fuels
|
||||
for _, fuelName in pairs(fuels) do
|
||||
print(" - " .. fuelName)
|
||||
end
|
||||
|
|
@ -152,7 +152,12 @@ local function executeInstruction(instruction, settings)
|
|||
local action = actionMap[instruction.action]
|
||||
if action then
|
||||
debug("Executing action \"" .. instruction.action .. "\" " .. instruction.count .. " times.", settings)
|
||||
if action.needsFuel and instruction.count > t.getFuelLevel() then
|
||||
local shouldRefuel = (
|
||||
(settings.safe or true) and
|
||||
(action.needsFuel) and
|
||||
(instruction.count > t.getFuelLevel())
|
||||
)
|
||||
if shouldRefuel then
|
||||
local fuelRequired = instruction.count
|
||||
refuelToAtLeast(fuelRequired, settings)
|
||||
end
|
||||
|
|
@ -184,7 +189,7 @@ local function parseScript(script, settings)
|
|||
end
|
||||
|
||||
function movescript.run(script, settings)
|
||||
settings = settings or defaultMovementSettings
|
||||
settings = settings or movescript.defaultSettings
|
||||
script = script or ""
|
||||
debug("Executing script: " .. script, settings)
|
||||
local instructions = parseScript(script, settings)
|
||||
Loading…
Reference in New Issue