USAGE_GUIDE.md

249 lines · 6.6 KB

Open raw

Copy & run

wget https://perlytiara.github.io/turtles.tips/raw/programs/perlytiara/tClear/USAGE_GUIDE.md
1# tClear with Chunky Turtle Pairing - Usage Guide
2
3## Overview
4The enhanced tClear system now includes automatic chunky turtle pairing to prevent the main mining turtle from breaking due to chunk unloading. The chunky turtle follows the main turtle and keeps chunks loaded.
5
6## Setup Requirements
7
8### Hardware Requirements
9- **Main Mining Turtle**: Standard mining turtle with pickaxe and wireless modem
10- **Chunky Turtle**: Wireless turtle with wireless modem (no tools needed)
11- **Computer/Control Terminal**: For running tClear_multi.lua (optional)
12
13### Software Requirements
14All files should be installed on both turtles:
15- `tClear.lua` - Main mining program
16- `tClearChunky.lua` - Chunky turtle program
17- `tClear_listener.lua` - Communication handler (for remote operation)
18
19## Setup Instructions
20
21### Step 1: Place Your Turtles
22```
23[Mining] [Chunky] ← Start here
24 ↓ ↓
25 Turtle Turtle
26```
27
28- Place the **mining turtle** at your desired starting position
29- Place the **chunky turtle** one block to the **left** (behind) of the mining turtle
30- Both turtles should have wireless modems attached
31
32### Step 2: Get Turtle IDs
33On each turtle, run:
34```lua
35print(os.getComputerID())
36```
37Note down both IDs for later use.
38
39### Step 3: Install Programs
40Copy all the tClear programs to both turtles:
41- `tClear.lua`
42- `tClearChunky.lua`
43- `tClear_listener.lua`
44
45## Usage Methods
46
47### Method 1: Single Turtle with Chunky Pairing (Recommended)
48
49#### Direct Operation
501. **Start the chunky turtle first:**
51 ```lua
52 tClearChunky
53 ```
54 The chunky turtle will display "Waiting for pairing with master turtle..."
55
562. **Start the main mining turtle:**
57 ```lua
58 tClear [depth] [width] [height] [options]
59 ```
60 Example: `tClear 10 5 3 layerbylayer`
61
623. **The system will automatically:**
63 - Find and pair with the chunky turtle
64 - Begin mining while the chunky turtle follows
65 - Keep chunks loaded throughout the operation
66
67#### Interactive Mode
68Simply run:
69```lua
70tClear
71```
72Follow the on-screen prompts to configure your mining parameters.
73
74### Method 2: Remote Operation with Listeners
75
76#### Setup Listeners
771. **On the mining turtle, start the listener:**
78 ```lua
79 tClear_listener
80 ```
81
822. **On the chunky turtle, start the listener:**
83 ```lua
84 tClear_listener
85 ```
86
87#### Remote Control
88From any computer on the network:
89```lua
90tClear_multi
91```
92Follow the prompts to:
93- Enter turtle IDs
94- Enter chunky turtle IDs (optional)
95- Configure mining parameters
96
97### Method 3: Multi-Turtle Mining
98
99#### Two-Turtle Mining
100Use `tClear_multi.lua` for coordinated mining:
101
1021. **Run the multi-launcher:**
103 ```lua
104 tClear_multi
105 ```
106
1072. **Enter the required information:**
108 - Number of turtles: `2`
109 - Left turtle ID
110 - Right turtle ID
111 - Left chunky turtle ID (optional)
112 - Right chunky turtle ID (optional)
113 - Mining parameters
114
1153. **The system will:**
116 - Start chunky turtles first (if specified)
117 - Coordinate both mining turtles
118 - Divide the work area between them
119
120## Parameters and Options
121
122### Basic Parameters
123- **Depth**: How far forward to mine (must be ≥ 1)
124- **Width**: How wide to mine (cannot be -1, 0, or 1)
125- **Height**: How tall to mine (cannot be 0)
126
127### Advanced Options
128- `layerbylayer` - Mine one layer at a time (safer for lava)
129- `startwithin` - Start inside the mining area
130- `stripmine` - Use for strip mining operations
131
132### Examples
133```lua
134# Basic mining
135tClear 5 3 2
136
137# Layer by layer mining (safer)
138tClear 10 4 3 layerbylayer
139
140# Start within the area
141tClear 8 6 2 startwithin
142
143# Strip mining
144tClear 20 -2 3 stripmine layerbylayer
145```
146
147## How Chunky Pairing Works
148
149### Automatic Discovery
1501. Main turtle broadcasts "find chunky turtle" message
1512. Available chunky turtles respond with their IDs
1523. Main turtle pairs with the first available chunky turtle
153
154### Movement Synchronization
155- Chunky turtle maintains position one block behind (to the left of) main turtle
156- All movements are synchronized (forward, back, up, down, turns)
157- Chunky turtle sends periodic chunk loading signals
158
159### Chunk Loading
160- Chunky turtle sends chunk load signals every 2 seconds
161- Prevents chunks from unloading while mining
162- Eliminates risk of turtle breaking due to chunk unloading
163
164## Troubleshooting
165
166### Common Issues
167
168#### "No chunky turtle found"
169- Ensure chunky turtle is running `tClearChunky` or `tClear_listener`
170- Check that both turtles have wireless modems
171- Verify both turtles are on the same network
172
173#### "No modem found"
174- Attach a wireless modem to the turtle
175- Ensure the modem is properly connected
176
177#### Chunky turtle not following
178- Check rednet communication between turtles
179- Restart both turtles if needed
180- Verify turtle IDs are correct
181
182#### Mining turtle breaks
183- This should no longer happen with chunky pairing
184- If it still occurs, check that chunky turtle is actually following
185- Ensure chunk loading signals are being sent
186
187### Debug Mode
188To enable debug output in chunky turtle, edit `tClearChunky.lua`:
189```lua
190local blnDebugPrint = true
191```
192
193### Manual Recovery
194If pairing fails:
1951. Stop both turtles (Ctrl+T)
1962. Restart chunky turtle first: `tClearChunky`
1973. Then restart mining turtle: `tClear [parameters]`
198
199## Best Practices
200
201### Placement
202- Always place chunky turtle behind (to the left of) mining turtle
203- Ensure clear path for chunky turtle to follow
204- Avoid placing near lava or dangerous areas
205
206### Operation
207- Start chunky turtle before main turtle
208- Use layer-by-layer mode for large operations
209- Monitor fuel levels on both turtles
210
211### Maintenance
212- Keep both turtles fueled
213- Ensure wireless modems have good signal
214- Clean up any debris that might block chunky turtle
215
216## Advanced Features
217
218### Custom Positioning
219The chunky turtle follows the main turtle but you can modify the relative position by editing:
220```lua
221local chunkyPosition = {x = -1, y = 0, z = 0, facing = 0} -- Behind main turtle
222```
223
224### Timing Adjustments
225Modify chunk loading interval in `tClearChunky.lua`:
226```lua
227local chunkLoadingInterval = 2 -- seconds between signals
228```
229
230### Multiple Chunky Turtles
231For very large operations, you can deploy multiple chunky turtles by modifying the pairing logic in `tClear.lua`.
232
233## Safety Notes
234
235- Always test in a safe area first
236- Keep backup fuel for both turtles
237- Monitor the operation, especially for large excavations
238- The chunky turtle is vulnerable while following - protect it from mobs
239- Ensure adequate inventory space for both turtles
240
241## Support
242
243If you encounter issues:
2441. Check this guide first
2452. Verify all files are properly installed
2463. Test with simple parameters first
2474. Check turtle fuel and inventory space
2485. Ensure proper turtle placement and network connectivity
249