A Python-based graphical emulator for ComputerCraft: Tweaked turtles with 3D visualization
- 3D Isometric View - Beautiful isometric rendering with smooth graphics
- 360° Camera Rotation - Rotate view with middle mouse button
- Interactive Console - Full command-line interface with output scrolling
- Complete Turtle API - All CC: Tweaked turtle commands implemented
- 16-Slot Inventory - Full inventory management system
- Filesystem Navigation - ls, cd, mkdir, rm commands and more
- Lua Script Support - Write and execute Lua automation scripts
- Block Inspection - Detailed block detection and comparison
- Block Interaction - Place, dig, detect blocks in real-time
- Fuel System - Realistic fuel consumption and management
- Multiple Console Modes - Docked, floating, or hidden console (F5/F6)
- Manual Block Placement - Interactive block placement panel (F3)
- Terrain Generation - Generate random terrain chunks (F2)
- Settings Panel - Customize view, animation speed, and toggles (F1)
- Animated Movement - Configurable animation delay (100-2000ms)
- Multiple Block Types - Stone, dirt, grass, ore, and custom blocks
- Real-time Status - Position, fuel, direction, and inventory display
- Interactive UI - Click-and-drag camera rotation
- Python 3.9 or higher
- Pygame 2.0 or higher
# Install dependencies
pip install pygame
# Run the emulator
python main.py| Key | Action |
|---|---|
| F1 | Toggle Settings Panel |
| F2 | Generate Random Terrain |
| F3 | Toggle Block Placement Panel |
| F4 | Clear World |
| F5 | Toggle Console (Docked) |
| F6 | Toggle Console Mode (Docked ↔ Floating) |
| F11 | Toggle Fullscreen |
| ESC | Exit Emulator |
| Action | Function |
|---|---|
| Middle Mouse + Drag | Rotate camera 360° |
| Mouse Wheel | Zoom in/out |
| Left Click | Interact with UI elements |
| Right Click | Place/remove blocks (in placement mode) |
forward / fd - Move forward one block
back / bk - Move backward one block
up - Move up one block
down - Move down one block
turnleft / tl - Turn left 90°
turnright / tr - Turn right 90°
dig - Dig block in front
digup - Dig block above
digdown - Dig block below
place - Place block in front
placeup - Place block above
placedown - Place block below
detect - Check if block is in front
detectup - Check if block is above
detectdown - Check if block is below
inspect - Get detailed info about block ahead
inspectup - Get detailed info about block above
inspectdown - Get detailed info about block below
compare - Compare block ahead to selected slot
compareup - Compare block above to selected slot
comparedown - Compare block below to selected slot
select [slot] - Select inventory slot (1-16)
getitemcount [slot] - Get item count in slot
getitemdetail [slot] - Get detailed item info
transferto [slot] [count] - Transfer items between slots
compareto [slot] - Compare items in two slots
ls / dir [path] - List files and directories
cd [path] - Change directory (use ".." for parent)
mkdir [name] - Create new directory
rm [file] - Remove/delete file
pwd - Print working directory
edit [file] - Show hint to edit file externally
pos / position - Show position and facing direction
fuel - Show current fuel level
refuel [amount] - Refuel turtle (default: 1)
scripts - List available Lua scripts
run [script] - Execute a Lua script
help - Show all commands
clear / cls - Clear console output
reboot / restart - Reboot computer and reset turtle
shutdown - Shut down computer
poweron - Power on computer
kill - Emergency stop all processes
exit / quit - Exit emulator
Create .lua files in the scripts/ folder:
-- My Script
-- Comments start with --
turtle.forward()
turtle.forward()
turtle.turnright()
turtle.dig()
turtle.place()| Script | Description |
|---|---|
| square.lua | Draws a 4×4 square path |
| digline.lua | Digs a straight 5-block line |
| tower.lua | Builds a 5-block tall tower |
| mine.lua | Creates a 2×2 mining tunnel |
| circle.lua | Circular movement pattern |
| explore.lua | Random exploration path |
> scripts
Available scripts:
- square.lua
- tower.lua
- mine.lua
> run square
# Watch the turtle execute commands with animation!| Type | Color | Description |
|---|---|---|
| block | Brown | Generic block |
| stone | Gray | Stone material |
| dirt | Brown | Dirt block |
| grass | Green | Grass block |
| ore | Silver | Ore deposits |
- Show Grid - Toggle reference grid
- Show Coordinates - Toggle coordinate markers
- Show Fuel - Toggle fuel display
- Show Inventory - Toggle inventory display
- Zoom Slider - Adjust 3D view zoom (10-70)
- Animation Time - Control animation speed (100-2000ms)
- Reset to Defaults - Restore default settings
- Horizontal rotation angle
- Vertical tilt angle
┌─────────────────────────────────────────────────────────────┐
│ Status Panel Settings (F1) │
│ Position: (0, 0, 0) │
│ Direction: NORTH │
│ Fuel: 1000/20000 │
│ Selected Slot: 1 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 3D Isometric View │
│ (Middle Mouse to Rotate) │
│ │
│ │
├─────────────────────────────────────────────────────────────┤
│ Console (F5: Toggle | F6: Float/Dock) │
│ > forward │
│ Success │
│ > _ │
└─────────────────────────────────────────────────────────────┘
> forward
Success
> turnright
Turned right
> position
Position: X=1, Y=0, Z=0, Facing=EAST> select 1
Selected slot 1
> place
Success
> up
Success
> place
Success> run square
# Turtle automatically executes all commands with animation
# Watch it draw a perfect square! Y (Up)
↑
|
|
0─────→ X (East)
/
/
↙
Z (South)
- X-axis: East (+) / West (-)
- Y-axis: Up (+) / Down (-)
- Z-axis: South (+) / North (-)
main.py → Entry point
├── emulator.py → Pygame graphics & UI
├── computer.py → Command processor & filesystem
├── turtle.py → Core turtle API implementation
└── scripts/ → Lua automation scripts
- Camera Rotation: Hold middle mouse and drag for perfect viewing angles
- Test Environment: Press F2 to generate terrain for mining scripts
- Fuel Up: Use
refuel 50before running long scripts - Fresh Start: Press F4 to clear world and start over
- Scrolling: Use mouse wheel to scroll through long outputs
- Block Variety: Use placement panel (F3) to create diverse terrain
- Animation Speed: Adjust in settings (F1) to see scripts faster/slower
- Organize Scripts: Use
cdandmkdirto organize your Lua files - Block Detection: Use
inspectto identify unknown blocks - Floating Console: Press F6 for a movable console window
- Lua script execution
- Manual block placement
- Terrain generation
- Multiple block types
- Settings panel with customization
- 360° camera rotation
- Full inventory system (16 slots)
- Filesystem commands
- Block inspection & comparison
- Animated turtle movement
- Floating/docked console modes
- Animation speed control
- Reset to defaults
- Drop/suck item commands
- Attack/combat commands
- Crafting support
- Save/load world state
- Advanced Lua parsing (loops, functions, variables)
- Wireless/modem communication simulation
- Peripheral simulation (disk drives, monitors)
- Redstone integration
- Multi-turtle support
MIT License - Feel free to use and modify!
Contributions welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation
Made with ❤️ for ComputerCraft fans
Happy turtle automating!